This guide explains how to migrate a Nextor driver from v2 to v3. The reader is expected to have experience with Nextor v2 driver development.
Only the changes relative to the structure of the driver for v2 are mentioned here. You can see the skeleton for a full v3 driver in the Nextor-v3-driver.asm in this same gist, and the skeleton for a full v2 driver in the Nextor repository.
The driver flags byte needs to be changed to the fixed value 83h. Bit 7 indicates that the driver is a v3 driver, bits 0 and 1 need to be set for consistency with the meaning they had in Nextor v2.
This field is not used anymore in Nextor v3 (the DRV_QUERY routine is used instead to get driver information). It should have the fixed value "Nextor v3 driver", padded at the right with spaces up to 32 characters.
This routine is not used anymore in Nextor v3 (the DRV_QUERY routine is used instead to get driver information). It should be changed to return A=0 and BC=0.
This routine works the same as in v2, with two minor changes:
- Since drive-based drivers are not supported anymore, the routine will never return the number of required drives in its first execution (or if it does, Nextor will ignore it).
- The second execution will occur even when there's not enough space in page 3 to allocate the requested amount of work area, but a flag will be passed (bit 7 of register C) indicating so.
This routine works as in v2, but since there is no concept of LUN anymore, Nextor will not pass any meaningful LUN number in register C; instead, it will always pass the value 1, which is the value expected by v2 drivers that don't implement the concept of LUNs (or put another way, implement one single LUN).
If your driver doesn't use LUNs, you don't need to change anything in this routine. Otherwise you need to come up with some mechanism to map devices+LUNs to single device numbers. For example you could support only device numbers 1-15 (that's more than the 7 devices that Nextor v2 supported anyway) and map higher values to LUNs, e.g. you can use something like "device+16*LUN".
These routines are not used anymore in Nextor v3, for compatibility with tools that might still call them they should be kept but just returning an error. DEV_INFO and LUN_INFO should return A=1, DEV_STATUS should return A=0.
The functionality of these routines has actually been moved to the DEV_QUERY routine, and you will probably be able to reuse most of their code, as we'll see later in this document.
This routine existed already since Nextor 2.0.5 (with the name DRV_CONFIG and only with queries 1 and 2) but it was optional; it will be mandatory in Nextor v3.
Note however that although the routine itself is mandatory, all the queries are optional, so you can just return an error for all of them (although it's recommended to implement at least the queries to return driver names and versions).
This query already existed in v2 and is identical in v3, so if you had already implemented it you don't need to change anything.
This query already existed in v2 and is identical in v3, except that it doesn't return a LUN number in register C anymore so if you had already implemented it and your driver doesn't support LUNs you don't need to change anything; otherwise adjust as needed, see the explanation about DEV_RW for a suggestion for remapping LUNs to devices.
For now, you need to implement this query only if your driver supports hot-plug devices.
A driver is said to support hot-plug devices if after the system boots new devices can begin to exist and existing devices can cease to exist, or be replaced with another devices. This is the case of a USB bus, for example.
Note that a hot-plug device changing is not the same as a medium change in a removable device, e.g. a SD card reader. See the descriprion of the "Get device or medium change status" query for the DEV_QUERY routine in Nextor-v3-driver.asm for more details on this.
This query replaces the hardcoded driver name defined in v2 drivers (DRV_NAME), and provides more options for returning information. While all the subqueries (information ids) are optional to implement, it's recommended to supply at least either the hardware name (for drivers that are specific to a given controller) or the driver name (for drivers made for generic hardware, or that don't depend on any hardware at all). Nextor doesn't require this information for normal operation.
Nextor will always call this query with a buffer size of at least 64 bytes, but the routine must be prepared to receive a smaller buffer size and return a truncated string if necessary. Note also that there's a special error code to indicate that the output is truncated.
This query replaces the DRV_VERSION routine in v2 drivers (and extends version number components to 16 bit values). While it's optional to implement, it's recommended to at least supply the driver version number. Nextor doesn't require this information for normal operation.
This routine is new in Nextor v3 drivers, and replaces the DEV_INFO, DEV_STATUS and LUN_INFO routines defined in v2, while providing also new capabilities.
This query replaces the "Medium type" and "Logical unit features flags" fields in the block of information returned by LUN_INFO from v2. So here's how you could do the conversion from the old routine to the new query:
- Adjust input parameters, from A=device id and B=LUN id to C=device id.
- Return the old "Logical unit features flags" in register C. Set B, DE, HL to zero.
Note that this query defines two new flags: bit 4 (device is hot-pluggable) and bit 5 (device is NOT a block device), the later is the replacement for the "Medium type" field returned by LUN_INFO.
This query replaces the DEV_STATUS routine from v2. However, other than for the input parameters (same as previous query), there are two important differences:
- Bit 7 in the returned status now indicates if the device itself has changed. This applies to hot-plug devices only, and replaces the "return the status of the device itself" input parameter in
DEV_STATUS. DEV_STATUSreturned a status of 0 in two cases: when the device doesn't exist, and when the device is removable but there is no medium inserted. This query on the other hand has two different outputs for these two cases: device not existing returns an error (A=1), device existing but medium not inserted returns a status of 0 (A=0, B=0).
See the descriprion of this query for the DEV_QUERY routine in Nextor-v3-driver.asm for more details on hot-plug devices vs removable devices.
This query replaces the DEV_INFO routine while providing additional types of information to return. Note that while in DEV_INFO the supplied buffer to copy information was defined as having a fixed size of 64 bytes, in this query the buffer size is passed along with the address of the buffer.
Nextor will always call this query with a buffer size of at least 64 bytes, but the routine must be prepared to receive a smaller buffer size and return a truncated string if necessary. Note also that there's a special error code to indicate that the output is truncated.
This query replaces the "Total number of available sectors" field in the block of information returned by LUN_INFO from v2. The difference is that if this information is not available LUN_INFO returned a value of 0, while this query returns an error instead.
Nextor doesn't require this information for normal operation, but devices not providing this information won't be handled by the built-in FDISK tool.
This query replaces the "Sector size", "Number of cylinders", "Number of heads" and "Number of sectors per track" fields in the block of information returned by LUN_INFO from v2.
As it was the case in v2, the last three are applicable only to physical hard disks and are useful only to disk partitioning tools (but Nextor's built-in FDISK doesn't use them). Regarding the sector size, Nextor will assume 512 bytes if this query is not implemented; so in most cases it won't be necessary to implement it.
Nextor will only call these queries in response to a FORMAT/CALL FORMAT command and only for devices that return the "it's a floppy disk drive" flag set in the "Get basic device information" query. Implementing these is optional, but of course not implementing them means that Nextor won't be able to format floppy disks in drives controlled by that driver.