Description of the functions of pseudo-drive U: for MagiC 3.00 onwards
######################################################################

Andreas Kromke
Hannover, 27.3.94
English translation: Peter West, May 99


I General
=========

Pseudo-drive U: is created at the initialisation of the DOS. So that its 
existence is recognised by current programs the corresponding bit in
_drvbits is set, though no corresponding BIOS drive exists. Dfree() 
basically returns only zeros.

All directories are currently limited to a maximum of 32 entries.

In contrast to MiNT, U:\PROC, U:\DEV etc. do not form their own file 
systems, but are simply subdirectories of the DFS for drive U:. Depending 
on the subdirectory, the U-DFS creates different file types and drivers.
As the control of directories is the responsibility of the DOS_XFS, write 
accesses for, say, a device in U:\DEV cause a change in the file time/date-
stamp, as for any normal disk file. This even goes so far that a write 
access to the root directory of drive A: will automatically alter the 
file time/date-stamp of U:\A.

Devices, pipes and shared memory blocks can be moved, deleted or renamed.
One can create symbolic links in all directories of drive U:, e.g. with
"ln -s U:\CON U:\CONSOLE" one can create an alias for the device file CON.
One can also simply create empty files, but no folders because drive U: 
does not possess any memory.
In contrast to MiNT, U:\ does not have its own special file system but is 
handled by the DOS file system. One merely has to pay regard to the fact 
that only symbolic links can be created.
The directories U:\A etc. are merely symbolic links, which can also be 
removed or renamed.

The construction of all internal structures and the fast, register-based 
parameter passing and return requires either:

- An implementation of all file drivers in assembler, at least for most 
  of the functions, or:
- Assembler routines for conversion of the parameters to 'C'-conventions.


1.1 The directory U:\
---------------------

Besides existing files only symbolic links can be created (via Fsymlink()) 
on the root directory of U:\. No Dcntl function is supported.

Before each access to drive U:, any new drives are added via a symbolic 
link, or no longer existing ones removed (this is recognised via _drvbits).

A symlink for drive X: is normally installed under the name "U:\X", 
pointing to "X:\". A symlink can naturally be renamed or deleted. A 
renamed symlink will also be deleted automatically when a bit is cleared 
in _drvbits.

Because the drive directories are only symbolic links, one obtains with 
Fsfirst/next the data for the actual file. This means that after a write 
access to the root directory of drive A:, the file time/date-stamp of 
U:\A will be amended automatically. But this is only a side effect that 
appears because all write accesses are logged via the file time/date-stamp, 
including those to subdirectories (these are not written to the disk, 
however).

MiNT does not install the drives as symbolic links, therefore one can use 
the following command sequence:

     Dsetdrv  U:
     Dsetpath U:\A
     Dgetpath => U:\A
     Dsetpath ..
     Dgetpath => U:\

With a symbolic link one really changes the path, i.e. in the third line 
A:\ will appear as the current path. In order to get round this problem 
special handling is used by the kernel, which makes the above command 
sequence possible in MagiC as well. There is only one problem with this:
The symlink must not be renamed, otherwise the following happens:

     Frename  U:\A U:\FLOPPY
     Dsetdrv  U:
     Dsetpath U:\FLOPPY
     Dgetpath => U:\A
     Dsetpath ..
     Dgetpath => U:\

but that should not be critical otherwise, and does not matter when a 
desktop is used because only absolute paths are used there.
In the future it is planned to possibly permit longer names for drives 
than just A: or B:, in which case a drive could also be called CDROM: 
and would then be installed automatically as U:\CDROM.

Because all the file functions on U: work in exactly the same way as for 
a floppy disk, it is also possible to rename directories U:\DEV etc.; but 
one should avoid this if possible, since otherwise the applications will 
no longer be able to find their device drivers.

There is a tricky possibility to create other files in U:\ all the same, 
namely create a device in U:\DEV, for instance, and move this with 
Frename() to U:\. But one should only play such tricks if one really 
knows what one is doing.


1.2 The directory U:\DEV
------------------------

Here device drivers are installed, which are pseudo-files that represent 
devices that are only known to DOS and not the BIOS. Devices can be 
created only with Dcntl(DEV_M_INSTALL), but can be renamed and deleted 
with the usual methods. In contrast to MiNT the deletion of a device 
proceeds via the device driver, which thus can unhook itself from the 
corresponding system vectors and release the memory it occupied (if it 
was installed with Ptermres()) or can terminate itself (if put to sleep).

One can not create files with Fcreate() here, but one can create symbolic 
links (sensibly to file drivers!!!). Thus one can create, say, a link 
U:\DEV\COM1 that points to U:\DEV\AUX.

In contrast to MiNT the full functionality of the DOS file system is 
available, i.e.:

- No more than one device with a given name may exist.
- Write accesses cause changes to the file time/date-stamp.
- Write-protected devices may not be written to, deleted or renamed.

On all STs the following devices are created in u:\dev, and except for 
CON all devices are "raw", i.e. do not react to ^C, ^S, ^Q etc.

     NULL      Empty pseudo-file, always returns OK during writing and 
     		"No character available" or EOF during reading.
               Fselect() works by interrupt control, i.e. the interrupt 
               for "ready for reading" never occurs.
     CON       "Cooked" output to the screen
               "Cooked" line by line input from the keyboard
               (with Fread/writechar also "raw" mode)
     AUX       In/output from BIOS device 2
     PRN       In/output from BIOS device 0
               Output will be broken off at a timeout (Bconout->0)
     MODEM1    In/output from BIOS device 6, is generally the serial port 
      		realised via the ST-MFP; on the Falcon the SCC, channel B
     MIDI      In/output from BIOS device 3, with output status device 4

  On the MegaSTE there are in addition the following devices:

     MODEM2    BIOS device 7 (generally SCC, channel B)
     SERIAL2   BIOS device 8 (generally SCC, channel A)

  On the TT, on the other hand, there are the following devices instead:

     MODEM2    BIOS device 7 (generally SCC, channel B)
     SERIAL1   BIOS device 8 (generally the TT-MFP)
     SERIAL2   BIOS device 9 (generally SCC, channel A)

  And on the Falcon, there are the following devices instead:

     LAN       BIOS device 7 (generally SCC, channel A)

  The old device names correspond to the following files:

     CON: or handle -1		=> U:\DEV\CON
     AUX: or handle -2   	=> U:\DEV\AUX
     PRN: or handle -3   	=> U:\DEV\PRN
     NUL: or handle -4   	=> U:\DEV\NULL

If one specifies filenames such as CON:, then this filename will be 
converted already by the kernel to U:\DEV\CON, i.e. "CON:" is a sort of 
alias.

Due to the incompatible driver format, Dcntl() does not use the MiNT 
subfunction DEV_INSTALL (0xde02), but the new MagiC subfunction 
DEV_M_INSTALL ($cd00).
Drivers are installed with the call Dcntl(DEV_M_INSTALL, fname, drvr). 
The makeup of the driver is described in MGX_DFS.TXT (also in this 
FILESYS directory).


1.3 The directory U:\SHM
------------------------

Here files are created with Fcreate(); Dcntl modes are not supported.
What is created here are special files that represent "shared memory".
Unfortunately I don't know of any program that supports this feature.


1.4 The directory U:\PROC
---------------------------

Here process names are created and removed again. Process-IDs are 
assigned at program start (modes 0, 4, 6, 7) and released at termination.
At present the renaming of files is possible, but should be avoided.
Deletion destroys a process and cleans up after it (via the AES program  
manager).

The file size specifies the memory used by the process. MiNT-conform file 
attributes are not supported at present.

The process name is included in the environment (variable _PNAM since 
MagiC 1.0), the process ID in the basepage.

Fcntl with PBASEADDR is supported.

Dfree is supported and returns the minimum actual block length (as 
"sectors per cluster"). At present memory is occupied word-wise, i.e. 
the "sector size" is 1 byte, cluster size are 2 sectors.


1.5 The directory U:\PIPE
-------------------------

Here pipes are stored. For more details see PIPES.TXT (in the outer 
directory of this documentation).
