Subversion Repositories openrisc

The Controller Area Network, CAN, is a multicast shared, differential

serial bus standard especially suited for networking "intelligent"

devices as well as sensors and actuators within a system or sub-system.

The protocol was originally developed in the 1980s by Robert Bosch GmbH

aiming at automotive applications. Nowadays CAN has gained widespread use

and is used in industrial automation as well as in automotive, mobile

machines and in many embedded control applications.

The CAN protocol is defined by the ISO 11898-1 standard. The physical layer

uses differential transmission on a twisted pair wire.  CAN uses a

non-destructive bit-wise arbitration to control access to the bus.

There is no explicit address in the messages because in CAN networks there

is no addressing of subscribers or stations, but instead, each message carries

a prioritized identifier. A transmitter sends a message to all CAN nodes

(broadcasting). The identifier may serve as an identification of the contents

of the message and also determines the priority that the message enjoys in

competition for bus access. A node decides on the basis of this identifier

received whether it should process the message or not.

The CAN messages are small (at most eight data bytes) and are protected

by a checksum. Each CAN message consists of  an 11 bit message ID, up to 8

bytes of data and, a CRC checksum and a number of  control bits. These

short messages ensure a robust transfer of data in electromagnetically

noisy environments. An extended version of the CAN frame supports 29 bit

message identifiers.

Basically there are two different operational modes for CAN receivers -

FullCAN and BasicCAN.  The difference between these two modes is the

Object Storage function. The BasicCAN architecture is quite similar to a

simple UART. A BasicCAN device has typically one transmit buffer and two

receive buffers. The CAN chip handles only the transmitting and receiving

of the data (and the error handling) and so most of the manipulation of the

data has to be done by the CPU. The CPU has to request the transmitting or

acknowledge the receiving of the data through the interrupt flags. This will

burden the CPU and take up much of the CPU time.

The FullCAN architecture is more suitable for high-speed performance. It

has its own storage area on chip and works with a number of message buffers

or message boxes. The CAN controller has its own Acceptance Filtering Mask

on chip. It can thus determine which frames are to be received by examining

the identifiers. The CPU in this case will only receive the valid (wanted)

frames and hence improve the performance of the CPU.

You can find more information at the

CAN in Automation website.

The eCos CAN subsystem supports the BasicCAN and FullCAN mode. The architecture

and the interface of the eCos CAN driver is quite similar to the eCos serial

driver and supports the same interface.

The eCos CAN support for any given platform is spread over a number of different

packages:

This package, CYGPKG_IO_CAN, exports a generic

device independent CAN I/O API for accessing devices attached to a CAN

network. This API handles issues such as locking between threads. The

package does not contain any hardware-specific code. Instead it will

call into a CAN device driver to handle the hardware device

access. This package also defines the interface that such hardware

drivers should provide.

Each CAN device will have its own device driver, which is implemented

as a separate package, for example

CYGPKG_DEVS_CAN_MCF52xx_FLEXCAN. For devices that may

be attached to a variety of different boards the device driver will be

generic and a second platform specific package will be used to customize

it to each platform. For devices that are associated with a specific

chipset, only a single package may be present.

Typically all appropriate packages will be loaded automatically when

you configure eCos for a given platform. If the application does not use

any of the CAN I/O facilities, directly or indirectly, then linker garbage

collection should eliminate all unnecessary code and data. All necessary

initialization should happen automatically. However the exact details may

depend on the platform, so the platform HAL documentation should be

checked for further details.

There is an important exception to this: if the CAN devices are attached

to an expansion connector, such as PCI, then the platform HAL will not

know about these devices. Instead the necessary packages will need to be

added explicitly during configuration.

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>.

Allow applications and other packages to access CAN devices.

A raw CAN driver is is provided as a standard part of the eCos system.

Use the include file <cyg/io/canio.h> for this driver.

The CAN driver is capable of sending single CAN messages to a device and

receiving single CAN events from a CAN device. Controls are provided to

configure the actual hardware, but there is no manipulation of the data by

this driver.

There may be many instances of this driver in a given system, one for each

CAN channel. Each channel corresponds to a physical device and there will

typically be a device module created for this purpose. The device modules

themselves are configurable, allowing specification of the actual hardware

details.

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 successfully sent, the function returns ENOERR.

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(handle, buf, len)

To receive a message the application calls cyg_io_read().

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 read 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 an event was successfully received, the function returns ENOERR.

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_event_flags_t flags;

    cyg_can_message msg;

} 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_event_flags_t flags

Event flags. The flags field contains bits that

indicate which kind of events occured. More than one flag can be raised

in a single event.

       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.

The following events are supported and after receiving an event the

application should check the flags field against these values:

CYGNUM_CAN_EVENT_RX               0x00000001 // message received

CYGNUM_CAN_EVENT_TX               0x00000002 // mesage transmitted

CYGNUM_CAN_EVENT_WARNING_RX       0x00000004 // tx error counter (TEC) reached warning level (>96)

CYGNUM_CAN_EVENT_WARNING_TX       0x00000008 // rx error counter (REC) reached warning level (>96)

CYGNUM_CAN_EVENT_ERR_PASSIVE      0x00000010 // CAN "error passive" occured

CYGNUM_CAN_EVENT_BUS_OFF          0x00000020 // CAN "bus off" error occured

CYGNUM_CAN_EVENT_OVERRUN_RX       0x00000040 // overrun in RX queue occured

CYGNUM_CAN_EVENT_OVERRUN_TX       0x00000080 // overrun in TX queue occured

CYGNUM_CAN_EVENT_CAN_ERR          0x00000100 // a CAN bit or frame error occured

CYGNUM_CAN_EVENT_LEAVING_STANDBY  0x00000200 // CAN hardware leaves standby / power down mode or is waked up

CYGNUM_CAN_EVENT_ENTERING_STANDBY 0x00000400 // CAN hardware enters standby / power down mode

CYGNUM_CAN_EVENT_ARBITRATION_LOST 0x00000800 // arbitration lost

CYGNUM_CAN_EVENT_FILTER_ERR       0x00001000 // CAN message filter / acceptance filter error

CYGNUM_CAN_EVENT_PHY_FAULT        0x00002000 // General failure of physical layer detected

CYGNUM_CAN_EVENT_PHY_H            0x00004000 // Fault on CAN-H detected (Low Speed CAN)

CYGNUM_CAN_EVENT_PHY_L            0x00008000 // Fault on CAN-L detected (Low Speed CAN)

CYGNUM_CAN_EVENT_ERR_ACTIVE       0x00010000 // CAN controller now "error active"

CYGNUM_CAN_EVENT_OVERRUN_RX_HW    0x00020000 // CAN controller reports a RX overrun

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.  Most of the flags are independent

from each other and the receiver has to handle each of them separately.

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 the 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. However if an

overrun occurs in the hardware message buffers of the CAN controller,

the flag CYGNUM_CAN_EVENT_OVERRUN_RX_HW is raised

instead.

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(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(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

CYG_IO_SET_CONFIG_CAN_RANGE_FILTER

CYG_IO_SET_CONFIG_CAN_MASK_FILTER

Runtime configuration is achieved by exchanging data structures with the

driver via the cyg_io_set_config() and

cyg_io_get_config() functions.

typedef struct cyg_can_info_st {

    cyg_can_baud_rate_t baud;

} cyg_can_info_t;

Device configuration is achieved by by exchanging

cyg_can_info_t data structures with the driver

via the cyg_io_set_config() and

cyg_io_get_config() functions using the config keys

CYG_IO_GET_CONFIG_CAN_INFO and

CYG_IO_SET_CONFIG_CAN_INFO.

The field baud contains a baud rate selection.

This must be one of the following values:

CYGNUM_CAN_KBAUD_10

CYGNUM_CAN_KBAUD_20

CYGNUM_CAN_KBAUD_50

CYGNUM_CAN_KBAUD_100

CYGNUM_CAN_KBAUD_125

CYGNUM_CAN_KBAUD_250

CYGNUM_CAN_KBAUD_500

CYGNUM_CAN_KBAUD_800

CYGNUM_CAN_KBAUD_1000

typedef struct cyg_can_timeout_info_st

{

    cyg_uint32 rx_timeout;

    cyg_uint32 tx_timeout;

} cyg_can_timeout_info_t;

Timeout configuration is achieved by by exchanging

cyg_can_timeout_info_t data structures with the

driver via the cyg_io_set_config() and

cyg_io_get_config() functions using the config keys

CYG_IO_SET_CONFIG_CAN_TIMEOUT and

CYG_IO_SET_CONFIG_CAN_TIMEOUT.

       cyg_uint32 rx_timeout

Timeout for cyg_io_read calls.

       cyg_uint32 tx_timeout

Timeout for cyg_io_write calls.

Timeout runtime configuration is supported if the configuration options

CYGOPT_IO_CAN_SUPPORT_NONBLOCKING

and CYGOPT_IO_CAN_SUPPORT_TIMEOUTS are enabled.

typedef struct cyg_can_buf_info_st

{

    cyg_int32 rx_bufsize;

    cyg_int32 rx_count;

    cyg_int32 tx_bufsize;

    cyg_int32 tx_count;

} cyg_can_buf_info_t;

CYG_IO_GET_CONFIG_CAN_BUFFER_INFO - This function

retrieves the current state of the software buffers in the CAN drivers.

For the transmit buffer it returns the the total number of

cyg_can_message objects in buffer and the current number of

cyg_can_message objects occupied in the buffer.

For the receive buffer it returns the total number of

cyg_can_event objects in receive buffer and the current

number of cyg_can_event objects occupied in the buffer.

It does not take into account any buffering such as FIFOs or holding

registers that the CAN hardware device itself may have.

       cyg_uint32 rx_bufsize

Total number of cyg_can_event buffers in receive queue.

       cyg_uint32 rx_count

Current number of cyg_can_event buffers occupied in receive queue.

       cyg_uint32 tx_bufsize

Total number of cyg_can_message buffers in transmit queue.

       cyg_uint32 rtx_count

Current number of cyg_can_message buffers occupied in transmit queue.

typedef struct cyg_can_hdi_st

{

    cyg_uint8 support_flags;

    cyg_uint8 controller_type;

} cyg_can_hdi;

CYG_IO_GET_CONFIG_CAN_HDI - This function retrieves

information about the used hardware. The Hardware Description Interface

provides a method to gather information about the CAN hardware and the

functionality of the driver. For this purpose the structure

cyg_can_hdi is defined.

       cyg_uint8 support_flags

Contains information about the capabilities of the used CAN hardware.

       cyg_uint8 controller_type

A number that identifies the CAN controller type.

The following flags are available in the field support_flags: