Callbacks

The interface from the hardware specific driver to the hardware independent driver is contained in a disk_callbacks_t structure. A pointer to this is automatically included into the disk channel structure callbacks field by the DISK_CHANNEL() macro. The disk_callbacks_t structure contains the following function pointers:

disk_init

cyg_bool (*disk_init)(struct cyg_devtab_entry *tab);

Initialize the disk. This must be called from the disk driver's init routine to initialize the device independent driver's data structures for this disk.

disk_connected

Cyg_ErrNo (*disk_connected)(struct cyg_devtab_entry *tab, cyg_disk_identify_t *ident);

This is called when a valid disk device has been recognised on the given disk channel. At this point, if the disk supports partitioning the disk's partition table will be read and the partitions determined. This may be called either from the driver's init routine, for fixed disks, or alternatively from the driver's lookup routine. It may also be called from other places when, for example, disk insertion is detected. All the fields of the ident structure must be filled in by the driver before this call is made.

disk_disconnected

Cyg_ErrNo (*disk_disconnected)(struct disk_channel *chan);

This is called when, for example, disk removal is detected. It invalidates all the existing partition and driver information and renders the channel ready for a new disk device to be inserted.

disk_lookup

Cyg_ErrNo (*disk_lookup)(struct cyg_devtab_entry **tab, struct cyg_devtab_entry *sub_tab, const char *name);

This must be called from the driver's lookup function to complete the lookup process. It is here that the interpretation of the partition number element of the device name is done and a new devtab entry created for the partition if necessary.

disk_transfer_done

void (*disk_transfer_done)(struct disk_channel *chan, Cyg_ErrNo res);

When the call to the read() or write() disk function returns -EWOULDBLOCK then the driver must indicate completion of the actual transfer by calling this function. This function should not be called from an ISR, but it may be called from the DSR.

In addition to these functions in disk_callbacks_t, the hardware driver is also responsible for calling the disk event callback. The calls should be made as follows:

    disk_channel *chan = <get pointer to disk channel>;

    ...

    chan->event( CYG_DISK_EVENT_CONNECT, devno, chan->event_data );

The first argument should be the event being notified: CYG_DISK_EVENT_CONNECT as shown here, or CYG_DISK_EVENT_DISCONNECT. The second argument is a device number; this is needed for devices that dynamically instantiate disk devices, such as USB. If the driver does not do this, then this argument should be -1. The third argument is the user data value passed in when the callback was registered.

The driver may call this function at any time and from any context other than an ISR. Normally it will be called either from a DSR or from a thread context. By default, the generic disk layer will install a dummy function in the disk channel structure, so the driver can always make the call without needing to test for a NULL pointer. A CONNECT event call should be made when the driver detects that a new device has been inserted into the drive, and an DISCONNECT event call should be made when the device is removed.

A CONNECT event call should also be made if a disk device is already connected when the driver observes the application registering for notification of disk events by use of the CYG_IO_SET_CONFIG_DISK_EVENT cyg_io_set_config() operation. However, this only applies to connected disks - the driver does not indicate DISCONNECT events for unconnected disks.