Chapter 32. User API

The CAN driver uses the standard eCos I/O API functions. 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 values will be ENOERR, -EINTR, -EINVAL and -EAGAIN. 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 len 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 CAN device and return its handle 
Cyg_ErrNo cyg_io_lookup( 
    const char *name,
    cyg_io_handle_t *handle )

This function maps a CAN 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.

// Send a CAN message
Cyg_ErrNo cyg_io_write( 
    cyg_io_handle_t handle,
    const void *buf,
    cyg_uint32 *len )

This function sends one single CAN message (not a buffer of CAN messages) 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 one CAN event from device
Cyg_ErrNo cyg_io_read( 
    cyg_io_handle_t handle,
    void *buf,
    cyg_uint32 *len )

This function receives one single CAN event 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.

You may notice that the data sent (messages) is different from the data received (events). An event includes flags that describe the event, and eventually a received message and a timestamp.

// Read configuration of a CAN 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 are all listed in the file <cyg/io/config_keys.h>.

// Change configuration of a CAN 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 are all listed in the file <cyg/io/config_keys.h>.