This is an old version from the tos.hyp. The new is on GitHub!

11.21 MagiC's XFS-concept

MagiC, just as MultiTOS, enables the incorporation of alternative filesystems (so-called XFSs) and with that the use of long filenames. However, for several reasons a different approach was chosen in MagiC to Atari's solution. This has the unfortunate consequence that the XFS's available for MultiTOS (Minix-XFS, CD-ROM-XFS, ...) cannot be used under MagiC. This chapter describes the following points:

• General remarks
• Make-up of an XFS
• Data structures
• Installation of an XFS
• Kernel functions for an XFS
• Symbolic links

See also: VFAT-XFS in MagiC   MagiC's DFS-concept

11.21.1 General remarks about MagiC's XFS-concept

GEMDOSwas until now the most conservative part of the MagiC operating system. For network drivers, practically all DOS calls, including Pexec, had to be recreated without being able to intervene at a deeper level. In Mag!X 1.x (as in TOS) the DOS was not even reentrant because a statically constructed stack was used.

In MultiTOS/MiNT the problem is circumvented in such a way that a virtual system is laid over the GEMDOS which takes care of all higher management tasks, can incorporate other filesystems and uses GEMDOS only as a dumb filesystem driver. An advantage of this solution is its great flexibility and extendibility, but a decided drawback is the towering overhead when using the 'normal' DOS filesystem. But this is just the one that is utilized most frequently. In addition, the GEMDOS filesystem can gain no functionality, comfort or speed with the use of MiNT, since the old routines only execute with additional overhead. File-system accesses under MiNT are therefore generally not reentrant, i.e., as under MS-Windows, every floppy disk access paralyses the whole computer.

A further property of MiNT is the attempt to undertake functions that all filesystems have in common in the kernel. Although this leaves the filesystem drivers (MiNT-XFSs) compact, due to the Inode-oriented format of the kernel functions an unfavourable structure is forced on the file drivers in some circumstances; in addition, generally many calls of the filesystem driver are required for one DOS call. Finally the MiNT kernel itself is very long, but to a large extent lies fallow as long as no filesystems other than DOS are in use.

Under MagiC a different approach was chosen, which included rewriting all GEMDOS functions from the ground up, including the low-level ones for the sector buffering, and to carve them up into three, four or five layers in which one can intervene from the outside (with loaded- in drivers). A side-effect resulted in an extension of the DOS file system functionality and an additional filesystem on the logical drive U:.

The whole concept inclusive of accesses to the DOS filesystems is reentrant and runs in the background. Thus it is possible to amend files on drive A: without markedly slowing down the computer during floppy disk accesses. Despite this MagiC has till now grown only by 10kB. Compared to MiNT, more functions were offloaded into the file system drivers, and while this makes them longer, it gives them the possibility of executing the functions much more efficiently. Also, the DOS filesystem has become somewhat faster rather than slower.

Although realized completely in Assembler, we are dealing with an object-oriented operating system with virtual functions and multi- level heredity. A file descriptor (FD), as used by the kernel and made available by the XFS, is an object with special data and functions. But the XFS realizes also a derived object with further data fields and functions. Finally the DFS subdriver of the DOS_XFS must in turn accommodate further functions and data in the FD and extrapolate the class further. Things look exactly the same with the DMD (drive medium descriptor). The kernel requires only a few statements, but the lower layers appreciably more, though always different ones.

The layers in detail:

1. The DOS kernel. This lies in MagiC itself and is called directly by user programs via TRAP #1. It contains modules for memory management, for process management and for file management. The latter has the following sublayers:
2. The filesystem (XFS = eXtended File-System). Its construction is basically different from a MiNT-XFS, but fulfills the same purpose. MagiC for Ataris contains only a single XFS, the so- called DOS_XFS; others can be incorporated. The Macintosh version (MagiC Mac) contains a Mac-XFS in addition. Specifically this filesystem again makes use of subdrivers:
   1. A DOS filesystem (DFS) is called up by DOS_XFS. This only contains the file functions, while the directory management is essentially taken on by the DOS_XFS. MagiC contains directly two DFSs. One for drive U:, a second for the FAT filesystems that lie on BIOS drives. More DFSs can be incorporated. The effort for a DFS is appreciably lower than for an XFS, as many functions are performed already by the DOS_XFS. The vital prerequisite is a DOS- conforming directory structure (with 32-bit entries and filenames in the 8+3 format). The kernel itself does not come into contact with the DFS but controls it transparently via the DOS-XFS.
3. The file drivers (MX_DEV), which essentially take care of file reading and writing operations. They are created and managed by the XFS, but with functions such as Fread and Fwrite called directly by the kernel, which accrues extremely low overheads. The DOS_XFS actually contains only one file driver. This handles the updating of the directory at write accesses, for instance, and in turn calls a subdriver (MX_DDEV).
   1. The subdriver MX_DDEV is only called by the DOS file driver of the DOS_XFS filesystem. The user can incorporate custom MX_DDEVs via the directory U:\\DEV. The kernel itself does not come into contact with the subdrivers.

Notes:

• In contrast to MiNT, U:\PROC, U:\DEV etc. are not their own file systems but simply just subdirectories of the DFS for drive U:. Depending on the subdirectory, the U-DFS creates various file- types and -drivers. As the control of the directory is encumbent on the DOS_XFS, write accesses to a workstation, for instance, are logged in the directory by the file date-stamp. This even goes so far that a write access to the root of drive A: will alter the file date-stamp of U:\A automatically.
  
  Devices, pipes and shared memory blocks can be moved, deleted or renamed. Symbolic links can be created in all directories of drive U:; for instance, with 'ln -s U:\CON U:\CONSOLE' one can create an alias for the device file CON. One can also create empty files simply, though not folders since the drive U: has no memory allocated to it.

• In contrats to MiNT, U:\ is not its own special filesystem. One just has to respect that only symbolic links can be created. The directories U:\A etc. are simply symbolic links, which can also be removed or renamed.

• All directories of U: are restricted to 32 entries at present

• The construction of all internal structures and the fast register- based parameter passing and return requires an implementation of all filesystems and drivers to be written in Assembler, at least for most of the functions

• The construction of the MX_DDEV file driver has changed since MagiC V2.10. The sample driver DEV_LPT1 may not be used under MagiC V3.00 and higher. Actually the concepts have stayed the same, only a few constants have changed. A new sample driver is not yet available (at the time this was written).

See also: MagiC's XFS-concept   Test for pipes

11.21.2 The make-up of an XFS

Since the implementation of an XFS can only be performed in Assembler, its description is given in Assembler syntax:

xfs_name:       DS.B      8    /* Name of the filesystem              */
xfs_next:       DS.L      1    /* Next driver                         */
xfs_flags:      DS.L      1    /* Flags, analogous to MiNT            */
xfs_init:       DS.L      1    /* Initialization                      */
xfs_sync:       DS.L      1    /* Synchronization of the filesystem   */
xfs_pterm:      DS.L      1    /* Notifies a program termination      */
xfs_garbcoll:   DS.L      1    /* Garbage collection, or NULL         */
xfs_freeDD:     DS.L      1    /* Releases DD                         */
xfs_drv_open:   DS.L      1    /* Tests/initializes DMD (Mediach)     */
xfs_drv_close:  DS.L      1    /* Forces a disk media change          */
xfs_path2DD:    DS.L      1    /* Returns a DD to a pathname          */
xfs_sfirst:     DS.L      1    /* Searches for first matching file    */
xfs_snext:      DS.L      1    /* Searches for next matching file     */
xfs_fopen:      DS.L      1    /* Opens or creates a file             */
xfs_fdelete:    DS.L      1    /* Deletes a file                      */
xfs_link:       DS.L      1    /* Required for Frename and Flink      */
xfs_xattr:      DS.L      1    /* Required for Fxattr                 */
xfs_attrib:     DS.L      1    /* Required for Fattrib                */
xfs_chown:      DS.L      1    /* Required for Fchown                 */
xfs_chmod:      DS.L      1    /* Required for Fchmod                 */
xfs_dcreate:    DS.L      1    /* Creates a directory                 */
xfs_ddelete:    DS.L      1    /* Deletes a directory                 */
xfs_DD2name:    DS.L      1    /* Returns the absolute pathname       */
xfs_dopendir:   DS.L      1    /* Opens a directory                   */
xfs_dreaddir:   DS.L      1    /* Reads the next directory entry      */
xfs_drewinddir: DS.L      1    /* Sets the dirhandle to 1st entry     */
xfs_dclosedir:  DS.L      1    /* Closes the dirhandle                */
xfs_dpathconf:  DS.L      1    /* Obtains various limits              */
xfs_dfree:      DS.L      1    /* Obtains number of free blocks etc.  */
xfs_wlabel:     DS.L      1    /* Writes the disk name                */
xfs_rlabel:     DS.L      1    /* Reads the disk name                 */
xfs_symlink:    DS.L      1    /* Creates a symbolic link             */
xfs_readlink:   DS.L      1    /* Reads a symbolic link               */
xfs_dcntl:      DS.L      1    /* Required for Dcntl                  */

See also: Make-up of a DFS   MagiC's XFS-concept

11.21.2.1 xfs_attrib

11.21.2.2 xfs_chmod

11.21.2.3 xfs_chown

11.21.2.4 xfs_dclosedir

11.21.2.5 xfs_dcntl

11.21.2.6 xfs_dcreate

11.21.2.7 xfs_ddelete

11.21.2.8 xfs_dfree

11.21.2.9 xfs_DD2name

11.21.2.10 xfs_dopendir

11.21.2.11 xfs_dpathconf

11.21.2.12 xfs_dreaddir

11.21.2.13 xfs_drewinddir

11.21.2.14 xfs_drv_close

11.21.2.15 xfs_drv_open

11.21.2.16 xfs_fdelete

11.21.2.17 xfs_flags

11.21.2.18 xfs_fopen

OM_RPERM   EQU  1   // File is opened for reading
OM_WPERM   EQU  2   // File is opened for writing
OM_EXEC    EQU  4   // File is opened for execution
OM_APPEND  EQU  8   // Write accesses at end (kernel!)
OM_RDENY   EQU  16  // Others may not read at same time
OM_WDENY   EQU  32  // Others may not write at same time
OM_NOCHECK EQU  64  // No check by the kernel

O_CREAT EQU  $200 // Create file, if it doesn't exist
O_TRUNC EQU  $400 // Clear file, if it exists
O_EXCL  EQU  $800 // Don't open file, if it exists

11.21.2.19 xfs_freeDD

11.21.2.20 xfs_garbcoll

11.21.2.21 xfs_init

11.21.2.22 xfs_link

11.21.2.23 xfs_name

11.21.2.24 xfs_next

11.21.2.25 xfs_path2DD

11.21.2.26 xfs_pterm

11.21.2.27 xfs_readlink

11.21.2.28 xfs_rlabel

11.21.2.29 xfs_sfirst

11.21.2.30 xfs_snext

11.21.2.31 xfs_symlink

11.21.2.32 xfs_sync

11.21.2.33 xfs_wlabel

11.21.2.34 xfs_xattr

11.21.3 Data structures for an XFS

When working with an XFS the following data structures are important:

See also: DFS structures   MagiC's XFS-concept

11.21.3.1 The directory descriptor (DD)

The directory descriptors must be created and managed by the XFS. All descriptors that are known to the kernel (i.e. those that are used as a standard path for a process) have a non-zero reference counter. The only exception is the DD for the root directory of a drive; here the reference counter is always 0, irrespective of whether a process has the root directory as a standard directory or not.

For the kernel a DD looks like the following; these entries have to be created by the XFS:

dd_dmd:      DS.L      1    /* 0x00: Pointer to DMD                  */
dd_refcnt:   DS.W      1    /* 0x04: Ref. counter for standard paths */

See also: MagiC's XFS-concept

11.21.3.1.1 dd_dmd

The associated filesystem is found here.

11.21.3.1.2 dd_refcnt

The reference counter. dd_refcnt is used only by the kernel, has to be initialized to 0 by the XFS on creation of a DD (for the root better to 1, see above for xfs_drv_open) and incremented by 1 at each handing over to the kernel (-> xfs_path2DD).

This means that on returning a new DD (which is thus not otherwise referenced by the kernel) xfs_path2DD must set the reference counter to 1.

If the reference counter is non-zero, the kernel has a pointer to this DD and it may in no way be released by the XFS. The kernel decrements the reference counter by 1 each time it no longer requires a DD. If the counter reaches 0 during this, then xfs_freeDD is called. The XFS can then release the DD, or else only at a call of xfs_garbcoll (the garbage collection) or at xfs_drv_close.

Warning: The root may not be released during the lifetime of the mounted filesystem. The root's reference counter should be preset to 1 to prevent it being released with xfs_freeDD.

See also: MagiC's XFS-concept   Data structures for an XFS

11.21.3.2 The directory handle descriptor (DHD)

The directory handles are required for Dopendir/Dclosedir/Drewinddir. Unlike the file descriptors (FDs) the kernel does not hold a list of opened directory handles (DH). When a process terminates, the XFS is called via the function xfs_pterm and must release all DHs created for the process.

The XFS can obtain the owner of a DH with the kernel pointer act_pd. For the kernel a DH looks like the following; these entries have to be created by the XFS:

dhd_dmd:  DS.L   1   /* 0x00: Pointer to DMD  */

See also: MagiC's XFS-concept   DMD

11.21.3.2.1 dhd_dmd

The associated filesystem is found here.

11.21.3.3 The Drive Medium Descriptor (DMD)

The DMD is created by the kernel (!) for each opened drive and also released again if necessary. The XFS stores all data here that it has to memorize for the drive. The following fields are the ones that the kernel requires (the ancestor object from which the XFS derives its XFS-DMD):

d_xfs:      DS.L   1    /* 0x00: The filesystem driver            */
d_drive:    DS.W   1    /* 0x04: Drive number 0..25               */
d_root:     DS.L   1    /* 0x06: Pointer to DD of the root        */
d_biosdev:  DS.W   1    /* 0x0a: BIOS drive, or -1                */
d_driver:   DS.L   1    /* 0x0c: With devcode, defines the medium */
d_devcode:  DS.L   1    /* 0x10: e.g. SCSI target and drive       */
d_dfs:      DS.L   1    /* 0x14: DOS-specific filesystem driver   */

Other XFSs or DFSs enter further data into the DMD. One can envisage the DMD as an object class. A DMD derived for the DOS_XFS only has the additional entry d_dfs. The FAT enters extra data such as the cluster size and the number of sectors.

See also: MagiC's XFS-concept   DD

11.21.3.3.1 d_xfs

The associated filesystem driver (XFS) is found here. It is entered by xfs_drv_open.

11.21.3.3.2 d_drive

d_drive specifies which logical drive ('A' .. 'Z') the filesystem is assigned to. This does not always have to correspond to a BIOS drive. This value is always(!) entered by the kernel when a drive is opened, before an XFS is entered.

11.21.3.3.3 d_root

A pointer to the DD of the root directory can be found here.

11.21.3.3.4 d_biosdev

If dealing with a partition that is handled by BIOS's Rwabs, then the BIOS device number will be found here. Else -1 must be entered here (e.g. for drive U: or a Macintosh partition).

11.21.3.3.5 d_driver

Together with d_devcode, this determines the medium. That means that if d_driver and d_devcode are identical, both drives lie on the same medium, and if the medium is to be ejected then both filesystems have to be locked. With a hard disk partition, d_biosdev is the BIOS drive, d_driver is arbitrary (e.g. pointer to the XHDI structure), d_devcode is the XHDI code of a medium, i.e. SCSI target and device number (one WORD in each case).

11.21.3.3.6 d_devcode

Together with d_driver, this determines the medium. That means that if d_driver and d_devcode are identical, both drives lie on the same medium, and if the medium is to be ejected then both filesystems have to be locked. With a hard disk partition, d_biosdev is the BIOS drive, d_driver is arbitrary (e.g. pointer to the XHDI structure), d_devcode is the XHDI code of a medium, i.e. SCSI target and device number (one WORD in each case).

11.21.3.3.7 d_dfs

This entry is mandatory only for DOS filesystems (i.e. already for a derived object) and contains a pointer to the DFS subdriver.

11.21.3.4 The Disk Transfer Area (DTA) for XFSs

The DTA is used by the old DOS functions Fsfirst and Fsnext, whose clumsy conception by the MS-DOS originators still weighs down the system like a curse. For the kernel the structure looks as follows:

dta_res1:        DS.B    20    /* 0x00: Not used by the kernel   */
dta_drive:       DS.B     1    /* 0x14: Logical drive            */
dta_attribute:   DS.B     1    /* 0x15: Found attribute          */
dta_time:        DS.W     1    /* 0x16: Found time               */
dta_date:        DS.W     1    /* 0x18: Found date               */
dta_len:         DS.L     1    /* 0x1a: Found length             */
dta_name:        DS.B    14    /* 0x1e: Found filename           */

Note: The components dta_attribute to dta_name represent the documented user area; this has to be handled according to GEMDOS specifications.

See also: MagiC's XFS-concept

11.21.3.4.1 xfs_dta_res1

dta_res1 (from XFS) is not used by the kernel. Here the XFS may muck about.

11.21.3.4.2 xfs_dta_drive

xfs_dta_drive contains the associated logical drive (0 corresponds to drive A: etc). With this information the kernel can decide at Fsnext which XFS has to perform the task.

11.21.3.5 The File Descriptor (FD)

The file descriptors must be created and managed by the XFS. All the descriptors that are known to the kernel have a non-zero reference counter. For the kernel an FD looks exactly like a DD, which is why the same data structure is used in the DOS_XFS.

For the kernel an FD looks like the following; these entries have to be created by the XFS:

fd_dmd:      DS.L    1   /* 0x00: Pointer to DMD                       */
fd_refcnt:   DS.W    1   /* 0x04: Reference counter for closing, or -1 */
fd_mode:     DS.W    1   /* 0x06: Open-mode and flags                  */
fd_dev:      DS.L    1   /* 0x08: Pointer to MX_DEV                    */

The class derived from DOS_XFS (a 'DOS-FD') also has the additional fields:

fd_ddev:     DS.L    1    /* 0x0c: Pointer to MX_DDEV                  */
fd_name:     DS.B   11    /* 0x10: DD_FD: Name in internal format      */
fd_attr:     DS.B    1    /* 0x1b: Attribute                           */
fd_owner:    DS.L    1    /* 0x1c: DD_FD: Owner of an FD, or NULL      */
fd_parent:   DS.L    1    /* 0x20: Pointer to the parent DD_FD         */
fd_children: DS.L    1    /* 0x24: DD_FD: List of all children         */
fd_next:     DS.L    1    /* 0x28: Pointer to FDs im same directory    */
fd_multi:    DS.L    1    /* 0x2c: Pointer to FD of the same file      */
fd_multi1:   DS.L    1    /* 0x30: Pointer to first list element       */
fd_fpos:     DS.L    1    /* 0x34: Position of the file pointer        */
fd_dirch:    DS.B    1    /* 0x38: Bit0: 'dirty'                       */
fd_unused:   DS.B    1    /* 0x39: Not used                            */
fd_time:     DS.W    1    /* 0x3a: Time  (8086)                        */
fd_date:     DS.W    1    /* 0x3c: Date (8086)                         */
fd_stcl:     DS.W    1    /* 0x3e: Starting cluster                    */
fd_len:      DS.L    1    /* 0x40: File length in bytes                */
fd_dirpos:   DS.L    1    /* 0x44: Pos. of matching entry in directory */
fd_user1:    DS.L    1    /* 0x48: Available for user allocation       */
fd_user2:    DS.L    1    /* 0x4c: Available for user allocation       */

See also: MagiC's XFS-concept   DMD   MX_DDEV   MX_DEV

11.21.3.5.1 fd_dmd

fd_dmd contains a pointer to the associated filesystem.

11.21.3.5.2 fd_refcnt

The reference counter. This entry is used only by the kernel, has to be decremented by 1 at each dev_close call and initialized (to 1) by xfs_fopen.

A reference counter of -1 signals that the FD may never be released. This is necessary for, say, the device files U:\DEV\CON, U:\DEV\AUX etc. that are always available.

11.21.3.5.3 fd_mode

fd_mode contains the mode, as described for xfs_fopen. If two FDs point to the same file, then the modes have to be compatible. Thanks to the simple MagiC-internal mode notation, a plain rotation and ANDing of the bits is sufficient, e.g.:

  move.w   fd_mode(a0),d1
  btst     #BOM_NOCHECK,d1  ; No check by the XFS?
  bne.b    _opf_nxt         ; Yes, ddev_open checks
  ror.b    #4,d1
  and.b    d0,d1
  bne      opd_eaccdn       ; Conflict: return(EACCDN)

11.21.3.5.4 fd_dev

fd_dev is the pointer to the device driver.

11.21.3.5.5 fd_ddev

Here the DFS has to enter the MX_DDEV (i.e. the device driver) at a dfs_dir2FD call.

11.21.3.5.6 fd_name

Here the name (8+3) is stored in an internal format. The name is valid only when it refers to a subdirectory, and only in a prototype FD, i.e. in fd_multi1. The name of the root is an empty character string.

11.21.3.5.7 fd_attr

Here the file attribute is stored. This is valid only in a prototype FD, i.e. in fd_multi1. From the attribute one can recognize whether the FD represents a directory.

11.21.3.5.8 fd_owner

Here a pointer to the owner of an FD is stored (i.e. a pointer to the basepage). A value of NULL signifies that the FD is not allocated at present.

11.21.3.5.9 fd_parent

This is a chaining pointer to the parent, i.e. to the directory in which the file lies, or the parent directory of a subdirectory. fd_parent is valid only for the prototype FD.

11.21.3.5.10 fd_children

This is a list of all opened files and opened subdirecories. fd_children is valid only for the prototype FD.

11.21.3.5.11 fd_next

This is a pointer to the next FD in the same directory, i.e. the next sibling; this can be an opened file or a subdirectory - in principle these are not differentiated.
fd_next is valid only for the prototype FD.

11.21.3.5.12 fd_multi

If a file is opened several times, then a 'clone' of the prototype FD is created. Most of the FD fields are invalid for this clone; in essence only driver, mode and file position are valid. fd_multi is a chained list, wich is NULL-terminated.

11.21.3.5.13 fd_multi1

This is the associated prototype FD that contains the valid file data. If a file is only opened once, then: fd->fd_multi1 == fd.

11.21.3.5.14 fd_fpos

fd_fpos is the position of the file pointer; it is 0L for a device.

11.21.3.5.15 fd_dirch

Bit 0 of fd_dirch indicates whether a file has been altered and hence on closing the file the directory (fd_parent) has to be updated (does not happen when dealing with a folder). The other bits are reserved and are used in part by the DOS_XFS.

11.21.3.5.16 fd_unused

Unused and reserved.

11.21.3.5.17 fd_time

fd_time is the time of day from the directory entry in Intel format.

11.21.3.5.18 fd_date

fd_date is the date from the directory entry in Intel format.

11.21.3.5.19 fd_stcl

fd_stcl is the starting cluster in Motorola format.

11.21.3.5.20 fd_len

fd_len is the file length in bytes in Motorola format.

11.21.3.5.21 fd_dirpos

fd_dirpos is the position of the associated entry in the parent. It is valid only for the prototype FD.

11.21.3.5.22 fd_user1

Together with fd_user2, 2 LONGwords available for free allocation by the user. The FAT_DFS stores here additional information for fd_fpos, namely the current cluster. Other DFSs can store other data. These fields are valid initially only for the prototype FD, except that on opening (ddev_open) the data are copied explicitly from the prototype FD into the clone.

11.21.3.5.23 fd_user2

Together with fd_user1, 2 LONGwords available for free allocation by the user. The FAT_DFS stores here additional information for fd_fpos, namely the current cluster. Other DFSs can store other data. These fields are valid initially only for the prototype FD, except that on opening (ddev_open) the data are copied explicitly from the prototype FD into the clone.

11.21.3.6 The device driver (MX_DEV)

The device driver is inserted by the XFS into the file descriptor at the opening of a file, and called directly by the kernel. The device driver must make the following functions available:

typedef struct _mx_dev
{
  LONG  (*dev_close)();
  LONG  (*dev_read)();
  LONG  (*dev_write)();
  LONG  (*dev_stat)();
  LONG  (*dev_seek)();
  LONG  (*dev_datime)();
  LONG  (*dev_ioctl)();
  LONG  (*dev_getc)();
  LONG  (*dev_getline)();
  LONG  (*dev_putc)();
} MX_DEV;

See also: MagiC's XFS-concept

11.21.3.6.1 dev_close

11.21.3.6.2 dev_datime

For Fdatime. The file driver installed by DOS_XFS passes the call on to the MX_DDEV subdriver, if the function is supported in the MX_DDEV driver (pointer != NULL), otherwise the function will be performed automatically with the help of the FD data.

Parameters:

11.21.3.6.3 dev_getc

11.21.3.6.4 dev_getline

For line-oriented input. mode as in dev_getc. The return will be the number of characters input without terminatng characters or similar. The file driver installed by DOS_XFS passes the dev_getline call on to the MX_DDEV subdriver if the function is supported in the MX_DDEV driver (pointer != NULL); otherwise the function is implemented auto matically as dev_fread. The line is then terminated with CR and LF;

Parameters:

11.21.3.6.5 dev_ioctl

For Fcntl. The file driver installed by DOS_XFS passes the dev_ioctl call directly to the MX_DDEV subdriver. Only the following functions are handled however: FSTAT and FUTIME. These should also be executed by other XFSs. Every file driver should support FIONREAD and FIONWRITE.

Parameters:

11.21.3.6.6 dev_putc

11.21.3.6.7 dev_read

From the file file, count bytes are read into the buffer buffer. The return is the number of characters actually read. The file driver installed by DOS_XFS passes the dev_read call directly to the MX_DDEV subdriver.

Parameters:

11.21.3.6.8 dev_seek

For Fseek. mode is, as in TOS, 0, 1 or 2. The return value will be the current position of the write/read pointer; device drivers must always return a 0L here. The file driver installed by DOS_XFS passes the dev_seek call directly to the MX_DDEV subdriver.

Parameters:

11.21.3.6.9 dev_stat

typedef struct
{
   union
   {
      void (*unsel) (MAGX_UNSEL *un);
      long status;
   }
   long param;
} MAGX_UNSEL;

11.21.3.6.10 dev_write

To the file file, count bytes are written from the buffer buffer. The return is the number of characters actually written. The file driver installed by DOS_XFS updates the date/timestamp of the file and then passes the dev_write call to the MX_DDEV subdriver.

Parameters:

11.21.4 Installation of an XFS

An XFS is just a program that installs the driver and then terminates itself resident. The installation is performed with:
kernel = Dcntl(KER_INSTXFS, NULL, &myxfs).

The return is a pointer to important kernel functions, or an error- code. The kernel functions can also be inquired for independently of the installation of an XFS, namely with: kernel = Dcntl(KER_GETINFO, NULL, NULL).

The deinstallation of an XFS is not provided for.

11.21.5 Kernel functions for an XFS

MagiCmakes available to the installed XFSs, DFSs or device drivers some kernel information as well as kernel functions. The same register conventions apply for the kernel functions as for the XFS functions, i.e. d0-d2 and a0-a2 may be destroyed. One can obtain a pointer to the structure that contains the kernel functions with:

     kernel = Dcntl (KER_INSTXFS, NULL, &myxfs);   or
     kernel = Dcntl (KER_GETINFO, NULL, NULL);

In the first case an XFS is installed, in the second case one only gets the kernel structure (perhaps for a DFS or a device driver). The build-up of the kernel structure in detail:

typedef struct
{
  WORD   mxk_version;
  VOID (*mxk_fast_clrmem)      ( void *von, void *bis );
  BYTE (*mxk_toupper)          ( char c );
  VOID (*mxk__sprintf)         ( char *dest, char *source, LONG *p );
  VOID  *mxk_act_pd;
  APPL  *mxk_act_appl;
  APPL  *mxk_keyb_app;
  WORD  *mxk_pe_slice;
  WORD  *mxk_pe_timer;
  VOID (*mxk_appl_yield)       ( void );
  VOID (*mxk_appl_suspend)     ( void );
  VOID (*mxk_appl_begcritic)   ( void );
  VOID (*mxk_appl_endcritic)   ( void );
  LONG (*mxk_evnt_IO)          ( LONG ticks_50hz, void *unsel );
  VOID (*mxk_evnt_mIO)         ( LONG ticks_50hz, void *unsel, WORD cnt );
  VOID (*mxk_evnt_emIO)        ( APPL *ap );
  VOID (*mxk_appl_IOcomplete)  ( APPL *ap );
  LONG (*mxk_evnt_sem)         ( WORD mode, void *sem, LONG timeout );
  VOID (*mxk_Pfree)            ( void *pd );
  WORD   mxk_int_msize;
  VOID  *mxk_int_malloc        ( void );
  VOID   mxk_int_mfree         ( void *memblk );
  VOID   mxk_resv_intmem       ( void *mem, LONG bytes );
  LONG   mxk_diskchange        ( WORD drv );
  LONG   mxk_DMD_rdevinit      ( DMD *dmd );
  LONG   mxk_proc_info         ( WORD code, PD *pd );
  LONG   mxk_mxalloc           ( d0 = LONG amount, d1 = WORD mode, a0 = PD *pd );
  LONG   mxk_mfree             ( a0 = void *block );
  LONG   mxk_mshrink           ( d0 = LONG newlen, a0 = void *block );
} MX_KERNEL;

See also: MagiC's XFS-concept

11.21.5.1 mxk_version

mxk_version is the version number, which is simply 3 at present. For each change of the kernel structure the version number is increased, so that programs may adapt themselves accordingly.

11.21.5.2 mxk_fast_clrmem

mxk_fast_clrmem is a fast memory clearance routine, which sets the memory block between from and to (exclusive) to 0.

The following apply for this:

11.21.5.3 mxk_toupper

mxk_toupper converts the character c to upper case, respecting the national special characters (accents, umlauts etc.).

The following apply for this:

11.21.5.4 mxk__sprintf

mxk__sprintf is a function that expects its arguments on the stack. Items to pass are the destination character string dest, the template source and the values to be entered p[]. Depending on the formatting statement, the LONGwords are interpreted as 'unsigned int' (%W), 'signed long' (%L) or character string (%S).

With %W the WORD lying further down in memory is used, the sequence %% inserts a 'percent' character.

11.21.5.5 mxk_act_pd

mxk_act_pd is the pointer to the current basepage; the address can be obtained also from the system header or the DOS variables.

11.21.5.6 mxk_act_appl

mxk_act_appl is a pointer to the current application (i.e. the running task). The build-up of the structure is not documented. Due to faster access, the pointer is used as the descriptor in place of the ap_id.

11.21.5.7 mxk_keyb_app

mxk_keyb_app is the pointer to the application that currently 'owns' the keyboard. The pointer can be used by device drivers that have to process the keyboard-owning application in a different way, for instance.

11.21.5.8 mxk_pe_slice

mxk_pe_slice is used for preemptive multitasking. If *pe_slice == -1 then preemptive multitasking is switched off, and disk accesses are not interrupted.

11.21.5.9 mxk_pe_timer

mxk_pe_timer is used for preemptive multitasking. If *pe_slice == -1 then preemptive multitasking is switched off, and disk accesses are not interrupted.

11.21.5.10 mxk_appl_yield

mxk_appl_yield allocates CPU time to the system. It is important for drivers that cannot wait for an interrupt and have to prevent that their 'busy waiting' paralyses the system.

11.21.5.11 mxk_appl_suspend

mxk_appl_suspend works like appl_yield, though it allocates a lower priority to the application, perhaps as a background process.

11.21.5.12 mxk_appl_begcritic

mxk_appl_begcritic signals that the current application has entered a critical phase and may not be terminated.

11.21.5.13 mxk_appl_endcritic

mxk_appl_endcritic signals the end of the critical phase for the current application. If a termination command has arrived in the meantime then the program will be terminated.

11.21.5.14 mxk_evnt_IO

11.21.5.15 mxk_evnt_mIO

11.21.5.16 mxk_appl_IOcomplete

mxk_appl_IOcomplete wakes up an application that is waiting for evnt_(m)IO.

The following apply for this:

11.21.5.17 mxk_evnt_sem

11.21.5.18 SEM_FREE

Parameters:

11.21.5.19 SEM_SET

Parameters:

11.21.5.20 SEM_TEST

Parameters:

11.21.5.21 SEM_CSET

Parameters:

11.21.5.22 SEM_GET

Parameters:

11.21.5.23 SEM_CREATE

Parameters:

11.21.5.24 SEM_DEL

Parameters:

11.21.5.25 mxk_Pfree

mxk_Pfree releases the memory for a process that was terminated with Ptermres. This is necessary to remove a device driver correctly.

The following apply for this:

11.21.5.26 mxk_int_msize

mxk_int_msize gives the length of a memory block of the internal (kernel) memory management.

11.21.5.27 mxk_int_malloc

mxk_int_malloc allocates an internal memory block. If there is no free memory any more then first a global 'garbage collection' will be performed (see description of the XFS), and if this fails the system will be halted. Internal memory blocks may be reserved only in small lots, else one soon gets 'Out of internal memory' messages and the system locks up.

11.21.5.28 mxk_int_mfree

mxk_int_mfree releases a memory block once more.

The following apply for this:

11.21.5.29 mxk_resv_intmem

mxk_resv_intmem extends the kernel memory. There is no possibility foreseen to claim memory back. As the kernel only reserves internal memory sufficient for the FAT drives on booting, it may be necessary for an XFS to reserve further kernel memory with this function at the start.

The following apply for this:

11.21.5.30 mxk_diskchange

mxk_diskchange must be called when an XFS or DFS driver has recognized a disk media change. The XFS driver releases its files and structures and subsequently the kernel.

Return values:

The following apply for this:

11.21.5.31 mxk_DMD_rdevinit

As of kernel version 1.

mxk_DMD_rdevinit initializes the fields d_driver and d_devcode of the DMD and uses the field d_biosdev for this. It is required for interchangeable disk mechanisms.

The following apply for this:

11.21.5.32 mxk_proc_info

As of kernel version 2.

mxk_proc_info obtains data for the current process:

The following apply for this:

11.21.5.33 mxk_mxalloc

As of kernel version 4.

mxk_mxalloc enables fast memory allocation, e.g. for a RAMdisk-XFS, without having to go via a trap.

pd specifies the process that is entered as the owner of the new block, therefore normally the basepage of the XFS driver should be passed.

11.21.5.34 mxk_mfree

As of kernel version 4.

mxk_mfree releases the memory allocated by mxk_mxalloc.

11.21.5.35 mxk_mshrink

As of kernel version 4.

mxk_mshrink alters the size of a memory block.

11.21.6 Symbolic links and the XFS-concept

Symbolic links (also called aliases in the user documentation in accordance with Macintosh nomenclature) are files that are specially labelled in some way, and instead of data contain a path which in turn points to another file. Such a path can also point to a no longer or not yet existing file. Paths can be absolute or relative, where the latter have the directory in which the link lies as a reference.

In memory such links are managed as structures:

{
   WORD n;         /* Rounded up to an even number, incl. EOS */
   char path[n];   /* Path with EOS at end  */
}

Note: When some XFS functions come across a symlink they have to dereference it, i.e. they return to the kernel in d0 the error-code ELINK and in a0 a pointer to a structure of the above form. The kernel then looks after the dereferencing and the limiting of the maximum nesting depth (if the symlink points to another one).

XFS functions that may return ELINK are:

xfs_path2DD, xfs_sfirst, xfs_snext, xfs_fopen, xfs_xattr, xfs_attrib.

See also: MagiC's XFS-concept

11.21.7 MX_DOSLIMITS

This structure is defined as follows:

typedef struct
{
    UWORD version;        /* Version number                 */
    UWORD num_drives;     /* Max. number of drives          */
    ULONG max_secsizb;    /* Max. sector size in bytes      */
    UWORD min_nfats;      /* Min. number of FATs            */
    UWORD max_nfats;      /* Max. number of FATs            */
    ULONG min_nclsiz;     /* Min. number of sectors/cluster */
    ULONG max_nclsiz;     /* Max. number of sectors/cluster */
    ULONG max_ncl;        /* Max. number of clusters        */
    ULONG max_nsec;       /* Max. number of sectors         */
} MX_DOSLIMITS;

See also: Dcntl   KER_DOSLIMITS   MagiC's XFS-concept

11.21.8 XFS structures

• 11.21.8.1 dev_descr
• 11.21.8.2 DEVDRV
• 11.21.8.3 FILESYS
• 11.21.8.4 fs_descr

11.21.8.1 dev_descr

This structure is defined as follows:

struct dev_descr
{
    DEVDRV  *driver;
    SHORT   dinfo;
    SHORT   flags;
    struct tty *tty;
    LONG    devdrvsiz;
    LONG    reserved[4];
};

Note: The component devdrvsiz describes the size of the DEVDRV structure.

See also: Dcntl   MagiC's XFS-concept

11.21.8.2 DEVDRV

This structure is defined as follows:

typedef struct devdrv
{
    LONG (*open)      (FILEPTR *f);
    LONG (*write)     (FILEPTR *f, BYTE *buf, LONG bytes);
    LONG (*read)      (FILEPTR *f, BYTE *buf, LONG bytes);
    LONG (*lseek)     (FILEPTR *f, LONG where, WORD whence);
    LONG (*ioctl)     (FILEPTR *f, WORD mode, VOID *buf);
    LONG (*datime)    (FILEPTR *f, WORD *timeptr, WORD rwflag);
    LONG (*close)     (FILEPTR *f, WORD pid);
    LONG (*select)    (FILEPTR *f, LONG proc, WORD mode);
    VOID (*unselect)  (FILEPTR *f, LONG proc, WORD mode);
    LONG reserved[3];
} DEVDRV;

See also: Dcntl   dev_descr   FILESYS   MagiC's XFS-concept

11.21.8.3 FILESYS

This structure is defined as follows:

typedef struct filesys
{
    struct  filesys *next;
    LONG    fsflags;
    LONG    (*root)       (WORD drv, fcookie *fc);
    LONG    (*lookup)     (fcookie *dir, BYTE *name, fcookie *fc);
    LONG    (*creat)      (fcookie *dir, BYTE *name, UWORD mode,
                           WORD attrib, fcookie *fc);
    DEVDRV *(*getdev)     (fcookie *fc, LONG *devspecial);
    LONG    (*getxattr)   (fcookie *fc, XATTR *xattr);
    LONG    (*chattr)     (fcookie *fc, WORD attr);
    LONG    (*chown)      (fcookie *fc, WORD uid, WORD gid);
    LONG    (*chmode)     (fcookie *fc, UWORD mode);
    LONG    (*mkdir)      (fcookie *dir, BYTE *name, UWORD mode);
    LONG    (*rmdir)      (fcookie *dir, BYTE *name);
    LONG    (*remove)     (fcookie *dir, BYTE *name);
    LONG    (*getname)    (fcookie *relto, fcookie *dir, BYTE *pathname,
                           WORD size);
    LONG    (*rename)     (fcookie *olddir, BYTE *oldname,
                           fcookie *newdir, BYTE *newname);
    LONG    (*opendir)    (DIR *dirh, WORD tosflag);
    LONG    (*readdir)    (DIR *dirh, BYTE *nm, WORD nmlen, fcookie *fc);
    LONG    (*rewinddir)  (DIR *dirh);
    LONG    (*closedir)   (DIR *dirh);
    LONG    (*pathconf)   (fcookie *dir, WORD which);
    LONG    (*dfree)      (fcookie *dir, LONG *buf);
    LONG    (*writelabel) (fcookie *dir, BYTE *name);
    LONG    (*readlabel)  (fcookie *dir, BYTE *name, WORD namelen);
    LONG    (*symlink)    (fcookie *dir, BYTE *name, BYTE *to);
    LONG    (*readlink)   (fcookie *dir, BYTE *buf, WORD len);
    LONG    (*hardlink)   (fcookie *fromdir, BYTE *fromname,
                           fcookie *todir, BYTE *toname);
    LONG    (*fscntl)     (fcookie *dir, BYTE *name, WORD cmd, LONG arg);
    LONG    (*dskchng)    (WORD drv);
    LONG    (*release)    (fcookie *fc);
    LONG    (*dupcookie)  (fcookie *dest, fcookie *src);
} FILESYS;

See also: Dcntl   fs_descr   MagiC's XFS-concept

11.21.8.4 fs_descr

This structure is defined as follows:

struct fs_descr
{
    FILESYS *file_system;
    SHORT   dev_no;
    LONG    flags;
    LONG    reserved[4];
};

See also: Dcntl   MagiC's XFS-concept