Chapter 11. User API

All functions, except cyg_io_lookup() require an I/O “handle”.

All functions return a value of the type Cyg_ErrNo. If an error condition is detected, this value will be negative and the absolute value indicates the actual error, as specified in cyg/error/codes.h. The only other legal return value will be ENOERR. All other function arguments are pointers (references). This allows the drivers to pass information efficiently, both into and out of the driver. The most striking example of this is the “length” value passed to the read and write functions. This parameter contains the desired length of data on input to the function and the actual transferred length on return.

// Lookup a device and return its handle 
  Cyg_ErrNo cyg_io_lookup( 
    const char *name,
    cyg_io_handle_t *handle )

This function maps a device name onto an appropriate handle. If the named device is not in the system, then the error -ENOENT is returned. If the device is found, then the handle for the device is returned by way of the handle pointer *handle.

// Write data to a device 
Cyg_ErrNo cyg_io_write( 
    cyg_io_handle_t handle,
    const void *buf,
    cyg_uint32 *len )

This function sends data to a device. The size of data to send is contained in *len and the actual size sent will be returned in the same place.

// Read data from a device 
Cyg_ErrNo cyg_io_read( 
    cyg_io_handle_t handle,
    void *buf,
    cyg_uint32 *len )

This function receives data from a device. The desired size of data to receive is contained in *len and the actual size obtained will be returned in the same place.

// Get the configuration of a device 
Cyg_ErrNo cyg_io_get_config( 
    cyg_io_handle_t handle,
    cyg_uint32 key,
    void *buf,
    cyg_uint32 *len )

This function is used to obtain run-time configuration about a device. The type of information retrieved is specified by the key. The data will be returned in the given buffer. The value of *len should contain the amount of data requested, which must be at least as large as the size appropriate to the selected key. The actual size of data retrieved is placed in *len. The appropriate key values differ for each driver and are all listed in the file <cyg/io/config_keys.h>.

// Change the configuration of a device 
Cyg_ErrNo cyg_io_set_config( 
    cyg_io_handle_t handle,
    cyg_uint32 key,
    const void *buf,
    cyg_uint32 *len )

This function is used to manipulate or change the run-time configuration of a device. The type of information is specified by the key. The data will be obtained from the given buffer. The value of *len should contain the amount of data provided, which must match the size appropriate to the selected key. The appropriate key values differ for each driver and are all listed in the file <cyg/io/config_keys.h>.