API Reference

Normative

The CAN driver API contract. A conformant driver MUST provide these types and functions with the behavior described. Signatures and member documentation are extracted from the driver headers with Doxygen/Breathe, so code and specification stay in sync. Expand a group below. Keywords per Requirement Keywords; behavioral rules in Can — Requirements; error codes in Errors.

Data types at a glance

Type	Kind	Purpose
Can_ConfigType	struct	Root configuration structure passed to Can_Init.
Can_PduInfoType	struct	L-PDU descriptor (id, length, data pointer) for transmit and receive.
Can_FrameIdType	typedef	Frame identifier; the two MSBs select frame and ID type.
Can_MailboxIdType	typedef	Hardware mailbox / message-object handle.
Can_MessageInfoType	struct	Metadata for a received frame (channel, frame/ID type).
Can_ChannelStateType	enum	Channel states (UNINIT / STOPPED / STARTED / SLEEP).
Can_ErrorType	enum	Error codes reported via CanIf_OnError (e.g. bus-off).

API at a glance

Function	Group	Purpose
Can_Init	Initialization and shutdown	Initialize the driver and every channel.
Can_DeInit	Initialization and shutdown	De-initialize the driver and hardware.
Can_Transmit	Transmission	Queue a frame for transmission on a started channel.
Can_GetChannelState	Channel state and baudrate	Read a channel’s current state.
Can_SetChannelState	Channel state and baudrate	Request a channel state transition.
Can_SetBaudrate	Channel state and baudrate	Select a preconfigured baudrate set (optional feature).
Can_PollFunction	Scheduling and interrupt	Poll TX-completion and RX events (high frequency).
Can_CyclicFunction	Scheduling and interrupt	Poll bus-off/errors and state-transition completion (≥ 1 ms).
Can_Interrupt	Scheduling and interrupt	Driver interrupt service routine.

Expected interfaces at a glance

Upper-layer / integration interfaces the integrator MUST provide (CHI-CAN-MUST-25); see the Expected interfaces group below for signatures.

Function	Kind	Purpose
CanIf_OnTransmission	CAN-specific	Confirms a successfully transmitted CAN TxPDU.
CanIf_OnReception	CAN-specific	Indicates a successfully received CAN Rx L-PDU.
CanIf_OnChannelState	CAN-specific	Indicates a channel state transition.
CanIf_OnError	CAN-specific	Indicates an error event (e.g. bus-off).
LogM_Report	Common	Reports channel HW errors (e.g. ECC error, lost frame) with a log level.
<Mip>_EnterCriticalSection / <Mip>_ExitCriticalSection	Common (optional)	Bracket sections requiring exclusive access, if used — see critical sections.

Data types

Can_ConfigType

struct Can_ConfigType

This data structure type contains the global initialization data for the CAN driver, including SFR (Special Function Register) settings that apply to all channels. Additionally, it holds pointers to the channel-specific configuration structures. The contents of this initialization structure are specific to the CAN hardware.

Available via: Can.h

Can_PduInfoType

struct Can_PduInfoType

This type unites PDU ID (pduId), Length (length), SduData (sduPtr), and Frame ID (frameId) for any CAN L-SDU.

Public Members

PduIdType pduId

uint8 length

Can_FrameIdType frameId

uint8 *sduPtr

Available via: CanIf_DriverTypes.h

Can_FrameIdType

typedef uint32 Can_FrameIdType

This represents the Identifier of an L-PDU. The two most significant bits define the frame type: 00 CAN frame with Standard CAN ID, 01 CAN FD frame with Standard CAN ID, 10 CAN frame with Extended CAN ID, 11 CAN FD frame with Extended CAN ID.

Range:

• 0..0x400007FF - Standard32Bit

• 0..0xDFFFFFFF - Extended32Bit

The two most significant bits select frame and ID type; see CHI-CAN-MUST-12 in Can — Requirements. Available via: CanIf_DriverTypes.h

Can_MailboxIdType

typedef uint16 Can_MailboxIdType

Represents the mailbox IDs of a CAN controller.

Range:

• 0..0xFFFF - Mailbox ID

Available via: CanIf_DriverTypes.h

Can_MessageInfoType

struct Can_MessageInfoType

This type defines a data structure which provides an MailboxID including its corresponding CAN channel and therefore CanDrv as well as the specific FrameID.

Public Members

Can_FrameIdType frameId

Can_MailboxIdType mailboxId

uint8 channelId

Available via: CanIf_DriverTypes.h

Can_ChannelStateType

enum Can_ChannelStateType

States that are used by the several ChannelState functions.

Values:

enumerator CAN_CH_STATE_UNINIT = 0x00

CAN channel state UNINIT

enumerator CAN_CH_STATE_STARTED = 0x01

CAN channel state STARTED

enumerator CAN_CH_STATE_STOPPED = 0x02

CAN channel state STOPPED

enumerator CAN_CH_STATE_SLEEP = 0x03

CAN channel state SLEEP

Available via: CanIf_DriverTypes.h

Can_ErrorType

enum Can_ErrorType

CanDrv error type to be reported to interface layer.

Values:

enumerator CAN_ERR_BUS_OFF = 0x01

Specifies the bus-off occurs

Available via: CanIf_DriverTypes.h

Note

PduIdType, PduInfoType, and PduLengthType are not part of the CAN driver; they are defined in the general reference.

Initialization and shutdown

Can_Init

void Can_Init(const Can_ConfigType *configPtr)

Initializes the driver and HW.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x00

Development error(s):

• CAN_DEVERR_STATE_TRANSITION CanDrv state is not CAN_DRV_STATE_UNINIT, or a CAN channel is not CAN_CH_STATE_UNINIT.

• CAN_DEVERR_PARAM_POINTER configPtr is not a null pointer.

Parameters:

configPtr – [in] Pointer to the configuration structure. This parameter is intended for future extensions to support runtime-selectable configuration variants, which allow the selection and initialization of specific variants during runtime. As this functionality is not currently supported, a NULL_PTR SHALL be provided.

Returns:

None.

When to call: once, before any other CAN function, with the driver in CAN_DRV_STATE_UNINIT.

Effect: initialises static variables, common CAN hardware settings, and per-channel settings; leaves the driver in CAN_DRV_STATE_INIT and every channel in CAN_CH_STATE_STOPPED; enables interrupts for events configured as interrupt.

Errors: see Errors (state, null-pointer). Available via: Can.h

Can_DeInit

void Can_DeInit(void)

De-initializes the driver and HW.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x10

Development error(s):

• CAN_DEVERR_STATE_TRANSITION CanDrv state is not CAN_DRV_STATE_INIT, or a CAN channel is in CAN_CH_STATE_STARTED.

Parameters:

None –

Returns:

None.

When to call: with the driver in CAN_DRV_STATE_INIT and no channel in CAN_CH_STATE_STARTED.

Effect: de-initialises the driver state and CAN hardware; leaves every channel in CAN_CH_STATE_UNINIT. Errors: see Errors. Available via: Can.h

Transmission

Can_Transmit

Std_ReturnType Can_Transmit(Can_MailboxIdType mailboxId, const Can_PduInfoType *pduInfoPtr)

This function is called by upper layer to pass a CAN message to CanDrv for transmission. This interface sets up mailboxId and return without completion of the transmission (non-blocking). Since this interface is non reentrant, the upper layer shall ensure that this interface is not interrupted by itself.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x06

Development error(s):

• CAN_DEVERR_UNINIT CanDrv is not initialized

• CAN_DEVERR_PARAM_MAILBOXID Given mailbox ID is invalid

• CAN_DEVERR_PARAM_POINTER pduInfoPtr is null pointer

• CAN_DEVERR_PARAM_POINTER pduInfoPtr->sduDataPtr is null pointer

• CAN_DEVERR_PARAM_DATA_LENGTH length is more than 64 byte

• CAN_DEVERR_PARAM_DATA_LENGTH length is more than 8 byte and CAN channel is not CAN FD mode

• CAN_DEVERR_PARAM_DATA_LENGTH length is more than 8 byte and CAN channel is CAN FD mode, but CAN FD flag is not set in Can_PduInfoType->frameId

Parameters:

• mailboxId – [in] This specifies which HW-transmit handle is used for transmission. Implicitly indicates the channel to be used, as the mailboxId numbers are unique inside one controller.

• pduInfoPtr – [in] Pointer to SDU user memory, Data Length and Identifier.

Return values:

• E_OK – Transmit command has been accepted

• E_NOT_OK – Development error occurred

• CAN_BUSY – No TX hardware buffer available

When to call: on a channel in CAN_CH_STATE_STARTED.

Returns

Value	Meaning
E_OK	Frame accepted; the hardware TX object was free and transmission was initiated.
CAN_BUSY	TX mailbox is busy with another request; nothing was changed. The caller may retry.
E_NOT_OK	A development error was detected (see Errors).

Side effects: stores pduInfoPtr->pduId for the later CanIf_OnTransmission callback (CHI-CAN-MUST-10). The caller MUST keep pduInfoPtr and its data valid until transmission completes. Available via: Can.h

Channel state and baudrate

Can_GetChannelState

n_ChannelStateType Can_GetChannelState(uint8 channelId)

This service reports about the current state of the requested CAN channel.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x12

Development error(s):

• CAN_DEVERR_UNINIT CanDrv is not initialized

• CAN_DEVERR_PARAM_CHANNELID Given channelId parameter is out of range

Parameters:

channelId – [in] ID of the CAN channel for which the state shall be requested.

Returns:

The state of the requested channel

Effect: returns the current state of the requested channel. Errors: see Errors. Available via: Can.h

Can_SetChannelState

Std_ReturnType Can_SetChannelState(uint8 channelId, Can_ChannelStateType channelState)

This function performs software triggered state transitions of the CAN channel State machine.

Sync/Async:

Asynchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x03

Development error(s):

• CAN_DEVERR_UNINIT CanDrv is not initialized

• CAN_DEVERR_PARAM_CHANNELID Given channelId parameter is out of range

• CAN_DEVERR_STATE_TRANSITION Invalid transition is requested via Transition

Parameters:

• channel – [in] ID of the CAN channel for which the state shall be changed

• channelState – [in] The desired new channel state

Return values:

• E_OK – request accepted

• E_NOT_OK – request not accepted, a development error occurred

Effect: performs a software-triggered channel state transition (see Concepts), enabling or disabling the interrupts needed in the new state. Does not block on transitions that require polling — completion is reported via CanIf_OnChannelState (CHI-CAN-MUST-03). Errors: see Errors. Available via: Can.h

Can_SetBaudrate

Std_ReturnType Can_SetBaudrate(uint8 channelId, uint16 baudRateConfigId)

This service shall set the baudrate configuration of the CAN channel.

Sync/Async:

Synchronous

Reentrancy:

Conditionally reentrant (reentrant when called with different channel)

Service ID [hex]:

0x0f

Development error(s):

• CAN_DEVERR_UNINIT CanDrv is not initialized

• CAN_DEVERR_PARAM_CHANNELID Given channelId parameter is out of range

• CAN_DEVERR_PARAM_BAUDRATEID Given baudRateConfigId is out of configured range

• CAN_DEVERR_INVALID_STATE Called when the channel state is NOT CAN_CH_STATE_STOPPED

Parameters:

• channelId – [in] ID of the CAN channel for which the baudrate shall be changed

• baudRateConfigId – [in] References a baudrate configuration by ID

Return values:

• E_OK – request accepted

• E_NOT_OK – request not accepted, a development error occurred

When to call: on a channel in CAN_CH_STATE_STOPPED, when the optional enable_set_baud_rate_api feature is enabled (CHI-CAN-SHOULD-01).

Effect: selects the preconfigured baudrate set identified by baudRateConfigId. Errors: see Errors. Available via: Can.h

Scheduling and interrupt

Can_PollFunction

void Can_PollFunction(void)

This function is called with high frequency. If TX or RX polling is configured, then it is responsible for polling the TX completion and RX events.

Reentrancy:

Non reentrant

Service ID [hex]:

0x01

Parameters:

None –

Returns:

None.

When to call: cyclically at high frequency (sub-millisecond). Handles TX-completion and RX events for channels configured for polling. May be empty if none are. Available via: Can.h

Can_CyclicFunction

void Can_CyclicFunction(void)

This function is cyclically called on a milliseconds base. This function can be used as time base if it’s required.

Reentrancy:

Non reentrant

Service ID [hex]:

0x08

Parameters:

None –

Returns:

None.

When to call: cyclically (≥ 1 ms). Polls bus-off, other unrecoverable errors, and channel state-transition completion. May be empty if none are configured for polling. Available via: Can.h

Can_Interrupt

void Can_Interrupt<vectorNr>[<VendorSpecificSuffix>](void)

Effect: the driver interrupt service routine; handles bus-off/error, RX frames, and TX-completion events. Define it with the ISR() macro (see the general reference). Available via: Can.h

Expected interfaces

The driver calls back into these upper-layer / integration interfaces, which the integrator MUST provide (CHI-CAN-MUST-25); see the summary table above. LogM_Report and the critical-section services are documented in the general reference.

CanIf_OnTransmission

void CanIf_OnTransmission(PduIdType canTxPduId)

This service confirms a previously successfully processed transmission of a CAN TxPDU.

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Parameters:

canTxPduId – [in] L-PDU handle of CAN L-PDU successfully transmitted. This ID specifies the corresponding CAN LPDU ID and implicitly the corresponding CAN channel.

Returns:

None.

Available via: CanIf.h

CanIf_OnReception

void CanIf_OnReception(const Can_MessageInfoType *messageInfo, const PduInfoType *pduInfoPtr)

This service indicates a successful reception of a received CAN Rx L-PDU to the CanIf after passing all filters and validation checks.

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Parameters:

• messageInfo – [in] Identifies the mailbox and its corresponding CAN channel.

• pduInfoPtr – [in] Pointer to the received L-PDU. CanDrv shall always set metaDataPtr in pduInfoPtr as null pointer, it’s not used in current CanDrv spec.

Returns:

None.

Available via: CanIf.h

CanIf_OnChannelState

void CanIf_OnChannelState(uint8 channel, Can_ChannelStateType channelState)

This service indicates a channel state transition referring to the corresponding CAN channel.

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Parameters:

• channel – [in] ID of the corresponding CAN channel.

• channelState – [in] State to which the CAN channel transitioned.

Returns:

None.

Available via: CanIf.h

CanIf_OnError

void CanIf_OnError(uint8 channelId, Can_ErrorType error)

This service indicates an error event referring to the corresponding CAN channel.

Sync/Async:

Synchronous

Reentrancy:

Reentrant

Parameters:

• channelId – [in] ID of the CAN channel on which the error occurred.

• error – [in] Identifies the error that was detected by the driver/hardware.

Returns:

None.

Available via: CanIf.h