User manual

From SpareMiNT Wiki
Jump to: navigation, search

Contents

What is FreeMiNT?

FreeMiNT is a free, open-source operating system for 16/32bit Atari computers and clones. It is compatible with TOS, but adds a lot of new functionality not available in any other TOS-compatible operating system.

  • Allows any number of GEM (with XaAES running) and TOS programs to run concurrently.
  • Has memory protection to improve security and stability.
  • Has built in network support and drivers for all existing networking hardware.
  • Multi-user support.
  • Has a wide array of system extensions to ease porting of unix programs.


How does FreeMiNT work?

FreeMiNT is a TSR that replace the GEMDOS-part of TOS. It also replace most of BIOS and XBIOS. The ROM AES can be replaced by the FreeMiNT kernel module XaAES or by some other AES like N.AES or MyAES.

FreeMiNT implements all features from TOS. It also adds a lot of it's own, like networking, multiuser support, process control and most importantly the ability to run several programs concurrently.


Installation

See the installation guide for details on how to install FreeMiNT on your computer. Get the latest version from the FreeMiNT downloads.


The unified filesystem (U:\)

The unified filesystem is similar to the root directory found in virtually all variants of unix. The unified filesystem is assigned the drive letter U. All drives are available as directories under this "drive", e.g. "u:\c\" or "u:\a\". In addition to the drives the following directories are present in this filesystem by default:

  • proc - every running program (or "process") has it's own file in this directory. The file suffix in proc is the the process ID. You can manipulate some aspects of the process through this file, e.g. killing the process by deleting it's entry in "u:\proc\".
  • kern - similar to u:\proc, kern is a newer system compatible to Linux' procfs to ease porting of unix programs.
  • dev - devices like the serial port or keyboard can be accessed through their files in this directory. Most device drivers (*.xdd files) are also accessed through this directory.
  • pipe - pipes are always created in this directory.
  • shm - shared memory is accessed through this directory.
  • ram - FreeMiNT's internal RAM-disk.

The main purpose of the unified filesystem is to make it easier to port unix applications. mintlib emulates the unix root directory on top of the unified filesystem.


Memory protection

A feature of FreeMiNT that is new to TOS-like systems is the concept of protecting the program's memory space from unauthorized "intruders". An "intruder" is another program that tries to access other programs' memory, either by design or because of a bug. This makes memory protection an extremely useful feature for two reasons:

  • Increased stability. A program that went berzerk due to a bug is prevented from doing damage to other programs.
  • As a developer tool. Memory protection will tell you when you forgot to initialize a pointer ;)

More about memory protection.

However, some programs needs to access other programs' memory due to how they're designed. GEM programs and accessories often interacts this way. Not all programs that does this are aware of the existence of memory protection, so you need to configure FreeMiNT to allow memory protection to be "bypassed" in certain circumstances.

More about Fine-tuning and troubleshooting memory protection.

Technical: Memory protection is implemented using the MMU, which means that you need a 68030 or newer with MMU. 68000-based computers can not use memory protection.

Memory protection works on a per-process basis. By default all programs are loaded into private memory, and all memory allocated by the program is also private memory. This behaviour can be modified in two ways:

  1. The header of any executable file contains amongst other some mode bits that specify the type of protection to be used for all memory belonging to this program.
  2. The program itself can specify the type of protection for allocated memory by allocating the memory using Mxalloc().


The MiNT System Folder

FreeMiNT expects to find a folder named "mint" in the root of your boot-drive. This folder contains the various config-files, modules and tools required by MiNT.

By default, this is be located in subfolders named after the kernel version number. For example FreeMiNT 1.17.0 will look for the subfolder "1-17-0", and if this folder doesn't exist it will load the config file and modules located in "mint". This allows the user to keep separate system folders for different versions of the kernel.

So if your boot-drive is C: and you boot FreeMiNT 1.17.0, it will look for the following folders:

  • c:\mint\1-17-0\
  • c:\mint\

It will load it's config-files and modules from the first folder it finds.

Exception: If you're using a beta or alpha version of the kernel, it will look for a special "-beta" folder. It will have the suffix "-cur", e.g. "1-18-cur", for anything compiled from the FreeMiNT cvs (like daily builds from freemint.org). This will allow you to have one system folder for the latest beta/cvs version, and one for the release version.

Warning: since version 1.16.0 FreeMiNT ignores "multitos" folder in the root of your boot-drive (done for backward compatibility with MultiTOS).


Configuration

The Boot Menu

Hold down the left SHIFT key while booting FreeMiNT to enter the boot menu. There are nine options in this menu, all of them can be toggled by pressing the key next to the menu entry.

  1. Start up FreeMiNT: Would normally be set to yes (for obvious reasons). If you don't use a boot manager, you can use this feature when you don't want/need to boot FreeMiNT.
  2. Load external XFS: Normally set to yes. If set to no, filesystem drivers are not loaded. You will then not be able to access other filesystems than FAT and FAT32.
  3. Load external XDD. Normally set to yes. If set to no, no device drivers will be loaded.
  4. Execute AUTO PRGs: Normally set to yes. If set to no, FreeMiNT will not execute programs located after FreeMiNT itself in the autofolder.
  5. Memory protection: If yes then Memory Protection will be enabled (recommended).
  6. Init step by step: If set to yes, booting will be paused after each step until you press a key. Useful when debugging the boot sequence.
  7. Debug/trace level: Applies only to debug kernels. Sets debug level.
  8. Debug output dev.: Applies only to debug kernels. Select debug output device.
  9. Remember settings: If set to yes, the selections you've made in the boot menu will be saved to mint.ini.

The boot delay (the amount of time FreeMiNT waits for the user to enter the boot menu) can not be set in the boot menu. If you want to change this delay, you must edit mint.ini with a text editor.


The Configuration Files

There are three configuration files in FreeMiNT. All of them are located in the system folder. These files are only read when the system starts, so for any changes to take effect the system must be restarted.

mint.ini
This file is automatically created by FreeMiNT, and contains the settings in the boot menu. It can be manually edited, but any comments will be deleted the next time FreeMiNT saves it's boot-settings.
mint.cnf
This file contains a set of commands and variables that determines how FreeMiNT will behave when started. If you want to tune your system this file is where you start.
xaaes\xaaes.cnf
Similar to mint.cnf, this file contains settings relevant to XaAES.

Keyboard layout

If your language is not directly supported by TOS, or if you use non-standard keyboard (e.g. a PC- or Mac-keyboard) you will probably need to modify the keyboard layout in FreeMiNT to match the physical layout of your keyboard. Traditionally this has been done by a small auto folder TSR that installs a new keymap. This will also work with FreeMiNT, but a safer way of remapping the keyboard is to let FreeMiNT do it by loading a keyboard layout file during boot. If the file keyboard.tbl is present in the system folder, it will be used as the default keyboard layout in FreeMiNT.

This has a few advantages over the traditional TSR-solution:

  • Clean and safe.
  • The ALT-key can be used as a modifier.
  • On the Milan and under ARAnyM, the AltGr-key can also be used as a modifier.
  • Deadkeys are supported, very handy if your language has more than a handful of accented characters.

Keyboard tables can be generated with the mktbl utility. If you prefer a GEM-tool, KeyEdit can create, edit and install FreeMiNT keyboard tables.

Since kernel 1-17-0, keyboard.tbl files for several different keyboard layouts (ready to use) can be found in the FreeMiNT build.

Filesystems and filesystem drivers

Filesystems are implemented as kernel modules. Filesystem kernel modules can be identified by the .xfs file extension. Usually you just have to place the filesystem kernel module into the system folder to enable support for an specific file system.

Currently supported filesystems:

When you partition a hard drive for use with GEM, all partitions are usually set up with the FAT filesystem. If you want to use other filesystems, you have to do two things:

  1. Copy the required filesystem driver to the system folder.
  2. Initialize at least one partition with the new filesystem.

Case sensitivity

File and Path name Lengths


VFAT and FAT32

Support for these FAT extensions is integrated in the kernel, no separate driver is necessary. VFAT is an extension to the FAT filesystem that allows long filenames to be used. This can be used on all existing FAT partitions, one needs to allow VFAT extension for each drive in mint.cnf though. It's not recommended to use VFAT-aware drives later in TOS as this can lead to filesystem corruption.

FAT32 is similar to FAT (FAT12/FAT16), but can handle much bigger files and partitions. You need to initialize at least one partition using mkfatfs or HD-Driver. The partition type must be set to F32 using a partitioning tool to use this filesystem. FAT32 partitions can not be accessed from TOS.

VFAT/FAT32 in FreeMiNT is fully compatible with Windows VFAT/FAT32, so if you use a harddisk driver that understands PC-partitioned disks you can directly attach a disk formatted under Windows as FAT32 to Atari and read/write files from/to it. MagiC offers similar option but it's much slower with accessing such drive.

Limits

   maximum partition size
   FAT16                      : 2 GB
   FAT32                      : > 16 TB
   maximum file size          : 2 GB
   block size                 : 512 byte - 32 kb
   physical blocksize must be smaller or
   equal to logical blocksize : yes


ext2

This filesystem is used by linux. It has several advantages over FAT, and if you want to install e.g. EasyMiNT it's mandatory. This partition type is required if you intend to install SpareMiNT (RPM), GentooMiNT, or build software that uses advanced make and configure scripts. To use this filesystem perform the following steps:

  1. Copy ext2.xfs to the system folder.
  2. Use a partitioning tool to set the partition type for the desired partition to LNX or RAW.
  3. Create the filesystem with mke2fs. Simple Example: mke2fs -L label /d (where d is the Disk Letter)
  4. Reboot.

Limits

   maximum partition size     : > 16 TB
   maximum file size          : 2 GB
   block size                 : 1, 2, 4 kb
   physical blocksize must be smaller or
   equal to logical blocksize : yes


minix

As the name suggests this is the filesystem used by Minix. It has the same key features as ext2, like symbolic and hard links, case sensitive filenames and access control bits, but also some severe limitations. This type of partition can be used with old software that require filenames to be in uppercase 8.3 formats (like Hisoft Debugger). It also supports long file name and the use of lowercase. This filesystem is made obsolete by ext2.

  1. Copy minix.xfs to the system folder.
  2. Use a partitioning tool to set the partition type for the desired partition to MIX or RAW.
  3. Create the filesystem with minit.
  4. Reboot.

Limits

   maximum partition size      : 2 GB
   maximum file size           : 2 GB
   block size                  : 1 kb
   physical blocksize must be smaller or
   equal to logical blocksize  : yes


nfs

A networking filesystem. Copy nfs.xfs to the system folder to enable it. This filesystem is used to mount NFS or Samba shared folders over a network.


Device drivers

Device drivers are kernel modules that provides the operating system and/or user applications with an interface to a specific piece of hardware. The drivers are located in the system folder. Currently there are two types of hardware drivers:


Hardware drivers

These drivers are recognized by their *.xdd filename extension. One driver usually supports one specific piece of hardware, and installs a device for it in the u:\dev directory. This device can then be accessed by user programs. It is advisable to only enable the drivers for installed hardware. To disable a driver, rename the filename extension to something else than .xdd.

The following device drivers are a part of the FreeMiNT project:

  • audiodev.xdd - /dev/audio for all Ataris.
  • dsp56k.xdd - Falcon DSP Device driver.
  • flop_raw.xdd - Raw floppy access.
  • lp.xdd - Parallel interface driver.
  • mfp.xdd - MFP Serial Port driver, for systems having MFP serial ports (ST, Mega ST, Mega STE, Hades, FireBee).
  • scc.xdd - SCC Serial Port driver, for systems having SCC serial ports (Mega STE, Falcon, TT).
  • uart.xdd - 16550 UART Serial port driver (Milan).
  • xconout2.xdd - implements u:/dev/xconout2. This must be installed if you use TosWin2's console window.
  • dummy.xdd - Just a test driver, no need to install.
  • inet4.xdd - TCP/IP interface. This is an exception from the other drivers. It does not provide a hardware driver directly, but implements the TCP/IP networking protocol.


Network hardware drivers

These drivers are recognized by their .xif filename extension. They are loaded by the inet4.xdd hardware driver, and provides driver routines for various networking hardware. It is advisable to only enable the drivers for installed hardware. To disable a driver, rename the filename extension to something else than .xif.

The following network hardware drivers are included in the FreeMiNT project:

  • fec.xif - Network driver for the Firebee built-in ethernet port.
  • ethernat.xif - Network Driver for EtherNAT hardware.
  • de600.xif - Driver for the DE600 ROMport ethernet adapter.
  • lance.xif
  • pamsdma.xif
  • biodma.xif - Driver for the BioData ACSI ethernet adapter.
  • riebl*.xif - Suite of drivers for the various Riebl ethernet adapters.
  • rtl8012.xif - Driver for the Genius ROMport ethernet adapter.
  • scsilink.xif - Driver for Daynaport SCSI ethernet adapter.
  • nfeth.xif - Network driver for ARAnyM.
  • slip.xif - Driver providing SLIP and PPP over serial links.
  • plip.xif - PLIP driver for the parallel port. Allows two Ataris to be networked over the printer port. NB! This PLIP protocol is not compatible with the PLIP protocol as implemented under Linux.

Third party network drivers.

System extensions

MiNTnet

gluestik is currently supplied in FreeMiNT distribution archives, under the folder "tools". It is a gateway that allows StiK/Sting applications to use networking.

XaAES

XaAES is a FreeMiNT kernel module which replaces the AES. The documentation is available here.


Time management

FreeMiNT understands the concept of timezones and Daylight Saving Time (DST). These are optional features and is described in the FreeMiNT time management article.


Special considerations

On stock computers you can run FreeMiNT without any additions. However, accelerated computers, clones or virtual machines often needs some additional tools or special considerations to run FreeMiNT.


Tips & tricks

  • Unlike TOS, FreeMiNT doesn't require patch programs at all. FreeMiNT replaces TOS, and bugs are fixed in FreeMiNT itself. All such patch programs (like serial port enhancers, cookie jar extenders, hard disk caches etc) must be avoided when running FreeMiNT.
  • In general, be restrictive with resident programs (TSR) and system enhancements; If you really need them (e.g. NVDI or graphics cards drivers), it's preferable to start them BEFORE FreeMiNT.
  • To save memory, reduce the caches of HDDriver to a minimum. FreeMiNT has it's own, much better, unified cache management. The HDDriver caches are not used at all under FreeMiNT. To increase the FreeMiNT buffer cache use the mint.cnf directive 'CACHE'.
  • Don't ever use wdialog.prg. wdialog is only TOS/MagiC compatible. XaAES has wdialog routines built-in, for N.AES you can use the wdialog replacement N.DIALOG.
  • Don't use Freedom. Freedom is only TOS/MagiC compatible.
Personal tools
Resources