Previous

Next

Device List

RTFiles-32 needs a list of devices with their associated drivers. Each available driver is implemented as a structure of function pointers to all driver entrypoints. To access a specific device, the drivers need a data structure for each device they should handle. In addition, RTFiles-32 must know whether the device is a floppy or hard disk and which options apply for the device.

RTFiles-32's driver list is a zero-terminated array of structures. Each structure defines everything RTFiles-32 needs to know about the device:

typedef struct { 
   int             DeviceType; 
   int             DeviceNumber; 
   DWORD           DeviceFlags; 
   RTFDriver     * Driver; 
   void          * DriverData; 
   RTFDeviceData   DevData;  // reserved for RTFiles-32 internal use 
} RTFDevice;

The device list array used by RTFiles-32 is a global symbol:

extern RTFDevice RTFDeviceList[];

DeviceType can be either RTF_DEVICE_FLOPPY or RTF_DEVICE_FDISK. This information may be required by the device driver if the driver can support different device types. It is also used to determine whether the device has a partition table or not. Thus, you must use RTF_DEVICE_FLOPPY for all devices without a partition table, even if they are not floppies (e.g., a RAM disk).

DeviceNumber is a zero-based index of the device within its class. For example, floppy disk A has device number 0 and floppy B is device number 1. The exact meaning of the device number can depend on the device driver.

DeviceFlags can be used to select special options to be applied to the device. These options can either be general RTFiles-32 flags or device driver specific flags. The following device independent flags are available and can be used with any device driver:

RTF_DEVICE_SINGLE_FAT

RTFiles-32 should use only the first FAT. Many devices are formatted to have two or even more copies of the FAT. Both DOS, Windows, and RTFiles-32 will use only the first FAT, but all other copies are always updated on every change of the FAT. To improve performance, you can instruct RTFiles-32 not to update redundant FAT copies.

RTF_DEVICE_LAZY_WRITE

Usually, RTFiles-32 will flush all cached buffers of a file to the disk when the file is closed. However, when this flag is set, RTFiles-32 will wait until the last file of this drive is closed. This option can improve write performance when many files are created/deleted and/or extended simultaneously. However, the drive may be left in an inconsistent state if not all files are closed before the program terminates.

RTF_DEVICE_MOUNT_CONTIGUOUS

This flag instructs RTFiles-32 not to assign drive letters to logical drives the same way MS-DOS would. Instead, all of the device's drives are assigned after all other devices not specifying this flag, and all drives are assigned contiguous drive letters. The algorithm for assigning drive letters is given in section RTFiles-32 in Embedded Applications, Mounting Devices and Logical Drives.

RTF_DEVICE_REMOVABLE

This flag can be used to inform RTFiles-32 that the device is removable. It is usually not necessary to specify RTF_DEVICE_REMOVABLE as RTFiles-32 can query a device driver whether a disk is removable or not. Use it only for drivers which do not support reporting removable media (i.e. drivers not shipped with RTFiles-32 or PCMCIA IDE disks).

RTF_DEVICE_NO_MEDIA

This flags instructs RTFiles-32 to assume that this device is initially not present. RTFiles-32 will not attempt to access the device until RTFRawSetMedia(.., 1) has been called. You should specify this flag only for removable devices when the device driver is not able to detect media insertion by itself. For example, this flag is required for PCMCIA disks. RTF_DEVICE_REMOVABLE should also be set for such device list entries.

RTF_DEVICE_NEW_LOCK

RTFiles-32 maintains semaphores to lock devices to prevent two threads accessing the same device simultaneously. To support non-reentrant device drivers, no parallel access to any two devices managed by the same driver is allowed by default. Each driver (not device) is allocated its own lock. However, each device with this flag set will get a new lock, allowing parallel access with other devices of the same driver. Please consult section Device Drivers for details on which drivers support this flag.

RTF_DEVICE_NO_DIAG_MSG

Some RTFiles-32 device drivers may issue warning messages when they encounter non fatal errors. This flag may be set to surpress such messages for a particular disk device.

RTF_DEVICE_RAMDISK

This flag marks a device list entry as a RAM disk. RTFiles-32 does not treat RAM disks in any special way, but RTFGetDiskInfoEx and Win32 API function GetDriveType() are able to correctly identify RAM disks if they have this flag set in the device list.

RTF_DEVICE_GPT_SYSPART

This flag instructs RTFiles-32 to mount EFI System Partitions in addition to Basic Data Partitions from GPT partition tables. EFI System Partitions usually contain OS boot loader data and are formatted with FAT-16 or FAT-32. By default, EFI System Partitions are not mounted on disks with a GPT partition table.

RTF_DEVICE_GPT_ALLPART

This flag instructs RTFiles-32 to mount all partitions from GPT partition tables, no matter what partition type they have. By default, only Basic Data Partitions are mounted on disks with a GPT partition table.

Please refer to section Device Drivers for details about device driver specific options.

The Driver member of structure RTFDevice is a pointer to a disk device driver. The following device drivers are shipped with RTFiles-32; they are documented in detail later in this section:

Member DriverData is device driver specific. Each driver defines a data structure, a pointer to which must be stored in this field. For many devices, the device data structure can be initialized to 0 to get the driver's default behavior. Please refer to the following sections for details about each driver's specific data.

RTFiles-32's default device list configuration looks like this:

static RTFDrvIDEData  IDE[4]  = {0}; 
static RTFDrvIDEData  SATA[4] = {0}; 
static RTFDrvAHCIData AHCI[4] = {0}; 

RTFDevice RTFDeviceList[] = { 
   // IDE primary master and slave 
   { RTF_DEVICE_FDISK , 0, 0,                   &RTFDrvIDE,  IDE + 0 }, 
   { RTF_DEVICE_FDISK , 1, 0,                   &RTFDrvIDE,  IDE + 1 }, 

   // IDE secondary master and slave 
   { RTF_DEVICE_FDISK , 2, RTF_DEVICE_NEW_LOCK, &RTFDrvIDE,  IDE + 2 }, 
   { RTF_DEVICE_FDISK , 3, 0,                   &RTFDrvIDE,  IDE + 3 }, 

   // four SATA ports 
   { RTF_DEVICE_FDISK , 8, RTF_DEVICE_NEW_LOCK, &RTFDrvIDE,  SATA + 0 }, 
   { RTF_DEVICE_FDISK , 9, RTF_DEVICE_NEW_LOCK, &RTFDrvIDE,  SATA + 1 }, 
   { RTF_DEVICE_FDISK ,10, RTF_DEVICE_NEW_LOCK, &RTFDrvIDE,  SATA + 2 }, 
   { RTF_DEVICE_FDISK ,11, RTF_DEVICE_NEW_LOCK, &RTFDrvIDE,  SATA + 3 }, 

   // four AHCI ports 
   { RTF_DEVICE_FDISK , 0, RTF_DEVICE_NEW_LOCK, &RTFDrvAHCI, AHCI + 0 }, 
   { RTF_DEVICE_FDISK , 1, RTF_DEVICE_NEW_LOCK, &RTFDrvAHCI, AHCI + 1 }, 
   { RTF_DEVICE_FDISK , 2, RTF_DEVICE_NEW_LOCK, &RTFDrvAHCI, AHCI + 2 }, 
   { RTF_DEVICE_FDISK , 3, RTF_DEVICE_NEW_LOCK, &RTFDrvAHCI, AHCI + 3 }, 

   { 0 } // end of list 
};

You can supply your own RTFDeviceList array to override RTFiles-32's default configuration. The following example would be used if you want to use only a single DiskOnChip:

static RTFDrvDOCData Disk0Data = {0}; 

RTFDevice RTFDeviceList[] = { 
   { RTF_DEVICE_FDISK , 0, 0, &RTFDrvDOC, &Disk0Data }, 
   { 0 } 
};

This example would also require an entry in your RTTarget-32 configuration file.

Example:

Region  DiskOnChip  D0000h  8k  Device  ReadWrite

with a suitable address of the DOC's memory window.

The following example supports one diskette drive, one IDE hard disk on the motherboard's IDE controller, a second IDE hard disk to be mapped as the master drive in a PCMCIA slot, and a RAM disk of 8M maximum size:

static RTFDrvFLPYData  A = {0}; 
static RTFDrvIDEData   C = {0}; 
static RTFDrvIDEData   D = {0}; 
static RTFDrvRAMData   E = {8*1024*1024/512}; 

RTFDevice RTFDeviceList[] = { 
  { RTF_DEVICE_FLOPPY, 0, 0,                   &RTFDrvFloppy, &A }, 
  { RTF_DEVICE_FDISK , 0, 0,                   &RTFDrvIDE,    &C }, 
  { RTF_DEVICE_FDISK , 2, RTF_DEVICE_NO_MEDIA  | 
                          RTF_DEVICE_REMOVABLE | 
                          RTF_DEVICE_NEW_LOCK  | 
                          RTF_CONTIGUOUS_IO,   &RTFDrvIDE,    &D }, 
  { RTF_DEVICE_FLOPPY, 0, 0,                   &RTFDrvRAM,    &E }, 
  { 0 } 
};

This example also requires that a DMA buffer is allocated in RTTarget-32's configuration file.

The following example uses a single flash disk using RTFiles-32's proprietary linear flash disk driver:

// we want a single flash disk device configured as a hard disk, 
// using 4 flash chips, 8 bits wide each, to implement a 32-bit 
// wide device, so we use the RTFMtdCFI2_32 MTD driver. 

// MTD data 
static RTFMtdCFI2Data MTDData = {0}; 

// Flash driver data, links to MTD driver 
static RTFDrvFlashData FlashDisk = { &RTFMtdCFI2_32, &MTDData }; 

// Device List, pulls in flash driver 
RTFDevice RTFDeviceList[] = { 
   { RTF_DEVICE_FDISK, 0, 0, &RTFDrvFlash, &FlashDisk }, 
   { 0 } 
};

This example would require Region and Nothing entity declarations such as:

Region  Flash     1G-256M     16M  Device 
Locate  Nothing  FlashDisk  Flash  Flash.Size

Configuring RTFiles-32

The System Driver

Device Drivers