eCos Reference Manual
Prev | Chapter 32. CAN driver details | Next

# API Details

## cyg_io_write

    cyg_io_write(handle, buf, len)

To transmit a message an application must fill a cyg_can_message buffer and call `cyg_io_write()`. 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. A pointer to a cyg_can_message is contained in `*buf`. The driver maintains a buffer to hold the data. The size of the intermediate buffer is configurable within the interface module. The data is not modified at all while it is being buffered. On return, `*len` contains the amount of characters actually consumed - that means `*len` always contains `sizeof(cyg_can_message)`.

It is possible to configure the write call to be blocking (default) or non-blocking. Non-blocking mode requires both the configuration option `CYGOPT_IO_CAN_SUPPORT_NONBLOCKING` to be enabled, and the specific device to be set to non-blocking mode for writes (see `cyg_io_set_config()`). In blocking mode, the call will not return until there is space in the buffer and the content of the CAN message has been consumed. In non-blocking mode, if there is no space in buffer for the CAN message, `-EAGAIN` is returned and the caller must try again.

It is possible to configure the write call to be non-blocking with timeout. None-blocking mode with timeout requires the configuration option `CYGOPT_IO_CAN_SUPPORT_NONBLOCKING` and `CYGOPT_IO_CAN_SUPPORT_TIMEOUTS` to be enabled, requires the eCos kernel package to be included and the specific device to be set to non-blocking mode for writes (see `cyg_io_set_config()`). In non-blocking mode with timeouts, if there is no space in buffer for the CAN message, the driver waits a certain amount of time (the timeout time) for space in the buffer. If there is still no space in buffer after expiration of the timeout time, `-EINTR` is returned and the caller must try again.

If a message was sucessfully sent, the function returns `ENOERR`.

## CAN Messages

The CAN driver uses `cyg_can_message` structures to pass messages between the application and the CAN driver. The type cyg_can_message provides a device independent type of CAN message. Before calling the write function this message should be setup properly.

    typedef struct can_message
    {
        cyg_uint32         id;
        cyg_uint8          data[8];
        cyg_can_id_type    ext;
        cyg_can_frame_type rtr;
        cyg_uint8          dlc;
    } cyg_can_message;

The structure contains the following fields:

cyg_uint32 `id`

  Message ID. This is the ID to be transmitted with the message, or the ID received. If the `ext` field is set, then this will contain a 29 bit ID, otherwise it will contain an 11 bit ID.

cyg_uint32 `data`

  Message data. Only the first `dlc` bytes of data are valid. If the `rtr` field is set, then the contents of this field are ignored.

cyg_can_id_type `ext`

  Extended ID. If this field is `CYGNUM_CAN_ID_EXT` then the `id` field contains a 29 bit extended ID. If it contains `CYGNUM_CAN_ID_STD` then the ID is 11 bits.

cyg_can_frame_type `rtr`

  Remote Transmission Request. If this field contains `CYGNUM_CAN_FRAME_RTR` then the RTR bit on the message will be set and the `data` field will be ignored. If the field contains `CYGNUM_CAN_FRAME_DATA` then a normal data frame will be send.

cyg_uint8 `dlc`

  The length of the data carried in the message. This can range from zero to 8. In a message with the `rtr` field set, this indicates the size of data being requested.

Example code for sending one single CAN message:

    cyg_can_message tx_msg;
    cyg_uint32      len;
    Cyg_ErrNo       ret;

    tx_msg.id  = 0x100;
    tx_msg.ext = CYGNUM_CAN_ID_EXT;
    tx_msg.rtr = CYGNUM_CAN_FRAME_DATA;
    tx_msg.dlc = 1;
    tx_msg.data[0] = 0xF1;

    len = sizeof(tx_msg);
    ret = cyg_io_write(hDrvCAN, &tx_msg, &len);

## cyg_io_read

    cyg_io_read(handle, buf, len)

To receive a message the application calls `cyg_can_recv()`. This function receives one single 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. A pointer to a cyg_can_event is contained in `*buf`. No manipulation of the data is performed before being transferred. Again, this buffering is completely configurable. On return, `*len` contains `sizeof(cyg_can_event)`.

It is possible to configure the read call to be blocking (default) or non-blocking. Non-blocking mode requires both the configuration option `CYGOPT_IO_CAN_SUPPORT_NONBLOCKING` to be enabled, and the specific device to be set to non-blocking mode for reads (see `cyg_io_set_config()`). In blocking mode, the call will not return until one single CAN event has been read. In non-blocking mode, if there is no CAN event in buffer, the call returns immediately with `-EAGAIN` and the caller must try again.

It is possible to configure the write call to be non-blocking with timeout. None-blocking mode with timeout requires the configuration option `CYGOPT_IO_CAN_SUPPORT_NONBLOCKING` and `CYGOPT_IO_CAN_SUPPORT_TIMEOUTS` to be enabled, requires the eCos kernel package to be included and the specific device to be set to non-blocking mode for reads (see `cyg_io_set_config()`). In non-blocking mode with timeouts, if there is no CAN event in receive buffer, the driver waits a certain amount of time (the timeout time) for a CAN event to arrive. If there is still no CAN event in buffer after expiration of the timeout time, `-EINTR` is returned and the caller must try again.

If a event was sucessfully received, the function returns `ENOERR`.

## CAN Events

The CAN driver uses `cyg_can_event` structures to pass events from hardware device driver to the generic CAN driver. A `cyg_can_event` provides a generic device independent type for handling CAN events that may occur.

    typedef struct cyg_can_event_st
    {
        cyg_uint32      timestamp;
        cyg_can_message msg;
        cyg_uint16      flags;
    } cyg_can_event;

The structure contains the following fields:

cyg_uint32 `timestamp`

  If the hardware CAN device driver supports timestamps then this field may contain a timestamp value for an event that occured.

cyg_can_message `msg`

  CAN message. The msg field contains a CAN message if an RX or TX event occured. If another type of event occured, the `data` field of the `msg` may contain additional event specific data.

cyg_uint16 `flags`

  Event flags. The `flags` field contains 16 bits that indicate which kind of events occured.

The following events are supported and after receiving an event the application should check the flag field against these values:

    typedef enum
    {
      CYGNUM_CAN_EVENT_RX               = 0x0001, // message received
      CYGNUM_CAN_EVENT_TX               = 0x0002, // message transmitted
      CYGNUM_CAN_EVENT_WARNING_RX       = 0x0004, // (TEC) reached warning level (>96)
      CYGNUM_CAN_EVENT_WARNING_TX       = 0x0008, // (REC) reached warning level (>96)
      CYGNUM_CAN_EVENT_ERR_PASSIVE      = 0x0010, // CAN "error passive" occured
      CYGNUM_CAN_EVENT_BUS_OFF          = 0x0020, // CAN "bus off" error occured
      CYGNUM_CAN_EVENT_OVERRUN_RX       = 0x0040, // overrun in RX queue or hardware
      CYGNUM_CAN_EVENT_OVERRUN_TX       = 0x0080, // overrun in TX queue occured
      CYGNUM_CAN_EVENT_CAN_ERR          = 0x0100, // a CAN bit or frame error occured
      CYGNUM_CAN_EVENT_LEAVING_STANDBY  = 0x0200, // CAN hardware leaves standby
      CYGNUM_CAN_EVENT_ENTERING_STANDBY = 0x0400, // CAN hardware enters standby
      CYGNUM_CAN_EVENT_ARBITRATION_LOST = 0x0800, // arbitration lost
      CYGNUM_CAN_EVENT_FILTER_ERR       = 0x1000, // CAN message filter / acceptance filter error
      CYGNUM_CAN_EVENT_PHY_FAULT        = 0x2000, // General failure of physical layer
      CYGNUM_CAN_EVENT_PHY_H            = 0x4000, // Fault on CAN-H (Low Speed CAN)
      CYGNUM_CAN_EVENT_PHY_L            = 0x8000, // Fault on CAN-L (Low Speed CAN)
    } cyg_can_event_flags;

Often the flags field will contain only one single set flag. But it is possible that a number of flags is set and so the flag field should always be checked by a receiver. I.e. if the `CYGNUM_CAN_EVENT_RX` is set then also the `CYGNUM_CAN_EVENT_OVERRUN_RX` may be set if the received message caused an RX overrun.

The internal receive buffers of the CAN device driver are circular buffers. That means that even if the buffers are completely filled new messages will be received. In this case the newest message will always overwrite the oldest message in receive buffer. If this happens the `CYGNUM_CAN_EVENT_OVERRUN_RX` flag will be set for this new message that caused overwriting of the old one. The `CYGNUM_CAN_EVENT_OVERRUN_RX` flag will be set also if a overrun occures in hardware message buffers of the CAN device.

Example code for receiving one single CAN event:

    cyg_can_event rx_event;
    cyg_uint32    len;
    Cyg_ErrNo     ret;

    len = sizeof(rx_event);
    ret = cyg_io_read(hDrvCAN, &rx_event, &len);

    if (ENOERR == ret)
    {
        if (rx_event.flags & CYGNUM_CAN_EVENT_RX)
        {
            // handle RX event
        }

        if (rx_event.flags & ~CYGNUM_CAN_EVENT_RX)
        {
            // handle other events
        }
    }
    else if (-EINTR == ret)
    {
        // handle timeout
    }

## cyg_io_get_config

    cyg_io_get_config(handle, key, buf, 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>`.

The following config keys are currently supported:

    CYG_IO_GET_CONFIG_READ_BLOCKING
    CYG_IO_GET_CONFIG_WRITE_BLOCKING
    CYG_IO_GET_CONFIG_CAN_INFO
    CYG_IO_GET_CONFIG_CAN_BUFFER_INFO
    CYG_IO_GET_CONFIG_CAN_MSGBUF_INFO
    CYG_IO_GET_CONFIG_CAN_TIMEOUT
    CYG_IO_GET_CONFIG_CAN_HDI
    CYG_IO_GET_CONFIG_CAN_STATE

## cyg_io_set_config

    cyg_io_set_config(handle, key, buf, 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>`.

The following config keys are currently supported:

    CYG_IO_SET_CONFIG_READ_BLOCKING
    CYG_IO_SET_CONFIG_WRITE_BLOCKING
    CYG_IO_SET_CONFIG_CAN_INFO
    CYG_IO_SET_CONFIG_CAN_OUTPUT_DRAIN
    CYG_IO_SET_CONFIG_CAN_OUTPUT_FLUSH
    CYG_IO_SET_CONFIG_CAN_INPUT_FLUSH
    CYG_IO_SET_CONFIG_CAN_TIMEOUT
    CYG_IO_SET_CONFIG_CAN_MSGBUF
    CYG_IO_SET_CONFIG_CAN_MODE
    CYG_IO_SET_CONFIG_CAN_ABORT
    CYG_IO_SET_CONFIG_CAN_CALLBACK

Prev | Home | Next
CAN driver details | Up | Runtime Configuration