NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO
#include <ddi/disk/disk.h>
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
DDI
Provides hard disk driver interface services.
The disk device driver service routines are declared by the DiskOps structure, shown below. Each probed disk is registered in the device registry by the disk device driver, using the svDeviceRegister microkernel call. A disk client scans the device registry, using svDeviceLookup, searching for entries reclaiming the device class DISK_CLASS, and the lowest DiskVersion. For each entry retrieved, the disk client can use the svDeviceEntry microkernel call in order to obtain a pointer to the device service routines, DiskOps, and a disk identifier.
#define DISK_CLASS "disk" typedef enum { DISK_VERSION_INITIAL = 0, } DiskVersion; typedef struct DiskOps { DiskVersion version; KnError (*open) (DiskId disk_id, DiskEventHandler dev_event_hdl, void* dev_cookie, DiskDevId* dev_id); void (*close) (DiskDevId dev_id); KnError (*read) (DiskDevId dev_id, DiskSize block_no, DiskSize block_count, void* buffer, DiskDoneHandler done_handler, void* cookie); KnError (*write) (DiskDevId dev_id, DiskSize block_no, DiskSize block_count, void* buffer, DiskDoneHandler done_handler, void* cookie); void (*get_params) (DiskDevId dev_id, DiskParams* params); } DiskOps;
The DiskOps.open function must be the first call issued by the disk client to establish communication with the disk device.
KnError (*open) (DiskId disk_id, DiskEventHandler dev_event_hdl, void* dev_cookie, DiskDevId* dev_id);
The disk device is designated, using the disk_id argument, to DiskOps.open. This argument is retrieved by the disk client via the svDeviceEntry microkernel call. The dev_event_hdl argument is an event handler in the disk client which is called by the disk driver in order to notify an event to the disk client. The dev_cookie argument is an opaque value for the disk driver, and is passed as the first argument to this event handler. This event handler takes two additional parameters, an event type specific argument and the disk event itself which is one of the following:
Notifies the disk client that the disk device is going to be shut down. The disk client should close its connection (using DiskOps.close), release any allocated resource, and release the device entry (with svDeviceRelease).
Notifies the disk client that the disk device has been removed and is no longer present. The disk client should close its connection (using DiskOps.close), release any allocated resource, and release device entry (using svDeviceRelease).
Notifies the disk client that the disk device has been reset while executing a previous request. This request is passed back to the disk client in the last argument of the event handler. The disk client must assume that the request has failed, and take appropriate action.
On success, a K_OK status is returned, and the dev_id argument returned specifies an identifier which must be given to the disk driver for all other service calls. On failure, DiskOps.open returns an error code as follows:
The system is out of memory.
For any other errors.
Invocation Context
DiskOps.open must be called at base level. It can be invoked multiple times on the same disk.
The disk client must close opened connections using the DiskOps.close service routine. Typically, DiskOps.close must be called when a DISK_DEV_SHUTDOWN event has been notified to the disk client.
void (*close) (DiskDevId dev_id); The dev_id is returned by DiskOps.open.
Invocation Context
DiskOps.close can be called at interrupt level.
The disk client must use the DiskOps.read service routine to read data from the disk. DiskOps.read returns immediately without waiting for request completion and is asynchronous.
KnError (*read) (DiskDevId dev_id, DiskSize block_no, DiskSize block_count, void* buffer, DiskDoneHandler done_handler, void* cookie);
The dev_id is returned by DiskOps.read. The block_no argument specifies the starting block number (linear numbering, starting at 0). The block_count argument specifies the count of the blocks (of 512 bytes) to read. Note that a maximum of 256 blocks can be read at a time. The buffer argument specifies the address of the buffer in memory where read data will be stored.
Once the DiskOps.read is finished, the done_handler() call-back function is called by the disk driver to notify the disk client. The cookie argument is passed as the first argument of this handler. This handler takes a second argument, a request status, DiskStatus, which indicates to the disk client whether the request has been a success or a failure.
On success, a K_OK status is returned. On failure, DiskOps.read returns an error code as follows:
The system is out of memory.
The requested transfer size is invalid. The block_count argument must be greater than 0 and lower than or equal to 256.
For any other errors. For example, done_handler() has returned NULL.
Invocation Context
The DiskOps.read must be called at base level. It is an asynchronous service and can be invoked multiple times, without waiting for command completion.
The disk client must use the DiskOps.write service routine request to write data to the disk. DiskOps.write returns immediately without waiting for request completion and is asynchronous.
KnError (*write) (DiskDevId dev_id, DiskSize block_no, DiskSize block_count, void* buffer, DiskDoneHandler done_handler, void* cookie);
dev_id is returned by DiskOps.open. The block_no argument specifies the starting block number (linear numbering, starting at 0). The block_count argument specifies the count of blocks (of 512 bytes) to write. Note that a maximum of 256 blocks can be written at a time. The buffer argument specifies the address of the buffer in memory containing the data to write. Once the DiskOps.write is finished, the done_handler() call-back function is called by the disk driver to notify the disk client. The cookie argument is passed as the first argument of this handler. This handler takes a second argument, a request status (DiskStatus), which indicates to the disk client whether the request has been a success or a failure.
On success, a K_OK status is returned. On failure, DiskOps.write returns an error code as follows:
The system is out of memory.
The requested transfer size is invalid. The block_count argument must be greater than 0 and lower than or equal to 256.
For any other errors. For example, done_handler() has returned NULL.
Invocation Context
The DiskOps.write must be called at base level. It is an asynchronous service and can be invoked multiple times, without waiting for command completion.
The disk client can use the DiskOps.get_params service routine to retrieve disk parameters. Disk parameters are given in a DiskParams structure.
void (*get_params) (DiskDevId dev_id, DiskParams* params);
The DiskParams structure is defined as:
typedef struct disk_params { uint8_f serial[20]; /* Serial number (includes '\0') */ uint8_f revision[8]; /* Firmware revision (includes'\0') */ uint8_f model[40]; /* Model number (includes '\0') */ uint16_f config; /* general configuration */ #define DISK_CFG_REMOVABLE 0x0080 #define DISK_CFG_FIXED 0x0040 uint16_f cylinders; /* Number of non-removable cylinders */ uint16_f heads; /* Number of heads */ uint16_f sectors; /* Number of sectors/track */ uint32_f lba_sectors; /* Total count of sectors (LBA adressing) */ int capabilities; /* Capability flags */ #define DISK_CAP_LBA 0x01 } DiskParams;
The dev_id is returned by DiskOps.open. The disk parameters are returned immediately in the memory buffer pointed to by the params argument.
Invocation Context
DiskOps.get_params must be call at base level. It is a synchronous service.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO