CAN Interface (CanIf)

CanIf is the hardware-independent layer between CAN drivers or transceivers and the upper communication modules. It maps transmit requests to Can_Write(), buffers when hardware is occupied, and forwards confirmations and filtered receptions to configured callbacks [SWS_CANIF_00318]. It controls controller and transceiver modes on behalf of CanSm and reports back BusOff and mode changes. PDU channel modes switch the transmit and receive paths separately. Transmission only takes place if the controller is in CAN_CS_STARTED and the transmit path is enabled [SWS_CANIF_00317].

more ›

The CAN Interface (CanIf) handles all hardware-independent tasks of CAN communication. These include transmit requests, confirmations, receive indications, error notifications, as well as starting and stopping CAN controllers SWS CanIf p. 13. CanIf accesses hardware buffers only via CanDrv services [SWS_CANIF_00023]. It addresses controllers and transceivers of multiple drivers via abstract IDs [SWS_CANIF_00653]. The configuration defines which callbacks are invoked in PduR, CanNm, CanTp, CanSm, or EcuM [SWS_CANIF_00011] [SWS_CANIF_00724].

Context diagram: CanIf between upper communication modules, mode management, and the drivers for controllers and transceivers. Sources: [SWS_CANIF_00012], [SWS_CANIF_00358], SWS CanIf p. 21

EcuM initializes CanIf with CanIf_Init(). After that, each channel is set to CANIF_OFFLINE [SWS_CANIF_00864], and until then, services reject with E_NOT_OK [SWS_CANIF_00661]. The controller start via CanIf_SetControllerMode() runs asynchronously. Completion is reported by CanIf_ControllerModeIndication(), which CanIf forwards to CanSm [SWS_CANIF_00003] [SWS_CANIF_00711]. Only after that does CanIf_SetPduMode() accept requests [SWS_CANIF_00874]. The PDU channel modes switch transmit and receive paths separately. Controller events such as SLEEP, STOPPED, or BusOff forcibly set them [SWS_CANIF_00865] [SWS_CANIF_00866].

State diagram: The four PDU channel modes and their transitions triggered by CanIf_SetPduMode() and controller events. Sources: [SWS_CANIF_00137], [SWS_CANIF_00866], SWS CanIf Fig. 7.8 p. 61

During transmission, CanIf_Transmit() calls Can_Write() [SWS_CANIF_00318]. If the hardware is occupied, CanIf buffers the L-PDU provided a buffer is configured [SWS_CANIF_00381]. Upon the next confirmation, it transmits the entry with the highest priority [SWS_CANIF_00668]. Received L-PDUs undergo software filtering and length checks before CanIf forwards them to <User_RxIndication> [SWS_CANIF_00389] [SWS_CANIF_00056].

In case of an error, a BusOff sets the channel to CANIF_TX_OFFLINE and is reported to CanSm [SWS_CANIF_00724]. When stopping a controller, CanIf confirms all pending transmit requests with E_NOT_OK [SWS_CANIF_00739]. Parameter and runtime errors are passed to DET [SWS_CANIF_91006] [SWS_CANIF_91007].

more ›

Role: hardware-independent hub between CAN drivers and communication stack

The CAN Interface (CanIf) handles all hardware-independent tasks of CAN communication for an ECU. The underlying CAN drivers only handle their specific hardware. CanIf processes transmit requests, transmit confirmations, receive indications, and error notifications, and starts or stops CAN controllers SWS CanIf p. 13. It accesses hardware buffers exclusively via services of CanDrv [SWS_CANIF_00023]. Control services operate with an abstract ControllerId that numbers the controllers of all CanDrv instances consecutively starting from 0 [SWS_CANIF_00653]. The same applies to transceivers with TransceiverId [SWS_CANIF_00655].

Downwards, CanIf combines the APIs of multiple CanTrcv drivers into a uniform interface, but does not contain any transceiver logic itself SWS CanIf p. 21. Even with multiple CanDrvs, each callback exists only once. CanIf identifies the calling driver by ControllerId in Can_HwType SWS CanIf p. 68.

Upwards, CanIf calls configurable callbacks such as <User_TxConfirmation> and <User_RxIndication> [SWS_CANIF_00011] [SWS_CANIF_00012]. The configuration specifies the concrete receiver, such as PduR_CanIfRxIndication [SWS_CANIF_00442] or CanTp_TxConfirmation [SWS_CANIF_00550]. CanIf reports BusOff and mode changes to CanSm or a CDD [SWS_CANIF_00724] [SWS_CANIF_00711]. Wake-up validations go to EcuM [SWS_CANIF_00563].

Context diagram: CanIf mediates between the upper communication modules, mode management (CanSm, EcuM), and the drivers for CAN controllers and transceivers. Error, security, and mirroring messages go to DET, IdsM, and Mirror. Sources: [SWS_CANIF_00011], [SWS_CANIF_00724], [SWS_CANIF_00358], [SWS_CANIF_00905], [SWS_CANIF_00913], SWS CanIf p. 13

The scope of functions depends heavily on the configuration. CanIf_Init() reads, among other things, the number of controllers and the assignment of HTHs/HRHs from configuration containers SWS CanIf p. 22. HTH and HRH are handles to logical transmit and receive objects [SWS_CANIF_00291] [SWS_CANIF_00292]. Many services can be deselected via pre-compile switches, e.g. CanIf_ReadRxPduData() [SWS_CANIF_00330] or CanIf_SetBaudrate() [SWS_CANIF_00871]. If no name is configured for a non-mandatory callback, the call is omitted SWS CanIf p. 133. In contrast, <User_ControllerBusOff> must always be configured [SWS_CANIF_00524].

From initialization to started controller

EcuM calls CanIf_Init() [SWS_CANIF_00001]. In doing so, CanIf initializes variables, flags, and buffers [SWS_CANIF_00085] as well as all transmit L-PDU buffers [SWS_CANIF_00387]. Each channel starts in CANIF_OFFLINE [SWS_CANIF_00864]. The controllers then remain in STOPPED mode, in which neither transmission nor reception takes place. EcuM initializes CanDrv and CanTrcv separately SWS CanIf p. 40. Prior to initialization, all services except CanIf_Init() and CanIf_GetVersionInfo() return E_NOT_OK [SWS_CANIF_00661]. Whoever calls CanIf_DeInit() [SWS_CANIF_91002] must ensure that no transmissions are in progress anymore SWS CanIf p. 81.

Controller start runs asynchronously. CanIf_SetControllerMode() [SWS_CANIF_00003] calls Can_SetControllerMode() [SWS_CANIF_00308]. The driver reports the completed change later with CanIf_ControllerModeIndication() [SWS_CANIF_00699], and CanIf forwards the notification to CanSm [SWS_CANIF_00711]. In polling mode, Can_MainFunction_Mode() detects the change SWS CanIf p. 152. Only in CAN_CS_STARTED does CanIf_SetPduMode() accept requests [SWS_CANIF_00874].

Sequence diagram: The start request is acknowledged immediately, but the mode change is indicated only later. Afterward, the PDU paths can be enabled. Sources: [SWS_CANIF_00308], [SWS_CANIF_00711], [SWS_CANIF_00874], SWS CanIf p. 156

PDU channel modes: switching transmit and receive paths separately

Each channel of a controller has a mode of type CanIf_PduModeType [SWS_CANIF_00137]. Upper layers set it with CanIf_SetPduMode() and read it with CanIf_GetPduMode() [SWS_CANIF_00008] [SWS_CANIF_00009]. The modes in detail SWS CanIf p. 58:

• CANIF_OFFLINE: Transmit requests are rejected with E_NOT_OK and buffers are emptied. Indications and confirmations are suppressed [SWS_CANIF_00073].
• CANIF_TX_OFFLINE: Only the transmit path is blocked; reception remains active [SWS_CANIF_00489].
• CANIF_TX_OFFLINE_ACTIVE: Transmit requests are immediately confirmed without being passed to CanDrv [SWS_CANIF_00072].
• CANIF_ONLINE: Transmit and receive are fully active [SWS_CANIF_00075].

Controller events forcibly set the channel mode. CAN_CS_SLEEP leads to CANIF_OFFLINE [SWS_CANIF_00865]. CAN_CS_STOPPED and BusOff lead to CANIF_TX_OFFLINE [SWS_CANIF_00866].

State diagram: The four PDU channel modes with transitions triggered by CanIf_SetPduMode() and by controller events. As in the specification, the three restricted modes are grouped into a superstate. Sources: [SWS_CANIF_00864], [SWS_CANIF_00865], [SWS_CANIF_00866], [SWS_CANIF_00874], SWS CanIf Fig. 7.8 p. 61

Transmit path: CanIf_Transmit, buffering, and Trigger Transmit

CanIf_Transmit() [SWS_CANIF_00005] determines the HTH and calls Can_Write(). The passed swPduHandle is returned later in CanIf_TxConfirmation() [SWS_CANIF_00318]. Before that, CanIf sets the two most significant bits of the CanId [SWS_CANIF_00243]. If Can_Write() returns E_OK, this also applies to the transmit request [SWS_CANIF_00162].

A request is accepted only under these conditions:

• The controller is started and the transmit path is online or offline active [SWS_CANIF_00317].
• When PnTxFilter is active, only CanIfTxPduPnFilterPdus pass [SWS_CANIF_00750].
• Overlength data is truncated with CanIfTxPduTruncation [SWS_CANIF_00894], otherwise rejected [SWS_CANIF_00900].

More recent document sections additionally name CanXL_Write() SWS CanIf p. 87. For R20-11, only Can_Write() is normative.

Activity diagram: How CanIf_Transmit() decides between rejection, simulated confirmation, direct transmission, and buffering. Interpretation: The order of checks is chosen for readability. Sources: [SWS_CANIF_00317], [SWS_CANIF_00382], [SWS_CANIF_00072], [SWS_CANIF_00381], [SWS_CANIF_00837], SWS CanIf Fig. 7.5 p. 51

If Can_Write() reports CAN_BUSY and CanIfPublicTxBuffering is active [SWS_CANIF_00063], CanIf attempts to buffer the L-PDU [SWS_CANIF_00381]. This requires a buffer size greater than zero [SWS_CANIF_00835]. If the same L-PDU is already in the buffer, it is overwritten [SWS_CANIF_00068]. If the buffer is full, a new L-PDU is rejected with E_NOT_OK [SWS_CANIF_00837]. An L-PDU is always located in only one place: in the hardware object or in the CanIf buffer SWS CanIf p. 43.

Upon CanIf_TxConfirmation() [SWS_CANIF_00007], CanIf notifies the responsible user via <User_TxConfirmation> with E_OK [SWS_CANIF_00383]. In the same call, it checks the buffers of the HTH that has become free [SWS_CANIF_00386]. It passes the waiting entry with the highest priority to Can_Write() [SWS_CANIF_00668] [SWS_CANIF_00070]. Upon E_OK, it removes the entry immediately from the buffer [SWS_CANIF_00183]. Newer document locations refer to the callback as LSduR_CanIfTxConfirmation() SWS CanIf p. 157. In R20-11, <User_TxConfirmation> applies.

Sequence diagram: When hardware is occupied, the L-PDU is buffered. The confirmation of an earlier request then triggers retransmission from the buffer. Sources: [SWS_CANIF_00381], [SWS_CANIF_00386], [SWS_CANIF_00668], [SWS_CANIF_00183], SWS CanIf p. 138, SWS CanIf p. 143

In triggered transmission, the user does not pass data, but a NULL SduDataPtr [SWS_CANIF_00882]. If the hardware is free, the driver fetches the data via CanIf_TriggerTransmit() [SWS_CANIF_00883]. CanIf forwards the call to <User_TriggerTransmit> and returns its result [SWS_CANIF_00885]. If the hardware is occupied, CanIf buffers only the transmit request [SWS_CANIF_00881]. The CanId of dynamic L-PDUs can be changed with CanIf_SetDynamicTxId() [SWS_CANIF_00189]. Alternatively, it originates from the MetaData [SWS_CANIF_00855] SWS CanIf p. 34.

Sequence diagram: In trigger transmit, the driver only fetches the data from the user when the hardware object is free. Sources: [SWS_CANIF_00882], [SWS_CANIF_00885], [SWS_CANIF_00881], SWS CanIf Fig. 9.6 p. 137

Reception path: filtering, checking length, forwarding

After reception, the driver calls CanIf_RxIndication() with Mailbox and data [SWS_CANIF_00006]. Processing takes place in three stages:

• Software filter: For BasicCAN HRHs, CanIf filters via software [SWS_CANIF_00663] SWS CanIf p. 39. A rejection terminates processing [SWS_CANIF_00389].
• Length check: It follows if configured [SWS_CANIF_00390], and accepts at least the configured length [SWS_CANIF_00026].
• Forwarding: Accepted L-PDUs go to the configured <User_RxIndication> [SWS_CANIF_00056] [SWS_CANIF_00135]. For dynamic L-SDUs, the CanId ends up in CAN_ID_32 [SWS_CANIF_00848].

Activity diagram: Software filter and length check decide whether a received L-PDU is indicated. Configuration-dependent side effects are shown in parallel. Sources: [SWS_CANIF_00421], [SWS_CANIF_00389], [SWS_CANIF_00168], [SWS_CANIF_00199], [SWS_CANIF_00392], SWS CanIf Fig. 7.6 p. 51

In addition, CanIf provides query services. CanIf_ReadRxPduData() reads data from a dedicated receive buffer [SWS_CANIF_00194] [SWS_CANIF_00198], but is not intended for range reception [SWS_CANIF_00329]. CanIf_ReadTxNotifStatus() and CanIf_ReadRxNotifStatus() reset the status upon reading [SWS_CANIF_00393] [SWS_CANIF_00394]. This "read-and-consume" ensures that at least one event has occurred since the last call SWS CanIf p. 55. CanIf_GetTxConfirmationState() summarizes the confirmations of an entire controller [SWS_CANIF_00734].

Transceiver, wake-up, and partial networking

CanIf forwards the transceiver services directly to the CanTrcv driver. CanIf_SetTrcvMode() calls CanTrcv_SetOpMode() [SWS_CANIF_00358], CanIf_GetTrcvMode() calls CanTrcv_GetOpMode() [SWS_CANIF_00363]. CanIf forwards transceiver mode changes to CanSm [SWS_CANIF_00712].

For wake-up, CanIf_CheckWakeup() queries the controllers and transceivers for the wake-up source [SWS_CANIF_00395] SWS CanIf p. 56. For validation, CanIf stores the first valid reception of a started controller [SWS_CANIF_00286]. CanIf_CheckValidation() then reports it via <User_ValidateWakeupEvent> [SWS_CANIF_00179].

If partial networking is active, a PnTxFilter per controller places an additional layer over the channel modes [SWS_CANIF_00747]. It is activated upon CAN_CS_SLEEP [SWS_CANIF_00749] and deactivated again with the first confirmation or indication [SWS_CANIF_00751] [SWS_CANIF_00896] SWS CanIf p. 70.

Behavior in the event of an error

BusOff: The driver reports the error with CanIf_ControllerBusOff() [SWS_CANIF_00218]. CanIf then sets the channel to CANIF_TX_OFFLINE [SWS_CANIF_00866] and reports the BusOff to CanSm [SWS_CANIF_00724] SWS CanIf Fig. 9.11 p. 147. Recovery is controlled by CanSm via CanIf_SetControllerMode() SWS CanIf p. 160.

Sequence diagram: Process from BusOff detection via notification to CanSm to controller restart. Sources: [SWS_CANIF_00218], [SWS_CANIF_00866], [SWS_CANIF_00724], [SWS_CANIF_00918], SWS CanIf p. 154, SWS CanIf p. 160

Controller stopped: Upon entering CAN_CS_STOPPED, CanIf clears the transmit buffers [SWS_CANIF_00485]. It confirms all pending transmit requests with E_NOT_OK [SWS_CANIF_00739]. In this way, every accepted PDU receives a confirmation, positive or negative SWS CanIf p. 54.

Error notifications: CanIf reports invalid parameters as development errors, e.g. CANIF_E_PARAM_CONTROLLERID [SWS_CANIF_00311] [SWS_CANIF_91006]. Runtime errors include CANIF_E_INVALID_DATA_LENGTH [SWS_CANIF_00168] and CANIF_E_STOPPED [SWS_CANIF_00382] [SWS_CANIF_91007]. A lost transmit request is only apparent from the return value or the missing confirmation Error Description p. 22. CanIf reports security events such as CANIF_SEV_ERRORSTATE_PASSIVE to the IdsM [SWS_CANIF_00913] [SWS_CANIF_00917].

Further detailed evidence

• Initialization and lifecycle: [SWS_CANIF_00001], [SWS_CANIF_00661], SWS CanIf p. 40
• Transmit path and buffering: [SWS_CANIF_00318], [SWS_CANIF_00836], SWS CanIf p. 46
• Reception chain: [SWS_CANIF_00415], SWS CanIf p. 50
• Configurable callbacks: [SWS_CANIF_00532], SWS CanIf p. 133