Mtools 4.0.20: Porting mtools

6 Porting mtools to architectures which are not supported yet

This chapter is only interesting for those who want to port mtools to an architecture which is not yet supported. For most common systems, default drives are already defined. If you want to add default drives for a still unsupported system, run configuration.guess, to see which identification autoconf uses for that system. This identification is of the form cpu-vendor-os (for example sparc-sun-sunos). The cpu and the OS parts are passed to the compiler as preprocessor flags. The OS part is passed to the compiler in three forms.

The complete OS name, with dots replaced by underscores. SCO3.2v2 would yield sco3_2v2
The base OS name. SCO3.2v2 would yield Sco
The base OS name plus its major version. SCO3.2v2 would yield Sco3

All three versions are passed, if they are different.

To define the devices, use the entries for the systems that are already present as templates. In general, they have the following form:

#if (defined (my_cpu) && defined(my_os))
#define predefined_devices
struct device devices[] = {
        { "/dev/first_drive", 'drive_letter', drive_description},
        … 
        { "/dev/last_drive", 'drive_letter', drive_description}
}
#define INIT_NOOP
#endif

"/dev/first_drive" is the name of the device or image file representing the drive. Drive_letter is a letter ranging from a to z giving access to the drive. Drive_description describes the type of the drive:

ED312: extra density (2.88M) 3 1/2 disk
HD312: high density 3 1/2 disk
DD312: double density 3 1/2 disk
HD514: high density 5 1/4 disk
DD514: double density 5 1/4 disk
DDsmall: 8 sector double density 5 1/4 disk
SS514: single sided double density 5 1/4 disk
SSsmall: single sided 8 sector double density 5 1/4 disk
GENFD: generic floppy drive (12 bit FAT)
GENHD: generic hard disk (16 bit FAT)
GEN: generic device (all parameters match)
ZIPJAZ(flags): generic ZIP drive using normal access. This uses partition 4. Flags are any special flags to be passed to open.
RZIPJAZ(flags): generic ZIP drive using raw SCSI access. This uses partition 4. Flags are any special flags to be passed to open.
REMOTE: the remote drive used for floppyd. Unlike the other items, this macro also includes the file name ($DISPLAY) and the drive letter (X)

Entries may be described in more detail:

 fat_bits,open_flags,cylinders,heads,sectors,DEF_ARG

or, if you need to describe an offset (file system doesn’t start at beginning of file system)

 fat_bits, open_flags, cylinders, heads, sectors, offset, DEF_ARG0

fat_bits: is either 12, 16 or 0. 0 means that the device accepts both types of FAT.
open_flags: may include flags such as O_NDELAY, or O_RDONLY, which might be necessary to open the device. 0 means no special flags are needed.
cylinders,heads,sectors: describe the geometry of the disk. If cylinders is 0, the heads and sectors parameters are ignored, and the drive accepts any geometry.
offset: is used if the DOS file system doesn’t begin at the start of the device or image file. This is mostly useful for Atari Ram disks (which contain their device driver at the beginning of the file) or for DOS emulator images (which may represent a partitioned device.

Definition of defaults in the devices file should only be done if these same devices are found on a large number of hosts of this type. In that case, could you also let me know about your new definitions, so that I can include them into the next release. For purely local file, I recommend that you use the /etc/mtools.conf and ~/.mtoolsrc configuration files.

However, the devices files also allows to supply geometry setting routines. These are necessary if you want to access high capacity disks.

Two routines should be supplied:

Reading the current parameters
```
static inline int get_parameters(int fd, struct generic_floppy_struct *floppy)
```
This probes the current configured geometry, and return it in the structure generic_floppy_struct (which must also be declared). Fd is an open file descriptor for the device, and buf is an already filled in stat structure, which may be useful. This routine should return 1 if the probing fails, and 0 otherwise.
Setting new parameters
```
static inline int set_parameters(int fd, struct generic_floppy_struct *floppy)
                                 struct stat *buf)
```
This configures the geometry contained in floppy on the file descriptor fd. Buf is the result of a stat call (already filled in). This should return 1 if the new geometry cannot be configured, and 0 otherwise.

A certain number of preprocessor macros should also be supplied:

TRACKS(floppy): refers to the track field in the floppy structure
HEADS(floppy): refers to the heads field in the floppy structure
SECTORS(floppy): refers to the sectors per track field in the floppy structure
SECTORS_PER_DISK(floppy): refers to the sectors per disk field in the floppy structure (if applicable, otherwise leave undefined)
BLOCK_MAJOR: major number of the floppy device, when viewed as a block device
CHAR_MAJOR: major number of the floppy device, when viewed as a character device (a.k.a. "raw" device, used for fsck) (leave this undefined, if your OS doesn’t have raw devices)

For the truly high capacity formats (XDF, 2m, etc), there is no clean and documented interface yet.