API Documentation

CAN

The CAN API will help users interface with devices using Controller Area Network protocols commonly found in automotive and industrial applications.

Usage #include <polysync_can.h>

Enumerations

ps_can_interface_kind

The reserved SocketCAN interface hardware identifiers.

Name Description
PSYNC_CAN0_INTERFACE_HARDWARE_ID SocketCAN interface ‘can0’ hardware identifier.
PSYNC_CAN1_INTERFACE_HARDWARE_ID SocketCAN interface ‘can1’ hardware identifier.
PSYNC_CAN2_INTERFACE_HARDWARE_ID SocketCAN interface ‘can2’ hardware identifier.
PSYNC_CAN3_INTERFACE_HARDWARE_ID SocketCAN interface ‘can3’ hardware identifier.
PSYNC_CAN4_INTERFACE_HARDWARE_ID SocketCAN interface ‘can4’ hardware identifier.
PSYNC_CAN5_INTERFACE_HARDWARE_ID SocketCAN interface ‘can5’ hardware identifier.
PSYNC_CAN6_INTERFACE_HARDWARE_ID SocketCAN interface ‘can6’ hardware identifier.
PSYNC_CAN7_INTERFACE_HARDWARE_ID SocketCAN interface ‘can7’ hardware identifier.
PSYNC_CAN8_INTERFACE_HARDWARE_ID SocketCAN interface ‘can8’ hardware identifier.
PSYNC_CAN9_INTERFACE_HARDWARE_ID SocketCAN interface ‘can9’ hardware identifier.
PSYNC_VCAN0_INTERFACE_HARDWARE_ID SocketCAN interface ‘vcan0’ hardware identifier.
PSYNC_VCAN1_INTERFACE_HARDWARE_ID SocketCAN interface ‘vcan1’ hardware identifier.
PSYNC_VCAN2_INTERFACE_HARDWARE_ID SocketCAN interface ‘vcan2’ hardware identifier.
PSYNC_VCAN3_INTERFACE_HARDWARE_ID SocketCAN interface ‘vcan3’ hardware identifier.
PSYNC_VCAN4_INTERFACE_HARDWARE_ID SocketCAN interface ‘vcan4’ hardware identifier.
PSYNC_VCAN5_INTERFACE_HARDWARE_ID SocketCAN interface ‘vcan5’ hardware identifier.
PSYNC_VCAN6_INTERFACE_HARDWARE_ID SocketCAN interface ‘vcan6’ hardware identifier.
PSYNC_VCAN7_INTERFACE_HARDWARE_ID SocketCAN interface ‘vcan7’ hardware identifier.
PSYNC_VCAN8_INTERFACE_HARDWARE_ID SocketCAN interface ‘vcan8’ hardware identifier.
PSYNC_VCAN9_INTERFACE_HARDWARE_ID SocketCAN interface ‘vcan9’ hardware identifier.

Functions

psync_can_open ( … )

This will open the CAN channel by the system ID.

If using multiple threads, the channel is usable only in the context of the thread that created it. The channel defaults to off-bus if it is successful.

See psync_can_go_on_bus to put the CAN channel on the bus.

Parameters
In/Out Type Name Description
in ps_can_channel * const channel A pointer to ps_can_channel that receives the initialization.
in const unsigned long system_id The system identifier for the channel.

See ps_can_channel.system_id for details.
in const unsigned long flags The configuration flags for the channel. It can be a combination of the PSYNC_CAN_OPEN_* flags.
Returns

psync_can_close ( … )

This will close the CAN channel. If no other threads are using the channel, the circuit will be taken off bus.

Parameters
In/Out Type Name Description
in ps_can_channel * const channel A pointer to ps_can_channel that holds the configuration.
Returns

psync_can_get_channel_count ( … )

This will get the number of available CAN channels on the host. The count corresponds to the system ID values, starting at zero.

Parameters
In/Out Type Name Description
out unsigned long * const count A pointer to an unsigned long that receives the value.
Returns

psync_can_get_channel_identifiers ( … )

This will get the hardware and circuit identifiers for a channel using its system identifier. See ps_can_channel for more details.

Parameters
In/Out Type Name Description
in const unsigned long system_id System identifier for the channel.

See ps_can_channel.system_id for details.
out unsigned long * const hardware_id The hardware identifier for the channel.

See ps_can_channel.hardware_id for details.
out unsigned long * const circuit_id The circuit identifier for the channel.

See ps_can_channel.circuit_id for details.
Returns
  • DTC Code:

psync_can_set_bit_rate ( … )

This will set the CAN channel bit rate.

Parameters
In/Out Type Name Description
in ps_can_channel * const channel A pointer to ps_can_channel that receives the configuration.
in const ps_datarate_kind bit_rate The bit rate. [bits per second]
Returns

psync_can_go_on_bus ( … )

This will place the CAN channel on bus.

Parameters
In/Out Type Name Description
in ps_can_channel *const channel A pointer to ps_can_channel that receives the configuration.
Returns

psync_can_go_off_bus ( … )

This will place the CAN channel off bus.

Parameters
In/Out Type Name Description
in ps_can_channel * const channel A pointer to ps_can_channel that receives the configuration.
Returns

psync_can_read ( … )

This will read the message/frame from a CAN channel.

Parameters
In/Out Type Name Description
in const ps_can_channel * const channel A pointer to ps_can_channel that holds the configuration.
out ps_can_frame * const frame A pointer to ps_can_frame that receives the CAN frame data.
in const ps_timestamp timeout If no message is immediately available, this specifies the amount of time to wait before returning. [microseconds]

A value of zero means do no block.
Returns

psync_can_write ( … )

This will write the message/frame to a CAN channel.

Parameters
In/Out Type Name Description
in const ps_can_channel * const channel A pointer to ps_can_channel that holds the configuration
in const ps_can_frame * const frame A pointer to ps_can_frame that specifies the CAN frame data to send
Returns

psync_can_drain_send_buffer ( … )

This will drain a CAN channel’s send buffer and wait until all CAN messages for the specified handle are sent, or until the timeout period expires.

Parameters
In/Out Type Name Description
in const ps_can_channel * const channel A pointer to the ps_can_channel that holds the configuration.
in const ps_timestamp timeout The amount of time to wait for the buffer to empty. [microseconds]

A value of zero means wait forever.
Returns

Macros

PSYNC_CAN_HANDLE_INVALID

Value Type Description
-1 int Invalid ps_can_channel.handle value.

PSYNC_CAN_OPEN_EXCLUSIVE

Value Type Description
0x0008 int Don’t allow the channel to be shared.

PSYNC_CAN_OPEN_EXTENDED

Value Type Description
0x0010 int Require extended CAN (CAN 2.0B) support from the channel.

PSYNC_CAN_OPEN_ALLOW_VIRTUAL

Value Type Description
0x0020 int Allow the use of virtual channels.

PSYNC_CAN_MSG_RTR

Value Type Description
0x0001 int Remote transmission request message flag.

PSYNC_CAN_MSG_STD

Value Type Description
0x0002 int Standard CAN identifier message flag.

PSYNC_CAN_MSG_EXT

Value Type Description
0x0004 int Extended CAN identifier message flag.

PSYNC_CAN_MSG_ERROR_FRAME

Value Type Description
0x0020 int Error frame CAN identifier message flag.

PSYNC_CAN_MSG_ERROR_OVERRUN

Value Type Description
0x0600 int Hardware/software overrun condition CAN frame message flag.

PSYNC_CAN_MAX_CIRCUITS_PER_HARDWARE

Value Type Description
64 int Maximum CAN channel circuits for a given piece of hardware.

PSYNC_CAN_FRAME_MAX_DLC

Value Type Description
8 int Maximum CAN frame data length count value.

Structures

ps_can_channel

This will provide access to a CAN circuit/channel. Some hardware will have multiple circuits/channels associated with its identifier. For example, a 4 channel PCI card and a single channel USB interface would have the following layout:

  • hardware (ID: 123)
    • circuit 0 - (system_id = 0)
    • circuit 1 - (system_id = 1)
    • circuit 2 - (system_id = 2)
    • circuit 3 - (system_id = 3)
  • hardware (ID: 234)
    • circuit 0 - (system_id = 4)
Type Name Description
int handle Driver/hardware handle.

Value PSYNC_CAN_HANDLE_INVALID means invalid channel.
unsigned long hardware_id Hardware identifier.

This is usually the serial number of the adapter hardware, not the channels (e.g. for a 2 channel PCI adapter, it would provide channel IDs 0 and 1, both with the same hardware ID).
unsigned long circuit_id Circuit identifier.

This is usually the index of the channel/circuit on a given piece of hardware (e.g. for a 2 channel PCI adapter, it would provide circuit IDs 0 and 1).
unsigned long system_id System identifier.

This is usually the system index of the channel as seen by the host driver or software stack. The system ID is not typically a reliable way of persisting channel configurations across reboots. Instead, it is recommended to use the hardware ID and circuit ID to determine the system ID before use.
ps_datarate_kind bit_rate Bit rate. [bits per second]
unsigned int on_bus If not zero, the channel is on-bus, otherwise channel is off-bus.
void * interface Internal driver interface.

ps_can_frame

Type Name Description
unsigned long id CAN Frame identifier.

Check ps_can_frame.flags for standard/extended/rtr/etc.
unsigned char buffer[8] CAN frame data payload.
unsigned long dlc Number of bytes in the payload.
unsigned long flags CAN frame flags.

Value PSYNC_CAN_MSG_STD means standard frame.
ps_timestamp hw_timestamp Hardware-provided timestamp, relative to device power-up. [microseconds]
ps_timestamp timestamp PolySync timestamp. [microseconds]