GEMDOS

Overview

The TOS File System

Each drive connected to an Atari system is given a unique alphabetic identifier which is used to identify it. Drive 'A' is reserved for the first available floppy disk drive (usually internal) and drive 'B' for the second floppy disk drive. If only one floppy drive exists, two letters will still be reserved and GEMDOS will treat drive 'B' as a pseudo-drive and request disk swaps as necessary. This feature is automatically handled by GEMDOS and is transparent to the application.

Drives 'C' through 'P' are available for use by hard disk drives. One letter is assigned per hard drive partition so a multiple-partition drive will be assigned multiple letters. MultiTOS extends drive letter assignments to 'Z' drive. Drive 'U' is a special drive reserved for MultiTOS and is unavailable for assignment.

To access a file, a complete path specification must be composed of the drive letter, directory name(s), and filename. A file named 'TEST.PRG' located in the 'SYSTEM' directory on drive 'C' would have a path specification like the following:

C:\SYSTEM\TEST.PRG

The drive letter is the first character followed by a colon. Each directory and subdirectory is surrounded by backslashes. If 'TEST.PRG' were located in the root directory of 'C' the path specification would be:

C:\TEST.PRG

New files should be created with Fcreate(). When a file is successfully created a positive file handle is returned by the call. That handle is what is used to identify the file for all future operations until the file is closed. After a file is closed its handle is invalidated.

File and record locking allow portions or all of a file to be locked against access from another computer over a network or another process in the same system.

Several special file handles are available for access through the standard Fopen()/Fread()/Fwrite() calls. They are as follows:

Name	Handle	Filename	Device
GSH_BIOSCON	0xFFFF	CON:	Console (screen). Special characters such as the carriage return, etc. are interpreted.
GSH_BIOSAUX	0xFFFE	AUX:	Modem (serial port). This is the ST-compatible port for machines with more than one.
GSH_BIOSPRN	0xFFFD	PRN:	Printer (attached to the Centronics Parallel port).
GSH_BIOSMIDIIN	0xFFFC		Midi In
GSH_BIOSMIDIOUT	0xFFFB		Midi Out
GSH_CONIN	0x00	-	Standard Input (usually directed to GSH_BIOSCON)
GSH_CONOUT	0x01	-	Standard Output (usually directed to GSH_BIOSCON)
GSH_AUX	0x02	-	Auxillary (usually directed to GSH_BIOSAUX)
GSH_PRN	0x03	-	Printer (usually directed to GSH_BIOSPRN)
None	0x04	-	Unused
None	0x05	-	Unused
None	0x06 and up	User-Specified	User Process File Handles

Input and output to a file may be redirected to an alternate file handle. For instance you may redirect the console output of a TOS process to the printer.

Memory Management

GEMDOS Processes

GEMDOS Vectors

GEMDOS reserves eight system interrupt vectors (of which only three are used) for various system housekeeping. The BIOS function Setexc() should be used to redirect these vectors when necessary. The GEMDOS vectors are as follows:

Name	Setexc() Vector Number	Usage
VEC_TIMER	0x0100	Timer Tick Vector: This vector is jumped through 50 times per second to maintain the time-of-day clock and accomplish other system housekeeping. A process intercepting this vector does not have to preserve any registers but should jump through the old vector when completed. Heavy use of this vector can severly affect system performance. Return from this handler with RTS.
VEC_CRITICALERR	0x0101	Critical Error Handler: This vector is used by the BIOS to service critical alerts (an Rwabs() disk error or media change request). When called, the WORD at 4(sp) is a GEMDOS error number. On return, D0.L should contain 0x0001000 to retry the operation, 0 to ignore the error, or 0xFFFFFFxx to return an error code (xx). D3-D7 and A3-A6 must be preserved by the handler. Return from this handler with RTS.
VEC_PROCTERM	0x0102	Process Terminate Vector: This vector is called just prior to the termination of a process ended with ctrl-c. Return from this handler with RTS.
-	0x103-0x0107	Currently unused.

MiNT

MiNT is Now TOS (MiNT) is the extension to GEMDOS that allows GEMDOS to multitask under MultiTOS. MiNT also provides memory protection (on a 68030 or higher) to protect an errant process from disturbing another.

Processes

Each system process has a file entry in the 'U:\PROC' directory. The filename given a process in this directory is the basename for the file (without extension) with an extension consisting of the MiNT process identifier. The MINIWIN.PRG application might have an entry named 'MINIWIN.003'.

The file size listed corresponds to the amount of memory the process is using. The time and date stamp contains the length of time the process has been executing as if it were started on Jan. 1st, 1980 at midnight. The file attribute bits tell special information about a process as follows:

Name	Attribute Byte	Meaning
PROC_RUN	0x00	The process is currently running.
PROC_READY	0x01	The process is ready to run.
PROC_TSR	0x02	The process is a TSR.
PROC_WAITEVENT	0x20	The process is waiting for an event.
PROC_WAITIO	0x21	The process is waiting for I/O.
PROC_EXITED	0x22	The process has been exited but not yet released.
PROC_STOPPED	0x24	The process was stopped by a signal.

MiNT contains a number of built-in devices and also supports loadable device drivers. Current versions of MiNT may contain any of the following devices:

Device Filename	Device
CENTR	Centronics Parallel Port
MODEM1	Modem Port 1
MODEM2	Modem Port 2
SERIAL1	Serial Port 1
SERIAL2	Serial Port 2
MIDI	MIDI ports
PRN	PRN: device (usually the Centronics Parallel Port)
AUX	AUX: device (usually the RS232 Port)
CON	Current Terminal
TTY	Current Terminal (same as CON)
STDIN	Current File Handle 0 (standard input)
STDOUT	Current File Handle 1 (standard output)
STDERR	Current File Handle 2 (standard error)
CONSOLE	Physical Console (keyboard/screen)
MOUSE	Mouse (system use only)
NULL	NULL device
AES_BIOS	AES BIOS Device (system use only)
AES_MT	AES Multitasking Device (system use only)

Each of the assigned members of this structure should point to a valid routine that provides the named operation on the device. The routine must preserve registers D2-D7 and A2-A7 returning its completion code in D0. No operating system TRAPs should be called from within these routines, however, using the vector tables provided in the kerinfo structure returned from the Dcntl() call, GEMDOS and BIOS calls may be used. The specific function that each routine is responsible for is as follows:

Member	Meaning
open	This routine is called by the MiNT kernel after a FILEPTR structure has been created for a file determined to be associated with the device. The routine should perform whatever initialization is necessary and exit with a standard GEMDOS completion code.This routine is responsible for validating the sharing mode and other file flags to verify that the file may be legally opened and should respond with an appropriate error code if necessary.
write	This routine should write bytes number of BYTEs from buf to the file specified in FILEPTR. If the file pointer has the O_APPEND bit set, the kernel will perform an lseek() call to the end of the file prior to calling this function. If the lseek()/write() series of calls does not guarantee that data will be written at the end of a file associated with your device, this function must ensure that the data specified is actually written at the end of the file.This function should return with a standard GEMDOS error code or the actual number of BYTEs written to the file when complete.
read	This routine should read bytes number of BYTEs from the file specified in FILEPTR and place them in the buffer buf. This function should return with a standard GEMDOS error code or the actual number of bytes read by the routine.
lseek	This routine should move the file position pointer to the appropriate location in the file as specified by the parameter where in relation to the seek mode whence. Seek modes are the same as with Fseek(). The routine should return a GEMDOS error code or the absolute new position from the start of the file if successful.
ioctl	This routine is called from the system's perspective as Fcntl() and is used to perform file system/device specific functions. At the very least, your device should support FIONREAD, FIONWRITE, and the file/record locking modes of Fcntl(). The arg parameter of Fcntl() is passed as buf.
datime	This routine is used to read or modify the date/time attributes of a file. timeptr is a pointer to two LONGs containing the time and date of the file respectively. These LONGs should be used to set the file date and time if rwflag is non-zero or filled in with the file's creation date and time if rwflag is 0.This function should return with a standard GEMDOS error code or E_OK (0) if successful.
close	This routine is used by the kernel to close an open file. Be aware that if f->links is non-zero, additional processes still have valid handles to the file. If f->links is 0 then the file is really being closed. pid specifies the process closing the file and may not necessarily be the same as the process that opened it.Device drivers should set the O_LOCK bit on f->flag when the F_SETLK or F_SETLKW ioctl() call is made. This bit can be tested for when a file is closed and all locks on all files associated with the same physical file owned by process pid should be removed. If the file did not have any locks created on it by process pid, then no locks should be removed.This routine should return with a standard GEMDOS error code or E_OK (0) if successful.
select	This routine is called when a call to Fselect() names a file handled by this device. If mode is O_RDONLY then the select is for reading, otherwise, if mode is O_WRONLY then it is for writing. If the user Fselect()'s for both reading and writing then two calls to this function will be made.The routine should return 1L if the device is ready for reading or writing (as appropriate) or it should return 0L and arrange to 'wake up' process proc when I/O becomes possible. This is usually accomplished by calling the wakeselect() member function of the kernel structure. Note that the value in proc is not the same as a PID and is actually a pointer to a PROC structure private to the MiNT kernel.
unselect	This routine is called when a device waiting for I/O should no longer be waited for. The mode and proc parameters are the same as with select(). As with select(), if neither reading nor writing is to be waited for, two calls to this function will be made. This routine should return a standard GEMDOS error code or E_OK (0) if successful.

The FILEPTR structure pointed to by a parameter of each of the above calls is defined as follows:

typedef struct fileptr
{
	WORD 			links;
	UWORD 			flags;
	LONG			pos;
	LONG			devinfo;
	fcookie			fc;
	struct devdrv 	*dev;
	struct fileptr	*next;
} FILEPTR;

The members of FILEPTR have significance as follows:

Member	Meaning
links	This member contains a value indicating the number of copies of this file descriptor currently in existence.
flags	This member contains a bit mask which indicates several attributes (logically OR'ed together) of the file as follows: Name Mask Meaning O_RDONLY 0x0000 File is read-only. O_WRONLY 0x0001 File is write-only. O_RDWR 0x0002 File may be read or written. O_EXEC 0x0003 File was opened to be executed. O_APPEND 0x0008 Writes start at the end of the file. O_COMPAT 0x0000 File-sharing compatibility mode. O_DENYRW 0x0010 Deny read and write access. O_DENYW 0x0020 Deny write access. O_DENYR 0x0030 Deny read access. O_DENYNONE 0x0040 Allow reads and writes. O_NOINHERIT 0x0080 Children cannot use this file. O_NDELAY 0x0100 Device should not block for I/O on this file. O_CREAT 0x0200 File should be created if it doesn't exist. O_TRUNC 0x0400 File should be truncated to 0 BYTEs if it already exists. O_EXCL 0x0800 Open should fail if file already exists. O_TTY 0x2000 File is a terminal. O_HEAD 0x4000 File is a pseudo-terminal "master." O_LOCK 0x8000 File has been locked.
pos	This field is initialized to 0 when a file is created and should be used by the device driver to store the file position pointer.
devinfo	This field is reserved for use between the file system and the device driver and may be used as desired. The exception to this is if the file is a TTY, in which case devinfo must be a pointer to a tty structure.
fc	This is the file cookie for the file as follows: typedef struct f_cookie { FILESYS *fs; UWORD dev; UWORD aux; LONG index; } fcookie;fs is a pointer to the file system structure responsible for this device. dev is a UWORD giving a useful device ID (such as the Rwabs() device number). The meaning of aux is file system dependent. index should be used by file systems to provide a unique means of identifying a file.
dev	This is a pointer to the DEVDRV structure of the device driver responsible for this file.
next	This pointer may be used by device drivers to link copies of duplicate file descriptors to implement file locking or sharing code.

Upon successful return from the Dcntl() call, a pointer to a kerinfo structure will be returned. The kerinfo structure is defined below:

typedef LONG (*Func)();

struct kerinfo
{
	WORD		maj_version;
	WORD		min_version;
	UWORD		default_mode;
	WORD		reserved1;
	
	Func		*bios_tab;
	Func		*dos_tab;

	VOID		(*drvchng)( UWORD dev );

	VOID		(*trace)( char *, ... );
	VOID		(*debug)( char *, ... );
	VOID		(*alert)( char *, ... );
	VOID		(*fatal)( char *, ... );

	VOIDP		(*kmalloc)( LONG size );
	VOID		(*kfree)( VOIDP memptr );
	VOIDP		(*umalloc)( LONG size );
	VOID		(*ufree)( LONG memptr );

	WORD		(*strnicmp)( char *str1, char *str2, WORD maxsrch );
	WORD		(*stricmp)( char *str1, char *str2 );
	char *	(*strlwr)( char *str );
	char *	(*strupr)( char *str );
	WORD		(*sprintf)( char *strbuf, const char *fmtstr, ... );
	
	VOID		(*millis_time)( ULONG ms, WORD *td );
	LONG		(*unixtim)( UWORD time, UWORD date );
	LONG		(*dostim)( LONG unixtime );

	VOID		(*nap)( UWORD n );
	VOID		(*sleep)( WORD que, WORD cond );
	VOID		(*wake)( WORD que, WORD cond );
	VOID		(*wakeselect)( LONG proc );

	WORD		(*denyshare)( FILEPTR *list, FILEPTR *f );
	LOCK *	(*denylock)( LOCK *list, LOCK *new );

	LONG		res2[9];
};

The members of the kerinfo structure are defined as follows:

Member	Meaning
maj_version	This WORD contains the kernel version number.
min_version	This WORD contains the minor kernel version number.
default_mode	This UWORD contains the default access permissions for a file.
reserved1	Reserved.
bios_tab	This is a pointer to the BIOS function jump table. Calling bios_tab[0x00]() is equivalent to calling Getmpb() and is the only safe way from within a device driver or file system.
dos_tab	This is a pointer to the GEMDOS function jump table. Calling dos_tab[0x3D]() is equivalent to calling Fopen() and is the only safe way from within a device driver or file system.
drvchng	This function should be called by a device driver if a media change was detected on the device during an operation. The parameter dev is the BIOS device number of the device.
trace	This function is used to send information messages to the kernel for debugging purposes.
debug	This function is used to send error messages to the kernel for debugging purposes.
alert	This function is used to send serious error messages to the kernel for debugging purposes.
fatal	This function is used to send fatal error messages to the kernel for debugging purposes.
kmalloc	Use this internal heap memory management function to allocate memory.
kfree	Use this internal heap memory management function to free memory allocated with kmalloc().
umalloc	Use this internal heap memory management function to allocate memory and attach it to the current process. The memory will be released automatically when the current process exits.
ufree	Use this internal heap memory management function to allocate memory allocated with ufree().
strnicmp	This function compares maxsrch characters of str1 to str2 and returns a negative value if str1 is lower than str2, a positive value if str1 is higher than str2, or 0 if they are equal.
stricmp	This function compares two NULL terminated strings, str1 to str2, and returns a negative value if str1 is lower than str2, a positive value if str1 is higher than str2, or 0 if they are equal.
strlwr	This function converts all alphabetic characters in str to lower case.
strupr	This function converts all alphabetic characters in str to upper case.
sprintf	This function is the same as the 'C' library sprintf() function except that it will only convert SPRINTF_MAX characters (defined in TOSDEFS.H).
millis_time	This function converts the millisecond time value in ms to a GEMDOS time in td[0] and date in td[1].
unixtim	This function converts a GEMDOS time and date in a UNIX format LONG.
dostim	This function converts a UNIX format LONG time/date value into a GEMDOS time/date value. The return value contains the time in the upper WORD and the date in the lower WORD.
nap	This function causes a delay of n milliseconds.
sleep	This function causes the current process to sleep, placing it on the system que que until condition cond is met.
wake	This function causes all processes in que que, waiting for condition cond, to be woken.
wakeselect	This function wakes a process named by the code proc currently doing a select operation.
denyshare	This function determines whether the sharing mode of f conflicts with any of the files given in the linked list list.
denylock	This function determines whether a new lock new conflicts with any existing lock in the linked list list. The LOCK structure is used internally by the kernel and is defined as follows: typedef struct ilock { FLOCK l; struct ilock *next; LONG reserved[4]; } LOCK;l is the structure actually containing the lock data (as defined in Fcntl()). next is a pointer to the next LOCK structure in the linked list or NULL if this is the last lock. reserved is a pointer to four LONGs currently reserved.
res2	These longwords are reserved for future expansion.

The members of the FILESYS structure are interpreted by MiNT as follows:

Member	Meaning
next	This member is a pointer to the next FILESYS structure in the kernel's linked list. It should be left as NULL.
fsflags	This is a bit mask of flags which define attributes of the file system as follows:Name Mask Meaning FS_KNOPARSE 0x01 Kernel shouldn't do directory parsing (common for networked file systems). FS_CASESENSITIVE 0x02 File system names are case-sensitive (common for Unix compatible file systems). FS_NOXBIT 0x04 Files capable of being read are capable of being executed (present in most file systems).
root	This function is called by the kernel to retrieve a file cookie for the root directory of the drive associated with BIOS device dev. When initializing, the kernel will query each file system, in turn, to determine which file system should handle a particular drive. If your file system recognizes the drive specified by dev it should fill in the fcookie structure as appropriate and return E_OK. If the drive is not compatible with your file system, return an appropriate negative GEMDOS error code (usually EDRIVE).
lookup	This function should translate a file name into a cookie. If the FS_KNOPARSE bit of fsflags is not set, name will be the name of a file in the directory specified by the fcookie dir. If the FS_KNOPARSE bit was set, name will be a path name relative to the specified directory dir.If the file is found, the fcookie structure fc should be filled in with appropriate details and either E_OK or EMOUNT (if name is '..' and dir specifies the root directory) should be returned, otherwise an appropriate error code (like EFILNF) should be returned.A lookup() call with a NULL name or with a name of '.' should always succeed and return a cookie representing the current directory. When creating a file cookie, symbolic links should never be followed.
creat	This function is used by the kernel to instruct the file system to create a file named name in the directory specified by dir with attrib attributes (as defined by Fattrib()) and mode permissions as follows:Name Mask PermissionS_IXOTH 0x0001 Execute permission for all others. S_IWOTH 0x0002 Write permission for all others. S_IROTH 0x0004 Read permission for all others. S_IXGRP 0x0008 Execute permission for processes with same group ID. S_IWGRP 0x0010 Write permission for processes with same group ID. S_IRGRP 0x0020 Read permission for processes with same group ID. S_IXUSR 0x0040 Execute permission for processes with same user ID. S_IWUSR 0x0080 Write permission for processes with same user ID. S_IRUSR 0x0100 Read permission for processes with same user ID. S_ISVTX 0x0200 Unused S_ISGID 0x0400 Alter effective group ID when executing this file. S_ISUID 0x0800 Alter effective user ID when executing this file. S_IFCHR 0x2000 File is a BIOS special file. S_IFDIR 0x4000 File is a directory. S_IFREG 0x8000 File is a regular file. S_IFIFO 0xA000 File is a FIFO. S_IMEM 0xC000 File is a memory region. S_IFLNK 0xE000 File is a symbolic link.If the file is created successfully, the fcookie structure fc should be filled in to represent the newly created file and E_OK should be returned. On an error, an appropriate GEMDOS error code should be returned.
getdev	This function is used by the kernel to identify the device driver that should be used to do file I/O on the file named by fc. The function should return a pointer to the device driver and place a user-defined value in the longword pointed to by devspecial. If the function fails, the function should return and place a negative GEMDOS error code in the longword pointed to by devspecial.
getxattr	This function should fill in the XATTR structure pointed to by xattr with the extended attributes of file fc. If the function succeeds, the routine should return E_OK, otherwise a negative GEMDOS error code should be returned.
chattr	This function is called by the kernel to instruct the file system to change the attributes of file fc to those in attr (with only the low eight bits being signifigant). The function should return a standard GEMDOS error code on exit.
chown	This function is called by the kernel to instruct the file system to change the file fc's group and user ownership to gid and uid respectively. The kernel checks access permissions prior to calling this function so the file system does not have to.
chmode	This function is called by the kernel to instruct the file system to change the access permissions of file fc to those in mode. The mode parameter passed to this function will never contain anything but access permission information (i.e. no file type information will be contained in mode). The call should return a standard GEMDOS error code on exit.
mkdir	This function should create a new subdirectory called name in directory dir with access permissions of mode. The file system should ensure that directories such as '.' and '..' are created and that a standard GEMDOS error code is returned.
rmdir	This function should remove the directory whose name is name and whose cookie is pointed to by dir. This call should allow the removal of symbolic links to directories and return a standard GEMDOS error code.
remove	This function should delete the file named name that resides in directory dir. If more than one 'hard' link to this file exists, then only this link should be destroyed and the file contents should be left untouched. Symbolic links to file fc, however, should be removed. This function should not allow the deletion of directories and should return with a standard GEMDOS error code.
getname	This function should fill in the buffer pointed to by pathname with as many as PATH_MAX (128) characters of the path name of directory dir expressed relatively to directory relto. If relto and dir point to the same directory, a NULL string should be returned.For example, if relto points to directory "\FOO" and dir points to directory "\FOO\BAR\SUB" then pathname should be filled in with "\BAR\SUB".
rename	This function should rename the file oldname which resides in directory olddir to the new name newname which resides in newdir. The file system may choose to support or not support cross-directory renames. The function should return a standard GEMDOS error code. If no renames at all are supported then EINVFN should be returned.
opendir	This function opens directory dirh for reading. The parameter tosflag is a copy of the flags member of the DIR structure as defined below: typedef struct dirstruct { fcookie fc; /* Directory cookie */ UWORD index; /* Index of current entry */ UWORD flags; /* TOS_SEARCH (1) or 0 */ char fsstuff[60]; /* File system dependent */ } DIR;If tosflags (dirstruct.flags) is contains the mask TOS_SEARCH the file system is responsible for parsing the names into something readable by TOS domain applications. The file system should initialize the index and fsstuff members of dirh and return an appropriate GEMDOS error code.
readdir	This function should read the next filename from directory dirh. The fcookie structure fc should be filled in with the details of this file. If dirh->flags does not contain the mask TOS_SEARCH then the filename should be copied into the buffer pointed to by name. If dirh->flags does contain the mask TOS_SEARCH then the first four bytes of name should be treated as a longword and filled in with an index value uniquely identifying the file and the filename should be copied starting at &name[4].In either case, if the filename is longer than namelen, rather than filling in the buffer name, the function should return with ENAMETOOLONG. If this is the last file in the directory, ENMFIL should be returned, otherwise return E_OK.
rewinddir	This function should reset the members of dirh so that any internal pointers point at the first file of directory dirh. This function should return a standard GEMDOS error code.
closedir	This function should clear any allocated memory and clean up any structures used by the search on dirh. This function should return a standard GEMDOS error code.
pathconf	This function should return information about the directory dir based on mode mode. For mode values and return values, see Dpathconf().
dfree	This function should return free space information about the drive directory dir is located on. The format of the buffer pointed to by buf is the same as is used by Dfree().This function should return a standard GEMDOS error code.
writelabel	This function is used to change the volume name of a drive which contains the directory dir. The new name name should be used to write (or rename the volume label). If the write is actually an attempt to rename the label and the file system does not support this function then EACCDN should be returned. If the file system does not support the concept of volume labels then EINVFN should be returned. Otherwise, a return value of E_OK is appropriate.
readlabel	This function should copy the volume label name of the drive on which directory dir is contained in the buffer name. If namelen is less than the size of the volume name, ENAMETOOLONG should be returned. If the concept of volume names is not supported by the file system, EINVFN should be returned. If no volume name was ever created, EFILNF should be returned. Upon successful error of the call, E_OK should be returned.
symlink	This function should create a symbolic link in directory dir named name. The symbolic link should contain the NULL terminated string in to. If the file system does not support symbolic links it should return EINVFN, otherwise a standard GEMDOS error code should be returned.
readlink	This function should copy the contents of symbolic link file into buffer buf. If the length of the contents of the symbolic link is greater than buflen, ENAMETOOLONG should be returned. If the file system does not support symbolic links, EINVFN should be returned. In all other cases, a standard GEMDOS error code should be returned.
hardlink	This function should create a 'hard' link called toname residing in todir from the file named fromname residing in fromdir. If the file system does not support hard links, EINVFN should be returned. Otherwise, a standard GEMDOS error code should be returned.
fscntl	This function performs a file system specific function on a file whose name is name that resides in directory dir. The cmd and arg functions parallel those of Dcntl(). In most cases, this function should simply return EINVFN. If your file system wishes to expose special features to the user through Dcntrl() then your file system should handle them here as it sees fit.
dskchng	This function is used by the kernel to confirm a 'media change' state reported by Mediach(). If the file system agrees that a media change has taken place, it should invalidate any appropriate buffers, free any allocated memory associated with the device, and return 1. The kernel will then invalidate any open files and relog the drive with the root() functions of each installed file system.If a media change has not taken place, simply return a value of 0.
zero	This member is reserved for future expansion and must be set to 0L.

Pipelines

MiNT Debugging

A processes' registers may be modified during tracing using the method as illustrated in the following example:

MiNT may be programmed to output special debugging messages to the debugging device through the use of special system keys. The supported system keys are shown in the table below:

Key Combination	Meaning
ctrl-alt-F1	Increase the system debugging level by one.
ctrl-alt-F2	Decrease the system debugging level by one.
ctrl-alt-F3	Cycle the BIOS output device number used for system debugging messages. This key cycles BIOS devices in the order 1-6-7-8-9-2.
ctrl-alt-F4	Restore debugging output to the console device.
ctrl-alt-F5	Output a memory usage map to the debugging device.
ctrl-alt-F6	Output a list of all system processes to the debugging device.
ctrl-alt-F7	Toggles debug 'logging' off and on. When debug logging is on, a 50-line buffer is maintained which contains recent debugging messages. Each time a new debugging message is output, the entire 50 line buffer is output as well.
ctrl-alt-F8	Outputs the 50-line debug log to the debugging device.
ctrl-alt-F9	Outputs the system memory map to the debugging device. The memory protection flags of each page are shown.
ctrl-alt-F10	Outputs an extended system memory map to the debugging device. The memory protection status, owner's PID, and format of each memory block are output to the debugging device.

CTRL-ALT-F1 and CTRL-ALT-F2 alter the current system debugging level. MiNT supports four debugging levels as follows:

Level	Meaning
0	Only fatal OS errors are reported to the debugging device (this is the default mode).
1	Processor exceptions are output to the debugging device.
2	Processor exceptions and failed system calls are output to the debugging device.
3	Constant MiNT status reports, processor exceptions, and failed system calls are output to the debugging device.

MultiTOS looks for an ASCII text file upon bootup called 'MINT.CNF' which may be used to execute commands or set MiNT variables. The following table illustrates what commands are recognized in the 'MINT.CNF' file:

Command	Example	Meaning
cd	cd c:\multitos	Change the GEMDOS working directory.
echo	echo "Atari Computer Booting..."	Echo a string to the screen.
ren	ren c:\test.prg c:\test.app	Rename a file.
sln	sln c:\level1\level2\level3 u:\deep	Create a symbolic link on drive 'U:'.
alias	alias x: u:\proc	Create an alias drive.
exec	exec c:\sam.prg	Execute a program.

The following MiNT variables may be set in the 'MINT.CNF' file:

Variable	Meaning
INIT	Execute the named TOS program. For example: INIT=c:\multitos\sam.prg
GEM	Execute the named GEM program. For example: GEM=c:\multitos\miniwin.app
CON	Redirect console input and output to the named file. For example: CON=u:\dev\modem1
PRN	Redirect printer output to the named file. For example: PRN=c:\spool.txt
DEBUG_LEVEL	Set the MiNT debugging level (default is 0). For example: DEBUG_LEVEL=1
DEBUG_DEVNO	Set the BIOS device number that MiNT will send debugging messages to. For example: DEBUG_DEVNO=1
SLICES	Set the number of 20ms time slices given to an application at a time (the default is 2). For example: SLICES=3
MAXMEM	Set the maximum amount of memory (in kilobytes) any application can be allocated (the default is unlimited). For example: MAXMEM=8192
BIOSBUF	Enable/Disable Bconout() optimizations. The parameter should be 'Y' to enable or 'N' to disable these optimizations. For example: BIOSBUF=Y

GEMDOS Character Functions

GEMDOS provides a number of functions to communicate on a character basis with the default system devices. Because of irregularities with these calls in some TOS versions, usage of the BIOS functions is usually recommended instead (the BIOS does not support redirection, however).

The GEMDOS character functions are illustrated in the table below:

Device:	Input	Output	Status
con:	Cconin() - Character Cnecin() - No Echo Cconrs() - String	Cconout() - Character Cconws() - String	Cconis() - Input Cconos() - Output
prn:	None	cprnout()	Cprnos()
aux:	Cauxin()	Cauxout()	Cauxis() - Input Cauxos() - Output
N/A	Crawio() and Crawcin()	Crawio()	Cconis() - Input Cconos() - Output

GEMDOS Time & Date Functions

GEMDOS Function Calling Procedure

GEMDOS system functions are called via the TRAP #1 exception. Function arguments are pushed onto the current stack in reverse order followed by the function opcode. The calling application is responsible for correctly resetting the stack pointer after the call.

GEMDOS may utilize registers D0-D2 and A0-A2 as scratch registers and their contents should not be depended upon at the completion of a call. In addition, the function opcode placed on the stack will be modified.

'C' compilers often provide a reusable interface to GEMDOS that allows new GEMDOS calls to be added with a macro as in the following example:

#define Super( a )	gemdos( 0x20, a )

GEMDOS is not guaranteed to be re-entrant and therefore should not be called from an interrupt handler.