Initialization and Device Access

Before performing any CAN system operations, the application must call cyg_can_init(). This function initializes the CAN subsystem and causes all the configured devices to initialize themselves. Only the first call to this function will initialize the subsystem, subsequent calls will do nothing, so libraries and independent systems may call it in their initialization routines without needing to ensure it is called only once.

To gain access to a specific CAN channel, the application must call cyg_can_open(). Channel names are defined in the configuration and are typically "can0" "can1" and so on. If the channel is not found this function will return CYG_CAN_NOTFOUND; it may also return errors generated by the device driver. If the channel is found the call will return CYG_CAN_NOERROR and the location pointed to by the dev parameter will be initialized with a handle on the channel. This handle must be used in all subsequent calls to access this channel.

When the application has finished with a channel it must call cyg_can_close() on the handle.

Buffer Management

The CAN subsystem uses buffers to pass messages between the application and the CAN subsystem. These buffers are allocated and managed by the CAN subsystem. The exact number of buffers is controllable in the configuration.

Each buffer contains the following fields:

A message buffer may be allocated by calling cyg_can_msg_alloc() and freed by calling cyg_can_msg_free().

Transmit and Receive

To transmit a message an application must acquire a message buffer from the CAN subsystem, fill it in with the message to be sent and call cyg_can_send(). Following a successful call the buffer becomes the property of the CAN subsystem and will be returned to the free pool when the message has been transmitted. If an error is detected then the call will return an error code and the message buffer will be returned to the user for reuse or retransmission.

To send a message without waiting for it to complete, the application can call cyg_can_send_nowait().

To receive a message the application calls cyg_can_recv(). If there is a message waiting, then a pointer to the message buffer will be installed in the location pointed to by the msg argument and CYG_CAN_NOERROR is returned.

If the application does no want to wait for a message to arrive, it can call cyg_can_recv_poll() which will just test for a message and return. If a message is present then CYG_CAN_NOERROR is returned and the msg filled in with a pointer to a message buffer. If no message is present then the function will return CYG_CAN_AGAIN.

The application can also wait for a defined length of time for a message to arrive by calling cyg_can_recv_timeout(). The additional timeout argument supplies an absolute timeout in system ticks. If a message is present then CYG_CAN_NOERROR is returned and the msg filled in with a pointer to a message buffer. If no message arrives before the timeout expires then the function will return CYG_CAN_TIMEOUT.

Regardless of which receive function is used, a successful return results in a message buffer being passed back to the caller. The result field of this message buffer will either contain CYG_CAN_NOERROR for a normal message, or it will contain an error code indicating an event that has occurred on the channel. When the application has finished with the buffer it must return it to the CAN subsystem by calling cyg_can_msg_free().

The function cyg_can_poll() may be called to force all channels to check for transmission completion or pending receptions. When using interrupt driven devices it is unnecessary to call this. However, if there are any polled devices, this is the only way to ensure timely processing of received messages. This function should therefore be called from the application main loop, or from a separate timer driven thread, or by any other appropriate means to ensure communication proceeds in a timely fashion.

Basic Filtering

The functions cyg_can_filter_set() and cyg_can_filter_get() allow the basic hardware filter to be set and queried. The basic filter model consists of a match value, such that if an ID when bitwise ANDed with the mask equals mask equals the match value ANDed with the mask, then the message is accepted. If the hardware does not support a filter that conforms to this model then no hardware filtering is done, but the filter will still be applied by the CAN subsystem to all incoming packets.

In cyg_can_filter_set(), the match and mask arguments define the filter. The ide indicates whether the filter is for normal or extended IDs. It is hardware dependent what happens when the filter ID size does not match the ID size being used on the network.

Extended Filtering

The functions cyg_can_filter_ext_set() and cyg_can_filter_ext_get() implement an extended filtering mechanism. In this case the application can submit an array of filters which will accept a message if any one of them matches the received ID. If it is possible, extended filtering will be implemented in the CAN controller hardware. Otherwise it will be implemented in software. Setting the extended filters will invalidate the basic filter and vice versa.

The filters are an array of cyg_can_filter structures. Each filter consists of a mask and a match field. For each filter, if the received ID bitwise ANDed with the mask equals the match field ANDed with the mask, then the message is accepted. In addition to the 11 or 29 bits of the ID, the mask and match fields can contain two extra bits: CYG_CAN_FILTER_IDE matches the message IDE bit for 29 bit addressing, and CYG_CAN_FILTER_RTR matches the message RTR bit.

Some care should be taken in setting the IDE and RTR bits in the filters. In general, if the intention is to match on either bit, then it should be set in both fields. Setting the bit only in the mask field will match packets that have the bit clear, which is unlikely to be what it wanted. Incoming message IDs are only matched against similarly sized filters: a message with a 29 bit ID is only matched against filters that have the IDE bits set, and 11 bit ID are only matched against filters with IDE clear. This approach is to ensure consistency between software and hardware filters, and between different hardware filters.

In cyg_can_filter_ext_set() the filters argument is the address of the filter array, and len defines the number of elements. An error will be returned if the filters are invalid or the list is too long. In cyg_can_filter_ext_get(), the *len argument is a pointer to the length; it should be set to the size of the filters array before the call and will be updated with the number of actual filters returned. If the filters argument is NULL, the number of filters set will be returned in *len. If the number of filters set is larger than the value of *len, or if no extended filters are set, then an error will be returned.

The configuration option CYGNUM_IO_CAN_FILTER_MAX describes the maximum number of extended filters than can be stored. Usually controller drivers will set this value according to the amount of hardware resource available in the filter system.

Baud Rate

The functions cyg_can_baud_set() and cyg_can_baud_get() allow the channel baud rate to be set and queried. Baud rates from 10kb/s to 1Mb/s may be set, although not all device drivers will necessarily support all rates, many will only support a subset. Also, due to interactions between the input clock to the device and the divider granularity, it may not be possible to set some baud rates accurately at some system clock rates; it may be necessary to alter the system clock speed to enable communication.

The functions cyg_can_baud_fd_set() and cyg_can_baud_fd_get() allow the channel FD baud rate to be set and queried. When an FD format message is sent or received, the data bytes will be transmitted at this rate rather than the standard rate.

Autobaud Support

The function cyg_can_autobaud() supports automatic baud rate detection. This will only be present if the controller driver supports autobaud or listen-only mode. It indicates this by implementing the CYGINT_IO_CAN_AUTOBAUD interface. If the driver does no support this feature then this function will not be defined.

The approach for baud detection is to switch the controller to listen-only mode, where it cannot affect the bus state. Each of a set of candidate baud rates are set and the function waits for a period of time for a valid packet to arrive. If no packet is seen, then attention moves to the next baud rate. If a packet is received, then that baud rate is selected and set in the controller in non-listen-mode. If no packets are seen at any baud rate, the original rate is restored to the controller.

There are two configuration options that control the behaviour of the autobaud mechanism:

Autobaud support comes with a number of caveats. Baud detection depends on traffic being present on the CAN bus and being frequent enough for packets to be seen during the timeout period for each candidate baud rate. Some baud rates may not be supportable by the controller. If there is only one other node in the network sending packets, the lack of acknowledgements may cause it to move into Error Passive or Bus Off mode and stop transmitting. Consequently autobaud detection cannot be considered to be a fully reliable operation and it is quite possible for cyg_can_autobaud() to terminate without detecting the baud rate. The length of time taken to detect the baud rate may be as long as the number of candidate rates multiplied by the timeout period.

Errors

Many of the CAN API calls return error codes. The result field of the message buffer structure may also contain an error code from this set. The following error codes may be returned by API calls:

The following error codes may be passed back in the result field of a message buffer acquired from one of the receive functions. Refer to the CAN specification for details of what these events actually mean.

The cyg_can_error_string() function translates these error codes into strings for diagnostic purposes.