CAN C API

CAN Controller

A CAN controller is created and configured with the following functions:

SilKit_ReturnCode SilKit_CanController_Create(SilKit_CanController **outCanController, SilKit_Participant *participant, const char *name, const char *network)

Create a CAN controller at this SIL Kit simulation participant.

The lifetime of the resulting CAN controller is directly bound to the lifetime of the simulation participant. There is no further cleanup necessary except for destroying the simulation participant at the end of the simulation. The object returned must not be deallocated using free()!

Parameters

  • outCanController – Pointer that refers to the resulting CAN controller (out parameter).

  • participant – The simulation participant at which the CAN controller should be created.

  • name – The name of the new CAN controller (UTF-8).

  • network – The network of the CAN controller to operate in (UTF-8).

SilKit_ReturnCode SilKit_CanController_SetBaudRate(SilKit_CanController *controller, uint32_t rate, uint32_t fdRate, uint32_t xlRate)

Configure the baud rate of the controller.

In a detailed simulation, the baud rate is used to calculate transmission delays of CAN messages and to determine proper configuration and interoperation of the connected controllers.

Parameters

  • controller – The CAN controller for which the baud rate should be changed.

  • rate – Baud rate for regular (non FD) CAN messages given in bps; valid range: 0 to 2’000’000

  • fdRate – Baud rate for CAN FD messages given in bps; valid range: 0 to 16’000’000

  • xlRate – Baud rate for CAN XL messages given in bps; valid range: 0 to 16’000’000

Its status can be controlled with the functions:

SilKit_ReturnCode SilKit_CanController_Start(SilKit_CanController *controller)

Start the CAN controller.

SilKit_CanController_Reset(), SilKit_CanController_Stop(), SilKit_CanController_Sleep()

SilKit_ReturnCode SilKit_CanController_Stop(SilKit_CanController *controller)

Stop the CAN controller.

SilKit_CanController_Reset(), SilKit_CanController_Start(), SilKit_CanController_Sleep()

SilKit_ReturnCode SilKit_CanController_Reset(SilKit_CanController *controller)

Reset the CAN controller.

Resets the controller’s Transmit Error Count (TEC) and the Receive Error Count (REC). Furthermore, sets the CAN controller state to CanControllerState::Uninit and the controller’s error state to CanErrorState::NotAvailable.

SilKit_CanController_Start(), SilKit_CanController_Stop(), SilKit_CanController_Sleep()

SilKit_ReturnCode SilKit_CanController_Sleep(SilKit_CanController *controller)

Put the CAN controller in sleep mode.

SilKit_CanController_Reset(), SilKit_CanController_Start(), SilKit_CanController_Stop()

The controller can send frames with:

SilKit_ReturnCode SilKit_CanController_SendFrame(SilKit_CanController *controller, SilKit_CanFrame *frame, void *userContext)

Request the transmission of a CanFrame.

The CanFrame must provide a valid CAN ID and valid flags. The controller must be in the Started state to transmit and receive messages.

Parameters

  • controller – The CAN controller that should send the CAN frame.

  • frame – The CAN frame to transmit.

  • userContext – A user provided context pointer, that is reobtained in the SilKit_CanController_AddFrameTransmitHandler handler.

The following set of functions can be used to add and remove event handlers on the controller:

SilKit_ReturnCode SilKit_CanController_AddFrameTransmitHandler(SilKit_CanController *controller, void *context, SilKit_CanFrameTransmitHandler_t handler, SilKit_CanTransmitStatus statusMask, SilKit_HandlerId *outHandlerId)

Register a callback for the TX status of sent CAN messages.

The registered handler is called when a CAN message was successfully transmitted on the bus or when an error occurred.

NB: Full support in a detailed simulation. In simple simulation, all messages are automatically positively acknowledged.

Parameters

  • controller – The CAN controller for which the callback should be registered.

  • context – The user provided context pointer, that is reobtained in the callback.

  • handler – The handler to be called on transmit acknowledge.

  • statusMask – A mask to select for which transmit statuses the handler should be called.

  • outHandlerId – The handler identifier that can be used to remove the callback.

SilKit_ReturnCode SilKit_CanController_AddFrameHandler(SilKit_CanController *controller, void *context, SilKit_CanFrameHandler_t handler, SilKit_Direction directionMask, SilKit_HandlerId *outHandlerId)

Register a callback for CAN message reception.

The registered handler is called when the controller receives a new CAN frame.

Parameters

  • controller – The CAN controller for which the message callback should be registered.

  • context – The user provided context pointer, that is reobtained in the callback.

  • handler – The handler to be called on reception.

  • directionMask – A bit mask defining the transmit direction of the messages (rx/tx)

  • outHandlerId – The handler identifier that can be used to remove the callback.

SilKit_ReturnCode SilKit_CanController_AddStateChangeHandler(SilKit_CanController *controller, void *context, SilKit_CanStateChangeHandler_t handler, SilKit_HandlerId *outHandlerId)

Register a callback for controller state changes.

The registered handler is called when the CanControllerState of the controller changes. E.g., after starting the controller, the state changes from SilKit_CanControllerState_Uninit to SilKit_CanControllerState_Started.

Parameters

  • controller – The CAN controller for which the state change callback should be registered.

  • context – The user provided context pointer, that is reobtained in the callback.

  • handler – The handler to be called on state change.

  • outHandlerId – The handler identifier that can be used to remove the callback.

SilKit_ReturnCode SilKit_CanController_AddErrorStateChangeHandler(SilKit_CanController *controller, void *context, SilKit_CanErrorStateChangeHandler_t handler, SilKit_HandlerId *outHandlerId)

Register a callback for changes of the controller’s error state.

The registered handler is called when the CanErrorState of the controller changes. During normal operation, the controller should be in state SilKit_CanErrorState_ErrorActive. The states correspond to the error state handling protocol of the CAN specification.

Parameters

  • controller – The CAN controller for which the error state callback should be registered.

  • context – The user provided context pointer, that is reobtained in the callback.

  • handler – The handler to be called on error state change.

  • outHandlerId – The handler identifier that can be used to remove the callback.

SilKit_ReturnCode SilKit_CanController_RemoveFrameTransmitHandler(SilKit_CanController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_CanFrameTransmitHandler_t by SilKit_HandlerId on this controller.

Parameters

  • controller – The CAN controller for which the callback should be removed.

  • handlerId – Identifier of the callback to be removed. Obtained upon adding to respective handler.

SilKit_ReturnCode SilKit_CanController_RemoveFrameHandler(SilKit_CanController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_CanFrameHandler_t by SilKit_HandlerId on this controller.

Parameters

  • controller – The CAN controller for which the callback should be removed.

  • handlerId – Identifier of the callback to be removed. Obtained upon adding to respective handler.

SilKit_ReturnCode SilKit_CanController_RemoveStateChangeHandler(SilKit_CanController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_CanStateChangeHandler_t by SilKit_HandlerId on this controller.

Parameters

  • controller – The CAN controller for which the callback should be removed.

  • handlerId – Identifier of the callback to be removed. Obtained upon adding to respective handler.

SilKit_ReturnCode SilKit_CanController_RemoveErrorStateChangeHandler(SilKit_CanController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_CanErrorStateChangeHandler_t by SilKit_HandlerId on this controller.

Parameters

  • controller – The CAN controller for which the callback should be removed.

  • handlerId – Identifier of the callback to be removed. Obtained upon adding to respective handler.

Data Structures

struct SilKit_CanFrame

A CAN frame.

Public Members

SilKit_StructHeader structHeader

The interface id specifying which version of this struct was obtained.

uint32_t id

CAN Identifier.

SilKit_CanFrameFlag flags

CAN Arbitration and Control Field Flags; see SilKit_CanFrameFlag.

uint16_t dlc

Data Length Code - determined by a network simulator if available.

uint8_t sdt

SDU type - describes the structure of the frames Data Field content (for XL Format only)

uint8_t vcid

Virtual CAN network ID (for XL Format only)

uint32_t af

Acceptance field (for XL Format only)

SilKit_ByteVector data

Data field containing the payload.

struct SilKit_CanFrameEvent

Public Members

SilKit_StructHeader structHeader

The interface id specifying which version of this struct was obtained.

SilKit_NanosecondsTime timestamp

Reception time.

SilKit_CanFrame *frame

The CAN Frame that corresponds to the meta data.

SilKit_Direction direction

The transmit direction of the CAN frame (TX/RX)

void *userContext

Optional pointer provided by user when sending the frame.

struct SilKit_CanFrameTransmitEvent

The acknowledgment of a CAN message, sent to the controller.

Public Members

SilKit_StructHeader structHeader

The interface id specifying which version of this struct was obtained.

void *userContext

Value that was provided by user in corresponding parameter on send of CAN frame.

SilKit_NanosecondsTime timestamp

Reception time.

SilKit_CanTransmitStatus status

Status of the CanTransmitRequest.

uint32_t canId

Identifies the CAN id to which this CanFrameTransmitEvent refers to.

You must check that the structure version is sufficient before accessing this field. Added in SIL Kit version 4.0.11.

Version

Check: SK_ID_GET_VERSION(SilKit_Struct_GetId(event)) >= 2

struct SilKit_CanStateChangeEvent

An incoming state change of a CAN controller.

Public Members

SilKit_StructHeader structHeader

The interface id specifying which version of this struct was obtained.

SilKit_NanosecondsTime timestamp

Reception time.

SilKit_CanControllerState state

CAN controller state.

struct SilKit_CanErrorStateChangeEvent

An incoming state change of a CAN controller.

Public Members

SilKit_StructHeader structHeader

The interface id specifying which version of this struct was obtained.

SilKit_NanosecondsTime timestamp

Reception time.

SilKit_CanErrorState errorState

CAN controller error state.

Enumerations and Typedefs

typedef uint32_t SilKit_CanFrameFlag

The available flags within the flags member of a CAN frame.

SilKit_CanFrameFlag_ide

Identifier Extension.

SilKit_CanFrameFlag_rtr

Remote Transmission Request.

SilKit_CanFrameFlag_fdf

FD Format Indicator.

SilKit_CanFrameFlag_brs

Bit Rate Switch (for FD Format only)

SilKit_CanFrameFlag_esi

Error State indicator (for FD Format only)

SilKit_CanFrameFlag_xlf

XL Format Indicator.

SilKit_CanFrameFlag_sec

Simple Extended Content (for XL Format only)