Arguments

module_name

The "C" label for this devtab entry

device_name

The "C" string for the device. E.g. /dev/serial0.

cyg_io_disk_devio

The table of I/O functions. This set is defined in the hardware independent disk driver and should be used exactly as shown here.

module_init

The module initialization function.

module_lookup

The device lookup function. This function typically sets up the device for actual use, turning on interrupts, configuring the controller, etc.

disk_channel

This table (defined below) contains the interface between the interface module and the disk driver proper.

Arguments

l

The "C" label for this structure.

dev_priv

A placeholder for any device specific data for this controller.

Arguments

l

The "C" label for this structure.

funs

The set of interface functions (see below).

dev_priv

A placeholder for any device specific data for this channel.

controller

Pointer to controller to which this disk channel is attached.

mbr_supp

Does this disk support partitioning.

max_part_num

The maximum number of partitions to be supported.

Arguments

dc

The name of an object of type disk_channel. This object will be initialised by the macro.

disk_info

The name of an object of type disk_info.

part_dev_tab

The name of an array of objects of type struct cyg_devtab_entry. The number of array members must equal max_part_num, plus one.

part_chan_tab

The name of an array of objects of type disk_channel. The number of array members must equal max_part_num.

part_tab

The name of an array of objects of type cyg_disk_partition_t. The number of array members must equal max_part_num.

Arguments

l

The "C" label for this structure.

read

Cyg_ErrNo (*read)(disk_channel *priv,
                  void         *buf,
                  cyg_uint32    len,
                  cyg_uint32    block_num)

This function reads len sectors of data from the disk at the sector number given by block_num. The actual quantity of data transferred depends on the disk's sector size, which can be obtained using the CYG_IO_GET_CONFIG_DISK_INFO key.

If the read completes immediately, or the low level driver is configured to do all IO synchronously, this function will return ENOERR, and if it fails will return a negative error code, for example -EIO. If the function returns -EWOULDBLOCK then it has only started the transfer and will indicate its completion by calling the transfer_done callback.

write

Cyg_ErrNo (*write)(disk_channel *priv,
                   void         *buf,
                   cyg_uint32    len,
                   cyg_uint32    block_num)

This function writes len sectors of data to the disk at the block given by block_num. The actual quantity of data transferred depends on the disk's sector size, which can be obtained using the CYG_IO_GET_CONFIG_DISK_INFO key.

If the write completes immediately, or the low level driver is configured to do all IO synchronously, this function will return ENOERR, and if it fails will return a negative error code, for example -EIO. If the function returns -EWOULDBLOCK then it has only started the transfer and will indicate its completion by calling the transfer_done callback.

get_config

bool (*get_config)(serial_channel *priv,
                   cyg_uint32 key, const void *xbuf, cyg_uint32 *len);
      )

This function is used to get configuration data from the device. The key argument defines the configuration data to be fetched. The xbuf and *len arguments describe a buffer into which the data will be put. The function should return true if the key type is supported and the buffer of sufficient length to contain the data. The value of *len should be updated to actual length of the data returned. The function should return false if the driver cannot support the key value or the buffer is of insufficient length.

The following keys may be used to get information from a disk device.

CYG_IO_GET_CONFIG_DISK_INFO

This key causes a cyg_disk_info_t structure, as defined in diskio.h to be returned.

CYG_IO_GET_CONFIG_DISK_EVENT

This key returns a copy of the cyg_disk_event_t previously set by CYG_IO_SET_CONFIG_DISK_EVENT.

set_config

bool (*set_config)(serial_channel *priv,
                   cyg_uint32 key, const void *xbuf, cyg_uint32 *len);
      )

This function is used to change the configuration of the device. The key argument defines the kind of configuration data to be set. The xbuf and *len arguments describe a buffer in which the data is supplied. The function should return true if the key type is supported and the buffer of the correct length and the data appears valid. The function should return false if the driver cannot support the key value or the buffer is the wrong length, or the data is invalid in some other way.

The following keys can be sent to a driver:

CYG_IO_SET_CONFIG_DISK_MOUNT

This is invoked from the filesystem after locating the device driver to record that the device has been mounted. The generic device layer records the mount against both the partition and physical disk and passes the call on down to the driver. The xbuf and *len arguments are unused.

CYG_IO_SET_CONFIG_DISK_UMOUNT

This is invoked from the filesystem to record that the device has been unmounted. The generic device layer records the unmount against both the partition and physical disk and passes the call on down to the driver. If the chan->info->mounts counter is zero, the driver should call the disk_disconnected() callback to prepare the generic layer for a potential media change. The xbuf and *len arguments are unused.

CYG_IO_SET_CONFIG_DISK_EVENT

This may be invoked by the application to set a disk event callback function. The generic disk layer is mostly responsible for handling this by recording the event function in the disk channel structure. The call is additionally passed down to the hardware driver so that it may prepare the hardware, if necessary. The xbuf should point to a cyg_disk_event_t structure.

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.