Detailed Description

PRELIMINARY CAN driver interface

WARNING These APIs are PRELIMINARY, and subject to change in the next few months.

To use the CAN driver, ensure that the correct driver library for your device is linked in and include this header file as follows:

#include <ti/drivers/CAN.h>

This module serves as the main interface for applications. Its purpose is to redirect the CAN APIs to specific driver implementations which are specified using a pointer to a CAN_FxnTable.

Overview

The Controller Area Network (CAN) driver is a generic driver that allows for communication on a CAN bus. It is a two-wire, half-duplex, LAN system that is collision free. The main method of transfer is by broadcasting. The CAN protocol defines the format of data transfer, and this CAN driver allows full functionality as a transmitting and receiving node on a bus. However, there can be higher-level software layers and stacks that use this driver to enable more advanced features. Functional modes available in this driver include blocking and non-blocking.

The APIs in this driver serve as an interface to a typical RTOS application. The specific peripheral implementations are responsible for creating all the RTOS specific primitives to allow for thread-safe operation.

Usage

The CAN driver interface provides device independent APIs, data types, and macros.

Synopsis

The following code example opens a CAN instance, creates an incrementing CAN frame, and continually writes them to the CAN bus. NOTE: a CAN receiver on this bus is needed, or else this transmitter will continually throw an error if it does not detect an ACK.

uint8_t i;
// Initialize the CAN driver
CAN_init();
CAN_Handle canHandle;
CAN_Params canParams;
CAN_Params_init(&canParams);
canHandle = CAN_open(CONFIG_CAN0, &canParams);
if (canHandle == NULL) {
    // CAN_open() failed
    while (1);
}
for (i = 0; ; ++i) {
    CAN_Frame canFrame[1];
    canFrame[0].can_id = i;
    canFrame[0].err = 0;
    canFrame[0].rtr = 0;
    canFrame[0].eff = 1;
    canFrame[0].dlc = i % 9;
    canFrame[0].data[0] = i;
    canFrame[0].data[1] = i + 1;
    canFrame[0].data[2] = i + 2;
    canFrame[0].data[3] = i + 3;
    canFrame[0].data[4] = i + 4;
    canFrame[0].data[5] = i + 5;
    canFrame[0].data[6] = i + 6;
    canFrame[0].data[7] = i + 7;
    CAN_write(canHandle, canFrame, sizeof(canFrame));
}

Details for the example code above are described in the following subsections.

CAN Driver Configuration

In order to use the CAN APIs, the application is required to provide device-specific CAN configuration in the ti_drivers_config.c file. The CAN driver interface defines a configuration data structure:

typedef struct {
    CAN_FxnTable  const    *fxnTablePtr;
    void                   *object;
    void          const    *hwAttrs;
    CAN_Frame              *rxBufPtr;
    CAN_frame              *txBufPtr;
    size_t                  rxBufSize;
    size_t                  txBufSize;
} CAN_Config;

You will need to check the device-specific CAN driver implementation's header file for example configuration. Please also refer to the ti_drivers_config.c file to see the CAN configuration.

Initializing the CAN Driver

CAN_init() must be called before any other CAN APIs. This function calls the device implementation's CAN initialization function, for each element of CAN_config[].

Opening the CAN Driver

Opening a CAN requires four steps:

Create and initialize a CAN_Params structure.
Fill in the desired parameters.
Call CAN_open(), passing the index of the CAN in the CAN_config structure, and the address of the CAN_Params structure. The CAN instance is specified by the index in the CAN_config structure.
Check that the CAN handle returned by CAN_open() is non-NULL, and save it. The handle will be used to read and write to the CAN you just opened.

Only one CAN index can be used at a time; calling CAN_open() a second time with the same index previously passed to CAN_open() will result in an error. You can, though, re-use the index if the instance is closed via CAN_close(). In the example code, CONFIG_CAN0 is passed to CAN_open(). This macro is defined in the applications "ti_drivers_config.h" file.

Modes of Operation

The CAN driver can operate in blocking mode or nonblocking mode, by setting the mode parameters passed to CAN_open(). If these parameters are not set, as in the example code, the CAN driver defaults to blocking mode. Options for the mode parameter are CAN_MODE_BLOCKING and CAN_MODE_NONBLOCKING:

CAN_MODE_BLOCKING uses a semaphore to block while data is being sent or read. The context of calling CAN_read() or CAN_write() must be a Task when using CAN_MODE_BLOCKING. The CAN_write() or CAN_read() call will block until all data is sent or received, or the write timeout or read timeout expires, whichever happens first.
CAN_MODE_NONBLOCKING is non-blocking and CAN_read() and CAN_write() will return either with the number of bytes successfully read/written, or a negative error number.

Reading and Writing data

The example code reads one CAN frame from the CAN instance, and then writes one CAN frame back to the same instance:

CAN_read(can, &canFrame, sizeof(canFrame));

CAN_write(can, &canFrame, sizeof(canFrame));

The CAN driver allows CAN_read() and CAN_write() calls to happen for any node at any time from the CAN bus. Please see the CAN protocol for how it handles collisions. The ability to filter incoming messages are also available through CAN_Params.

Implementation

The CAN driver interface module is joined (at link time) to an array of CAN_Config data structures named CAN_config. CAN_config is implemented in the application with each entry being an instance of a CAN peripheral. Each entry in CAN_config contains a:

(CAN_FxnTable *) to a set of functions that implement a CAN peripheral
(void *) data object that is associated with the CAN_FxnTable
(void *) hardware attributes that are associated with the CAN_FxnTable

The CAN APIs are redirected to the device specific implementations using the CAN_FxnTable pointer of the CAN_config entry. In order to use device specific functions of the CAN driver directly, link in the correct driver library for your device and include the device specific CAN driver header file (which in turn includes CAN.h). For example, for the MSP432 family of devices, you would include the following header file:

#include <ti/drivers/can/CANMSP432.h>

#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/can/types.h>

Include dependency graph for CAN.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	CAN_Params
	CAN Parameters. More...

struct	CAN_FxnTable
	The definition of a CAN function table that contains the required set of functions to control a specific CAN driver implementation. More...

struct	CAN_Config_
	CAN Global configuration. More...

Macros
#define	CAN_CMD_RESERVED (32)

#define	CAN_STATUS_RESERVED (-32)

#define	CAN_STATUS_SUCCESS (0)
	Successful status code returned by CAN_control(). More...

#define	CAN_STATUS_ERROR (-1)
	Generic error status code returned by CAN_control(). More...

#define	CAN_STATUS_UNDEFINEDCMD (-2)
	An error status code returned by CAN_control() for undefined command codes. More...

#define	CAN_WAIT_FOREVER (~(0U))
	Wait forever define. More...

Typedefs
typedef struct CAN_Config_ *	CAN_Handle
	A handle that is returned from a CAN_open() call. More...

typedef struct can_frame	CAN_Frame
	CAN frame structure. More...

typedef void(*	CAN_CloseFxn) (CAN_Handle handle)
	A function pointer to a driver specific implementation of CAN_CloseFxn(). More...

typedef int_fast16_t(*	CAN_ControlFxn) (CAN_Handle handle, uint_fast16_t cmd, void *arg)
	A function pointer to a driver specific implementation of CAN_ControlFxn(). More...

typedef void(*	CAN_InitFxn) (CAN_Handle handle)
	A function pointer to a driver specific implementation of CAN_InitFxn(). More...

typedef CAN_Handle(*	CAN_OpenFxn) (CAN_Handle handle, CAN_Params *params)
	A function pointer to a driver specific implementation of CAN_OpenFxn(). More...

typedef int_fast32_t(*	CAN_ReadFxn) (CAN_Handle handle, void *buffer, size_t size)
	A function pointer to a driver specific implementation of CAN_ReadFxn(). More...

typedef int_fast32_t(*	CAN_WriteFxn) (CAN_Handle handle, const void *buffer, size_t size)
	A function pointer to a driver specific implementation of CAN_WriteFxn(). More...

typedef void(*	CAN_TxMsgFxn) (CAN_Handle handle)
	A function pointer to a driver specific implementation of CAN_TxMsgFxn(). More...

typedef struct CAN_Config_	CAN_Config
	CAN Global configuration. More...

Enumerations
enum	CAN_Mode { CAN_MODE_BLOCKING, CAN_MODE_NONBLOCKING }
	CAN mode settings. More...

enum	CAN_Direction { CAN_DIRECTION_READ = 0x1, CAN_DIRECTION_WRITE = 0x2, CAN_DIRECTION_READWRITE = 0x3 }
	CAN communication mode. More...

Functions
void	CAN_close (CAN_Handle handle)
	Function to close a CAN peripheral specified by the CAN handle. More...

void	CAN_init (void)
	Function to initialize the CAN module. More...

int_fast16_t	CAN_control (CAN_Handle handle, uint_fast16_t cmd, void *arg)
	Function performs implementation specific features on a given CAN_Handle. More...

CAN_Handle	CAN_open (uint_least8_t index, CAN_Params *params)
	Function to initialize a given CAN peripheral. More...

void	CAN_Params_init (CAN_Params *params)
	Function to initialize the CAN_Params struct to its defaults. More...

int_fast32_t	CAN_write (CAN_Handle handle, const void *buffer, size_t size)
	Function that writes data to a CAN with interrupts enabled. More...

int_fast32_t	CAN_read (CAN_Handle handle, void *buffer, size_t size)
	Function that reads data from a CAN with interrupt enabled. More...

Macro Definition Documentation

§ CAN_WAIT_FOREVER

#define CAN_WAIT_FOREVER (~(0U))

Wait forever define.

Typedef Documentation

§ CAN_Handle

typedef struct CAN_Config_* CAN_Handle

A handle that is returned from a CAN_open() call.

§ CAN_Frame

typedef struct can_frame CAN_Frame

CAN frame structure.

The structure that makes up a CAN message. The unions are provided in order for there to be structural naming compatibility with SocketCAN while at the same time providing an alternative easier to use naming convention. We diverge a bit with TI structural naming convention of the struct in order to provide an option to be compatible with SocketCAN conventions.

See also: CAN_write(); CAN_read()

§ CAN_CloseFxn

typedef void(* CAN_CloseFxn) (CAN_Handle handle)

A function pointer to a driver specific implementation of CAN_CloseFxn().

§ CAN_ControlFxn

typedef int_fast16_t(* CAN_ControlFxn) (CAN_Handle handle, uint_fast16_t cmd, void *arg)

A function pointer to a driver specific implementation of CAN_ControlFxn().

§ CAN_InitFxn

typedef void(* CAN_InitFxn) (CAN_Handle handle)

A function pointer to a driver specific implementation of CAN_InitFxn().

§ CAN_OpenFxn

typedef CAN_Handle(* CAN_OpenFxn) (CAN_Handle handle, CAN_Params *params)

A function pointer to a driver specific implementation of CAN_OpenFxn().

§ CAN_ReadFxn

typedef int_fast32_t(* CAN_ReadFxn) (CAN_Handle handle, void *buffer, size_t size)

A function pointer to a driver specific implementation of CAN_ReadFxn().

§ CAN_WriteFxn

typedef int_fast32_t(* CAN_WriteFxn) (CAN_Handle handle, const void *buffer, size_t size)

A function pointer to a driver specific implementation of CAN_WriteFxn().

§ CAN_TxMsgFxn

typedef void(* CAN_TxMsgFxn) (CAN_Handle handle)

A function pointer to a driver specific implementation of CAN_TxMsgFxn().

§ CAN_Config

typedef struct CAN_Config_ CAN_Config

CAN Global configuration.

The CAN_Config structure contains a set of pointers used to characterize the CAN driver implementation.

This structure needs to be defined before calling CAN_init() and it must not be changed thereafter.

See also: CAN_init()

Enumeration Type Documentation

§ CAN_Mode

enum CAN_Mode

CAN mode settings.

This enum defines the read, write, and blocking modes for the configured CAN.

Enumerator
CAN_MODE_BLOCKING	Blocking and will return only when at least one CAN frame has been processed by CAN_write() or CAN_read() data, or if the optional timeout occurs.
CAN_MODE_NONBLOCKING	Non-blocking and will return immediately with or without write or read data. Error flags could be thrown if invalid CAN_write() or CAN_read().

§ CAN_Direction

enum CAN_Direction

CAN communication mode.

This enum defines read or write communication direction for the configured CAN.

Enumerator
CAN_DIRECTION_READ	Read only mode, a transmit object is not used
CAN_DIRECTION_WRITE	Write only mode, a receive object is not used
CAN_DIRECTION_READWRITE	Read and write mode. A single transmit object is used and at least one receive object is used. NOTE: enum value must be logical OR of CAN_DIRECTION_READ and CAN_DIRECTION_WRITE

Function Documentation

§ CAN_close()

void CAN_close ( CAN_Handle handle )

Function to close a CAN peripheral specified by the CAN handle.

Precondition: CAN_open() has been called.; No active CAN_read() or CAN_write() call.

Parameters

handle A CAN_Handle returned from CAN_open()

See also: CAN_open()

§ CAN_init()

void CAN_init ( void )

Function to initialize the CAN module.

Precondition: The CAN_config structure must exist and be persistent before this function can be called. This function must also be called before any other CAN driver APIs.

§ CAN_control()

int_fast16_t CAN_control	(	CAN_Handle	handle,
		uint_fast16_t	cmd,
		void *	arg
	)

Function performs implementation specific features on a given CAN_Handle.

Commands for CAN_control() can originate from CAN.h or from implementation specific CAN*.h (CANTCAN2550.h, CANMSP432.h, etc.. ) files. While commands from CAN.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific CAN*.h files add unique driver capabilities but are not API portable across all CAN driver implementations.

Commands supported by CAN.h follow a CAN_CMD_<cmd> naming convention.
Commands supported by CAN*.h follow a CAN*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.

Precondition: CAN_open() has to be called.

Parameters

handle	A CAN handle returned from CAN_open()
cmd	CAN.h or CAN*.h commands.
arg	An optional R/W (read/write) command argument accompanied with cmd

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

See also: CAN_open()

§ CAN_open()

CAN_Handle CAN_open	(	uint_least8_t	index,
		CAN_Params *	params
	)

Function to initialize a given CAN peripheral.

Function to initialize a given CAN peripheral specified by the particular index value.

Precondition: CAN_init() has been called

Parameters

index	Logical peripheral number for the CAN indexed into the CAN_config table
params	Pointer to a parameter block. If NULL, default parameter values will be used. All the fields in this structure are RO (read-only).

Returns: A CAN_Handle upon success. NULL if an error occurs, or if the indexed CAN peripheral is already opened.

See also: CAN_init(); CAN_close()

§ CAN_Params_init()

void CAN_Params_init ( CAN_Params * params )

Function to initialize the CAN_Params struct to its defaults.

Parameters

params An pointer to CAN_Params structure for initialization

Defaults values are: mode = CAN_MODE_BLOCKING; direction = CAN_DIRECTION_READWRITE; readTimeout = CAN_WAIT_FOREVER; writeTimeout = CAN_WAIT_FOREVER; baudRate = 125000;

§ CAN_write()

int_fast32_t CAN_write	(	CAN_Handle	handle,
		const void *	buffer,
		size_t	size
	)

Function that writes data to a CAN with interrupts enabled.

CAN_write() writes data from a memory buffer to the CAN interface. The source is specified by buffer and the number of bytes to write is given by size.

In CAN_MODE_BLOCKING, CAN_write() blocks task execution until at least one CAN frame data in buffer has been written.

In CAN_MODE_NONBLOCKING, CAN_write() returns immediately with the number of bytes (in frame size chunks) that were able to be immediately written.

Parameters

handle	A CAN_Handle returned by CAN_open()
buffer	A read-only pointer to buffer containing CAN frames to be written to the CAN interface (CAN_Frame, struct can_frame)
size	The number of bytes in the buffer that should be written to the CAN interface, sizeof(CAN_frame)

Returns: Returns the number of bytes that have been written to the CAN interface. If an error occurs, a negative error number is returned. If in non-blocking mode, and if there is no more room for write data, then -EAGAIN is return. If in blocking mode and a timeout occurs, then -ETIMEDOUT is returned.

§ CAN_read()

int_fast32_t CAN_read	(	CAN_Handle	handle,
		void *	buffer,
		size_t	size
	)

Function that reads data from a CAN with interrupt enabled.

CAN_read() reads data into a memory buffer from the CAN interface. The destination is specified by buffer and the number of bytes to read is given by size.

In CAN_MODE_BLOCKING, CAN_read() blocks task execution until at least one CAN frame data can be received.

In CAN_MODE_NONBLOCKING, CAN_write() returns immediately with the number of bytes (in frame size chunks) that were able to be immediately received.

Parameters

handle	A CAN_Handle returned by CAN_open()
buffer	A pointer to buffer containing space for CAN frames to be read into from the CAN interface (CAN_Frame, struct can_frame)
size	The number of bytes in the buffer that can be filled with receive data from the CAN interface, sizeof(CAN_frame)

Returns: Returns the number of bytes that have been read from the CAN interface. If an error occurs, a negative error number is returned. If in non-blocking mode, and if there is no data to be read then -EAGAIN is returned. If in blocking mode and a timeout occurs, then -ETIMEDOUT is returned.

Detailed Description

Overview

Usage

Synopsis

CAN Driver Configuration

Initializing the CAN Driver

Opening the CAN Driver

Modes of Operation

Reading and Writing data

Implementation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ CAN_WAIT_FOREVER

Typedef Documentation

§ CAN_Handle

§ CAN_Frame

§ CAN_CloseFxn

§ CAN_ControlFxn

§ CAN_InitFxn

§ CAN_OpenFxn

§ CAN_ReadFxn

§ CAN_WriteFxn

§ CAN_TxMsgFxn

§ CAN_Config

Enumeration Type Documentation

§ CAN_Mode

§ CAN_Direction

Function Documentation

§ CAN_close()

§ CAN_init()

§ CAN_control()

§ CAN_open()

§ CAN_Params_init()

§ CAN_write()

§ CAN_read()