RTA Knowledge Base

Scope

This document aims to describe the function of the CanIf BSW module. This document pertains to RTA-CAR's implementation of CanIf in AUTOSAR version 23-11. Specifically see 'Specification of CAN Interface' in AUTOSAR CP R23-11: AUTOSAR_CP_SWS_CANInterface.pdf. While this document makes refrence to the AUTOSAR standard, it does not replace the standard and readers are encouraged to read the standard themselves in addition to this application note.

What is CanIf

The CAN Interface module consists of all CAN hardware independent tasks which belongs to the CAN communication device drivers of the corresponding ECU. This functionality is implemented once in the CanIf module so that the underlying CAN
device drivers only focus on access and control of the corresponding specific CAN hardware device. As a result the CanIf can be a hardware abstracted module that the upper layers can use as an interface to the Can driver. As can be seen in the above diagram CanIf can be seen between the Com service layer and the Com driver layer.

Acronyms and Abbreviations

CAN L-Pdu - CAN Protocol Data Unit. Consists of an identifier, Data Length and data (SDU) Visible to the CAN driver.
CAN L-SDU - CAN Service Data Unit. Data that are transported inside the CAN L-Pdu. Visible to the upper layers of the CAN interface (e.g. Pdu Router).
HOH - CAN hardware object handle.
HRH - CAN hardware receive handle.
HTH - CAN hardware transmit handle.
SDT - SDU type.
SDU - service data unit.
CAN Hardware Unit - A CAN Hardware Unit may consist of one or multiple CAN Controllers of the same type and one, two or multiple CAN RAM areas. The CAN Hardware Unit is located on-chip or as external device. The CAN hardware unit is represented by one CAN Driver.
Hardware Object (HW Object) - A CAN hardware object is defined as a Pdu buffer inside the CAN RAM of the CAN Hardware Unit / CAN Controller.

Hardware Object Handles (HOHs)

HOHs for Transmission (HTHs) and Receiveing (HRHs) represent an abstract reference to a Can Mailbox that contain Can related data such as a CanId, DLC and data.
The HOH is used as a parameter in the calls of CanDrv's interface services and is provided by the CanDrv's configuration and used by the CanDrv as an identifier for communication buffers and Can Mailboxes.
CanIf behaves only as the user of a HOH but does not interpret it regarding hardware information therefore remains hardware independant (eg does not directly access hardware specific buffers and will only access buffers through CanDrv services).

Each Can Controller can provide multiple Transmit Hw Objects in a mailbox, these can be logically linked to one pool of Hw Objects (Multplexed Hw Objects) therefore can be addressed by one HTH.

CanIf will use two types of HOHs to access the CanDrv; HTH and HRH.

HRH

The HRH shall be a handle referencing a logical Hardware Receive Object of the CAN Controller mailbox.
The HRH shall enable CanIf to use BasicCAN or a FullCAN reception method of the referenced reception unit and to indicate a Received L-SDU to a target upper layer module
If the HRH references a reception unit configured for BasicCAN reception, software filtering shall be enabled in CanIf.
If multiple HRHs are used, each HRH shall belong at least to a single or fixed group of Rx L-SDU (CanRxPduIds).
A HRH Can be configured to receive:
    • one single CanId (FullCAN)
    • a group of single CanIds (BasicCAN)
    • a range/area of CanIds (BasicCAN)
    • all CanIds.

HTH

The HTH shall be a handle referencing a logical Hardware Transmit Object of the CAN Controller mailbox.
The HTH shall enable CanIf to use BasicCAN or FullCAN transmission method of the referenced transmission unit and to confirm a transmitted L-SDU to a target upper layer module.
Each CanIf Tx L-Pdu shall statically be assigned to one CanIfBufferCfg configuration container at configuration time.
If multiple HTHs are used, each HTH shall belong to a single or fixed group of Tx L-Pdus (CanTxPduIds).
The dedicated HRHs and HTHs are derived from the configuration set of CanDrv. The definition of HTH/HRH and Hardware Objects is up to CanDrv.

Static L-Pdu's

CanIf supports activation and deactivation of all L-Pdus belonging to a Can Controller for transmission as well as reception.
Each L-Pdu is associated with an upper layer module in order to ensure correct dispatching during reception, transmission confirmation and data access.

Can Hardware Unit

The CAN Hardware Unit combines one or multiple CAN Controller modules of the same type, which may be located on-chip or as external standalone devices. Each CAN Hardware Unit is served by a CanDrv.
If different types of CAN Controllers are used then different types of CanDrvs have to be applied with a unified API to CanIf. CanIf collects information about number and types of CAN Controllers and their Hardware Objects at configuration time. This allows transparent and hardware independent access to the CAN Controllers from upper layer modules using HOHs.

BasicCan and FullCan

Can XL hardware has an entirely different approach for accessing the frames using descriptors and queues, similar to Ethernet therefore this does not apply to Can XL.

CanIf distinguishes between BasicCAN and FullCAN handling for activation of software acceptance filtering. A CAN mailbox (Hardware Object) for FullCAN operation only enables transmission or reception of single CanIds. Accordingly, BasicCAN operation of one Hardware Object enables to transmit or receive a range of CanIds.
A Hardware Receive Object when configured for BasicCAN reception is able to receive a range of CanIds which pass its hardware acceptance filter. This range may exceed the list of predefined Rx L-Pdus to be received by this HRH. Therefore CanIf subsequently shall execute software filtering to pass only the predefined list of Rx L-Pdus to the corresponding upper layer modules.

CanIf configures and orders the HTHs and HRHs for all HOHs from the configuration containers CanIfHthCfg and CanIfHrhCfg.
CanIf references a hardware acceptance filter for each HOH derived from the configuration parameters CanIfHthIdSymRef and CanIfHrhIdSymRef.
CanIf allows the possibility to configure and store a software acceptance filter for each HRH of type BasicCAN configured by parameter CanIfHrhSoftwareFilter.
CanIf shall execute the software acceptance filter for the HRH passed back by callback function CanIf_RxIndication()

Initialisation

The EcuM will call the function CanIf_Init to initialise CanIf. All global variables and data structures are initialized including flags and buffers during the initialization process. The EcuM will initialise the CanDrv(s) and CanTrcv(s) seperatley by calling their respective init functions.
If re-initialization of the entire CAN modules during runtime is required, the EcuM shall invoke CanSm to initiate the required state transitions of the CAN Controller by call of CAN Interface module’s API service CanIf_SetControllerMode, CanIf then maps the calls from CanSm to calls of the respective CanDrvs.

Transmit Requests

CanIf's Transmit Request function CanIf_Transmit is a common interface for upper layers to transmit L-Pdus on the Can Network. The Upper layer modules only initiate transmission through the CanIf's services. The Transmit request is completed sucessfully if the CanDrv can sucessfully write the L-Pdu data into the Can Hardware Transmit Object.

Upon a call to CanIf_Transmit CanIf Performs performs the following actions.

  • Checks the init status of CanIf.
  • Identifies the CanDrv.
  • Determines the HTH to access the Can Hardware Transmit Object.
  • Calls Can_Write or CanXL_Write in the CanDrv. 

Upon a successful transmission then CanIf_Transmit will return the code E_OK.

Transmit Buffering

General Behavior

With respect to CanIf, the transmit process begins with a call to CanIf_Transmit and ends with an invocation of the upper layer modules callback notification (..._TxConfirmation). During the transmit process CanIf, CanDrv and the Can Mailboxes will store the L-Pdu to be transmitted but only in a single place. Depending on the transmit method this place may be: The CAN hardware transmit object or The Transmit L-Pdu Buffer inside CanIf, if transmit buffering is enabled.

For triggered transmission CanIf only stores the transmit request for the L-Pdu but not the data as the data is fetched just in time by means of the trigger transmit function when the HTH is free. Keep in mind that L-Pdu's requested for transmission would only ever be stored once.

In the case where transmit buffering is enabled, if the transmit buffer in the can driver is occupied then CanIf will buffer the Pdu for transmission and will return E_OK even though the transmission has not occoured (Can_Write returned CAN_BUSY). CanIf will then take care of transmitting the queued Pdu when the callback CanIf_TxConfirmation is called when the driver has cleared the previously filled buffer, this means that the upper layer does not have to retry the transmit request. If transmit buffering was disabled then CanIf would return E_NOT_OK uppon the call to CanIf_Transmit as the Pdu could not be coppied to the CanDrv's buffer.


Keep in mind that the Pdu refrences the HTH through the containers in CanIfBufferCfg where the buffer size will be set through the parameter CanIfBufferSize, if transmit buffering is disabled then the buffer size can be to be set to zero or not set at all.
Also if the data length of the Pdu excedes the configured size of the buffer then CanIf will buffer the configured amount and disacard the rest, it will then make a call to DET through the function Det_ReportRuntimeError and pass the error code CANIF_E_DATA_LENGTH_MISMATCH.


Buffer Characteristics

Storage of L-Pdus in the transmit buffer

Lastly If a Pdu comes into CanIf and it has already got the same Pdu in the buffer then the contents of the buffer will be overwritten with the newest Pdu. The rational is to keep the latest data available. If the Pdu in the buffer is a different Pdu then the buffer will not be overwritten and CanIf_Transmit will return E_NOT_OK. Also keep in mind transmit buffering is only an option if the HTH is configured for BasicCAN, FullCAN is not supported.

Initialisation of transmit buffers

When CanIf_Init is called, CanIf will perform an initialisation of the buffers.

Transmit Confirmation

The above sequence diagram shows the call path of a TX confirmation when performed via an interrupt.


The above sequence diagram shows the call path of a TX confirmation when performed through polling.


When a transmit request has completed, CanDrv notifies CanIf through the callback CanIf_TxConfirmation. If Bus Mirroring is enabled then CanIf will call Mirror_ReportCanFrame for each frame transmission on the controller that is confirmed providing the stored content and the Can ID.

When the callback CanIf_TxNotficiation is called, CanIf will find the upper layer responsible for the L-Pdu and will notify it about the sucessfull transmit.
If CanIfPublicTxConfirmPollingSupport is enabled, CanIf shall buffer the information about a received TxConfirmation per CAN Controller, if the controller mode of that controller is in state CAN_CS_STARTED.

Receive Data Flow
According to the AUTOSAR Basic Software Architecture the received data will be evaluated and processed in the upper layer communication stacks (i.e. AUTOSAR COM, CanNm, CanTp, DCM). This means, upper layer modules may neither work with (i.e. change) buffers of CanDrv (Rx) nor do they have access to buffers of CanIf (Tx). CanIf provides internal buffering in the receive path only if CanIfPublicReadRxPduDataApi is set to TRUE. Tx buffering is covered previously.

In reception of a new Pdu, the CanDrv will call the function CanIf_RxIndication. The Received L-Pdu is hardware dependent (nibble and byte ordering, access type) and allocated to the lowest layer in the communication system - to CanDrv. HRH serves as a link between CanDrv and the upper layer module using the L-Pdu. The HRH identifies one CAN hardware receive object, where a new L-Pdu was received.

After the indication of a received L-Pdu the CanDrv (CanIf_RxIndication() is called) the CanIf shall proceed as described in the section Receive indication. CanIf does not know whether the CanDrv uses temporary buffering or a direct hardware access so it expects normalized L-Pdu data in calls of CanIf_RxIndication().


Receive Indication

A call of CanIf_RxIndication() references in its parameters a newly received L-Pdu. If the function CanIf_RxIndication() is called CanIf evaluates the L-Pdu for acceptance and prepares the L-SDU for later access by the upper communication layers.
CanIf will then notify the upper layer about this asynchronous event using <User_RxIndication>() if configured and if this L-Pdu is successfully detected and accepted for further processing.
If Bus Mirroring is enabled globally and activated for a Can Controller, CanIf shall call Mirror_ReportCanFrame for each frame received on that controller.

When CanIf_TxConfirmation is called, CanIf performs the software filtering on the received L-Pdu if configured. Once the Pdu has been accepted by the software filtering then CanIf will perform the data length check if configured. CanIf then identifies the upper layer for the Pdu before calling the upper layers indication callback providing the required data.


Read Received Data

The API CanIf_ReadRxPduData provided By CanIf is a common interface for upper layer modules to read Can L-Pdus recently received fron the Can Network.
The Upper layers may only start the receive request for the data through services of CanIf withought accessing the CanDrv directly. The Receive request will be completed when CanIf has written the L-Pdu into the upper layers I-Pdu buffer.

When this API is enabled via the use of the parameter CanIfPublicReadRxPduDataApi then upper layers can request recently received Pdus outside of the context of a call to RxIndiction. This means that a RxIndication function for a specific Pdu does not need to be configured but both options are allowed at the same time. This allows the integrator to decide how to implement Pdu reception by upper layers at configuration time.

If the parameter CanIfPublicReadRxPduDataApi is set to true then CanIf will store to a buffer each L-Pdu for Rx L-Pdus that have the parameter CanIfRxPduReadData set to true. If this is configured then after a call to CanIf_RxIndication which has suceeded then the received Pdus data will be written to this buffer.

Read Tx/Rx notification status

In addition to the notification callbacks, CanIf provides the API service CanIf_ReadTxNotifStatus that reads the transmit confirmation status of an transmited L-SDU. There is also the API CanIf_ReadRxNotifStatus that is provided to read the receive indication status of any receive L-SDU.

These APIs can be enabled/disabled globally through the parameter's CanIfPublicReadRxPduNotifyStatusApi and CanIfPublicReadTxPduNotifyStatusApi for the APIs CanIf_ReadRxNotifyStatus and CanIf_ReadTxNotifyStatus respectivley and enabled/disabled per Pdu with the (per Pdu) parameters CanIfRxPduReadNotifyStatus and CanIfTxPduReadNotifyStatus.

Can Controller Mode

General Functionality

CanIf provides services to control the comminication modes of all Can controllers represented by the CanDrv. The Can Controller status may be changed by requests from upper layers by calling the service CanIf_SetControllerMode. This request to CanIf is passed to the CanController through the CanDrv.

CanIf accepts all request for a state transition via the Apis CanIf_SetControllerMode and CanIf_ControllerBusOff as it does not decide whether any of these requests are valid or not, it simply passes the request to the driver.

Note that an optimisation to avoid frequent calls to the can driver when frequently finding the Controller mode is to use the function CanIf_ControllerModeIndication as this does not pass back to the driver, instead after the mode changes; the driver tells CanIf about the change which is stored per Can Controller, this API reads the value from CanIf.

It is usually the responsiblity of CanSm to perform mode change requests however it is not exclisively CanSm that is allowed to use these Apis.


Can Controller Operation Modes

If a controller is in the state CAN_CS_STOPPED and a Pdu referencing that controller tries to be transmitted through a call of CanIf_Transmit then CanIf will not forward the request to CanDrv therefore no call to Can_Write or CanXL_Write will take place and CanIf_Transmit will return E_NOT_OK.

If a controller enters the state CAN_CS_STOPPED then CanIf will clear the transmit buffer to the controller, then it will notify the upper layer about the failed transmission by calling the upper layers _TxConfirmation Api and passing in E_NOT_OK for every outstandind transmission request. If CanIfPublicTxConfirmPollingSupport is enabled then CanIf will clear the TxConfirmation buffers.

When the CanDrv calls the CanIf callback CanIf_ControllerBusOff to notify CanIf of the state change then CanIf will notify CanSm via the callback k CanSm_ControllerBusOff.
When the callback CanIf_ControllerModeIndication is called then CanIf will call CanSm_ControllerModeIndication of the CanSm to indicate to CanSm about the mode change.

Controller Mode Transitions

Api's for state change requests to the Can Controller behaves in an asynchronous manner with asynchronous notification callback calls therefore the real mode transition may occour asynchronously, when the transition has occoured then CanDrv will CanIf_ControllerModeIndication and in turn CanIf calls the upper layers _ControllerModeIndication callback. Upper layer modules may poll the Can Controller Mode by calling the function CanIf_GetControllerMode.

WakeUp

The ECU supports wakeup over Can only when the Can Controllers and Transceivers are in a sleep mode where communication is disabled. Only this mode will ensure that the Can Controller is stopped therefore the wakeup interrupt may be enabled.

Wakeup Detection

If Wakeup support is enabled then CanIf is notified (Likely by integration code) about the wakeup by the service CanIf_CheckWakeup in order to know if the CanDrv or CanTrcv (Via can_CheckWakeup and CanTrcv_CheckWakeup respectivley) has signaled for a wakeup event. If (at least) one of the calls to the driver of transceiver return E_OK then CanIf_CheckWakeup will return E_OK, else it will return E_NOT_OK. In case of a Can bus wakeup event then the function CanIf_CheckWakeup may also be called from EcuM_CheckWakeup. 

Wakeup Validation

If a Can Controller/Can Transceiver detects a bus wakeup event then it will directly notify the Ecu State Manager, if the wakeup needs to be validated then the EcuM will switch on the corresponding Can Controller/Can Transciever via the functions CanIf_SetControllerMode and CanIf_SetTrcvMode.

Pdu Channel Mode Control

Pdu Channel Groups

Each L-Pdu is assigned to to one dedicated physical Can Channel connected to one Can Controller on one Can Network. This way all L-Pdus belonging to one Physical Channel can be controlled by a single L-Pdu Channel Group as these groups represent all L-Pdus connected to a single underlying channel. Note a single L-Pdu can only be assigned to a single channel group.

Pdu Channel Modes

CanIf provides service CanIf_SetPduMode and CanIf_GetPduMode to prevent the processing of Pdus on a per channel basis. This is only allowed if the channel mode is set to CAN_CS_STARTED.
The acceptable Pdu modes are:

  • CANIF_OFFLINE (0x00) - Transmit and receive path of the corresponding channel are disabled => no communication mode
  • CANIF_TX_OFFLINE (0x01) - Transmit path of the corresponding channel is disabled. The receive path is enabled.
  • CANIF_TX_OFFLINE_ACTIVE (0x02) - Transmit path of the corresponding channel is in offline active mode. The receive path is enabled. This mode requires CanIfTxOfflineActive Support = TRUE.
  • CANIF_ONLINE (0x03) - Transmit and receive path of the corresponding channel are enabled => full operation mode.
  • Whilst CANIF_ONLINE and CANIF_OFFLINE disable Tx and Rx for the channel for the Pdu's in the channel, CANIF_TX_OFFLINE and CANIF_TX_OFFLINE_ACTIVE allow for reception withought transmission of the Pdus.

If CanIf_SetControllerMode is called with the mode CAN_CS_SLEEP as a parameter, then CanIf will set the Pdu mode to CANIF_OFFLINE. When switching to CANIF_OFFLINE mode then CanIf prevents forwarding of transmit requests (via CanIf_Transmit) for the associated Pdus to the CanDrv. It then clears the corresponding CanIf transmit buffers. Prevents invocation of both the RxIndication and TxConfirmation callbacks to upper layers.

If CanIf_SetControllerMode with the param CAN_CS_STOPPED or if CanIf_ControllerBusOff is called then CanIf will set the Pdu modes for the specified channel to CANIF_OFFLINE.

CANIF_OFFLINE

During Initialisation CanIf initialised every channel state to CANIF_OFFLINE. If CanIf_SetControllerMode with the parameter CAN_CS_SLEEP is called then CanIf will set the PDU channel mode of the corresponding channel to CANIF_OFFLINE.

For Physical Channels switching to CANIF_OFFLINE mode then CanIf shall:

  • prevent forwarding of transmit requests CanIf_Transmit() of associated L-PDUs to CanDrv (return E_NOT_OK to the calling upper layer modules)
  • clear the corresponding CanIf transmit buffers
  • prevent invocation of receive indication callback services of the upper layer modules
  • prevent invocation of transmit confirmation callback services of the upper layer modules. 

If CanIf_SetControllerMode with the parameter CAN_CS_STOPPED or CanIf_ControllerBusOff is called then CanIf will set the PDU channel mode of the corresponding channel to CANIF_TX_OFFLINE.

For Physical Channels switching to CANIF_TX_OFFLINE mode CanIf shall:

  • prevent forwarding of transmit requests CanIf_Transmit() of associated L-PDUs to CanDrv (return E_NOT_OK to the calling upper layer modules)
  • clear the corresponding CanIf transmit buffers
  • prevent invocation of transmit confirmation callback services of the upper layer modules.
  • enable invocation of receive indication callback services of the upper layer modules. 

The BusOff notification is implicitly suppressed in case of CANIF_OFFLINE and CANIF_TX_OFFLINE due to the fact that no L-PDUs can be transmitted and thus the CAN Controller is not able to go in BusOff mode by newly requested L-PDUs for transmission. 

If those Transmit L-PDUs, which are already waiting for transmission in the CAN Transmit Hardware Object, will be transmitted immediately after change to CANIF_TX_OFFLINE or CANIF_OFFLINE mode and a subsequent BusOff event occurs, CanIf does not prohibit execution of the BusOff notification.

CANIF_ONLINE

For Physical Channel switching to CANIF_OFFLINE then CanIf will:
Enable forwarding of transmit requests CanIf_Transmit of the channels associated Pdus to CanDrv.
Enable invocation of both RX and TX indication callback services of the upper layer modules. 

CANIF_OFFLINE_ACTIVE

If the parameter CanIfTxOfflineActiveSupport is set to true then CanIf provides simulation of successful transmission when the Pdu channel mode is in the state CANIF_TX_OFFLINE_ACTIVE, this means that CanIf calls the transmit confirmation callback services to the upper layer immediatly, no actuall transmit occours. This is used for specialized use cases such as testing where no actual Tx is wanted but the upper layers must believe in a Tx yet true Rx is still required.

Software Receive Filter

Not all L-Pdus which may pass the hardware RX filter and therefore are successfully received in BasicCAN HW Objects are actually receive L-Pdus to the ECU where CanIf can filter out these unwanted L-Pdus.

Certain software filter algorithms are provided to optimize software filter runtime. The approach of software filter mechanisms is to find out the corresponding L-Pdu from the HRH and CanId currently being processed. After the L-Pdu is found, CanIf accepts 
the reception and enables upper layers to access L-SDU information directly.

Software Filtering Concept

The configuration tool handles the information about the hardware acceptance filter settings, the most important settings are the number of L-Pdu HW objects there are and their allowable range of Pdu/Can id's that will not be filtered out. The options are: A single Pdu for Full Can reception, a list of Pdus could be accepted or one or more ranges can be linked to an RX HW onject for Basic Can reception.

These ranges can be set by either an upper and lower limit (CanIfHrhRangeRxPduUpperCanId and CanIfHrhRangeRxPduLowerCanId respectivley) being set where any Pdu that falls within the bounds is accepted or a base ID can be set (CanIfHrhRangeBaseID) with a mask (CanIfHrhRangeMask) that defines which bits in the base ID are relevent and therefore have to mach to the Pdu's ID. Also keep in mind that software filtering is optional and each configurable range type will accept standard Can IDs and extended Can IDs.

Lastly note: If a range is (partly) contained in another range, or a single CanId is contained in a range, the software filter shall select the L-Pdu based on the following assumptions:

  • A single CanId is preferred over any range.
  • A smaller range is preferred over a larger range.  

Data Length Check

The received data length value is compared to the configured data length value of the received L-Pdu configured via the param CanIfRxPduDataLength. CanIf will accept any Pdu who's size is equal or greater than that of the configured length (assuming the Pdu otherwise passes filtering). The data length check can be set globally (CanIfPrivateDataLengthCheck) and on a per-Pdu basis (CanIfRxPduDataLengthCheck), keep in mind that if the check is disabled globally then it can't be enabled per-Pdu. If CanIf rejects a Pdu during data length checking then CanIf will report a runtime error to DET with the code CANIF_E_INVALID_DATA_LENGTH. If the data length check is passed then CanIf will pass the Pdu length up to the upper layer.

Polling Mode

The polling mode provides handling of transmit, receive and error events that occur in the CAN hardware without the usage of hardware interrupts. Thus CanIf and CanDrv provid notification services for detection and execution corresponding hardware events. This way upper layer modules are abstracted from the strategy to detect hardware events. If different CanDrvs are in use, the calling frequency has to be harmonized during configuration setup and system integration.
The user has to consider that CanIf has to be able to execute notification services triggered by interrupts as well as to execute invoked notification services on the task level. If any access to the CAN controller’s mailbox is blocked then subsequent transmit buffering takes place.

Multiple Can Driver Support

CanIf needs a specific mapping to cover multiple CanDrv to provide a common interface to upper layers. Thus CanIf must dispatch all actions down the stack to the APIs of the corresponding CanDrv and underlying CAN Controller(s). For othe direction up the stack CanIf has to provide adequate callback notifications to differentiate between multiple CanDrvs. The support for multiple CanDrvs can be enabled and disabled by the parameter CanIfPublicMultipleDrvSupport.

Partial Networking

If Partial Networking is enabled (via CanIfPublicPnSupport) then CanIf supports a PnTxFilter per CAN Controller which overlays the PDU channel modes.
This filter only has an effect and transition its modes (enabled/disabled) if more than zero Tx L-PDUs per CAN Controller are configured as CanIfTxPduPnFilterPdu.

If the PnTxFilter of a CAN Controller is enabled then CanIf will block all Tx requests to that CAN Controller (return E_NOT_OK when CanIf_Transmit() is called) as long as the the requested Tx L-PDUs is not one of the configured CanIfTxPduPnFilterPdus of that CAN Controller. These CanIfTxPduPnFilterPdus will always be passed to the corresponding CAN Driver.

If CanIf_RxIndication() is called and PnTxFilter is enabled then the corresponding PnTxFilter shall be disabled, if however the PnTxFilter of a CAN Controller is disabled then CanIf shall behave as requested via CanIf_SetPduMode. If CanIf_SetPduMode is called to set a controller to CANIF_TX_OFFLINE and Partial Networking is enabled (via CanIfPublicPnSupport) then the PnTxFilter of the corresponding CAN Controller shall be enabled.

APIs

  • Functions
    • Function Definitions
      • CanIf_Init 
        • Notes:
          • CanIf_Init should only be called be EcuM.
          • Does not initialise the controllers into an operational state.
          • Initialises the CanIf module's own state.
        • Parameters
          • const CanIf_ConfigType* ConfigPtr - Pointer to a selected configuration structure.
        • Return: Void
        • Reentrant: No
        • Sync/Async: Synchronous
        • Service ID: 0x01
        • Defined: CanIf.h


      • CanIf_Deinit
        • Notes:
          • Deinitialises the CanIf module.
          • It is the callers responsibility to make sure there are no on-going transmissions/receptions, nor any pending transmission confirmations.
        • Parameters: None
        • Return: Void
        • Reentrant: No
        • Sync/Async: Synchronous
        • Service ID: 0x02
        • Defined: CanIf.h


      • CanIf_SetControllerMode
        • Notes:
          • This service calls the corresponding CAN Driver service for changing of the CAN controller mode.
          • It is the callers responsibility to make sure there are no on-going transmissions/receptions, nor any pending transmission confirmations.
          • The service CanIf_SetControllerMode calls Can_SetControllerMode for the requested CAN controller.
          • If ControllerId has an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID to Det,
          • If ControllerMode has an invalid value (not CAN_CS_STARTED, CAN_CS_SLEEP or CAN_CS_STOPPED) then CanIf will report development error code CANIF_E_PARAM_CTRLMODE to DET.
        • Parameters:
          • In:
            • uint8 ControllerId -  ControllerId which is assigned to a CAN controller.
            • Can_ControllerStateType ControllerMode - Requested mode transition.
        • Return: Std_ReturnType
          • E_OK: Controller mode request has been accepted.
            E_NOT_OK: Controller mode request has not been accepted
        • Reentrant: Reentrant (Not for the same controller)
        • Sync/Async: Asynchronous
        • Service ID: 0x03
        • Defined: CanIf.h


      • CanIf_GetControllerMode
        • Notes:
          • This service calls the corresponding CAN Driver service for obtaining the current status of the CAN controller.
          • If ControllerId has an invalid, the CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID to DET.
          • If ControllerModePtr has an invalid value, the CanIf shall report development error code CANIF_E_PARAM_POINTER to DET.
        • Parameters:
          • In:
            • uint8 ControllerId  -  ControllerId which is assigned to a CAN controller.
          • Out:
            • Can_ControllerStateType* ControllerModePtr - Pointer to a memory location, where the current mode of the CAN controller will be stored. 
        • Return: Std_ReturnType
          • E_OK: Controller mode request has been accepted.
          • E_NOT_OK: Controller mode request has not been accepted
        • Reentrant: No.
        • Sync/Async: Synchronous
        • Service ID: 0x04
        • Defined: CanIf.h


      • CanIf_GetControllerErrorState
        • Notes:
          • This service calls the corresponding CAN Driver service for obtaining the error state of the CAN controller
          • If ControllerId has an invalid, the CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID to DET.
          • If parameter ErrorStatePtr of CanIf_GetControllerErrorState() is a null pointer, the CanIf shall report development error code CANIF_E_PARAM_POINTER to DET.
        • Parameters:
          • In:
            • uint8 ControllerId  -  ControllerId which is assigned to a CAN controller.
          • Out:
            • Can_ErrorStateType* ErrorStatePtr - Pointer to a memory location, where the error state of the CAN controller will be stored.
        • Return: Std_ReturnType
          • E_OK: Error state request has been accepted.
          • E_NOT_OK: Error state request has not been accepted.
        • Reentrant: Non Reentrant for the same ControllerId.
        • Sync/Async: Synchronous
        • Service ID: 0x4b
        • Defined: CanIf.h


      • CanIf_Transmit
        • Notes:
          • Requests transmission of a PDU.
          • CanIf_Transmit shall call Can_Write with the hardware transmit handle corresponding to the provided TxPduId and a Can_PduType structure where:
            • swPduHandle is set to the CanTxPduId used in the corresponding CanIf_TxConfirmation() call.
            • length is set to the value provided be PduInfoPtr→SduLength.
            • Id is set to the CAN ID associated with the TxPduId.
            • Sdu is set to the pointer provided as PduInfoPtr->SduDataPtr.
          • IfTxPduId has an invalid value then CanIf will report development error code CANIF_E_INVALID_TXPDUID to DET.
        • Parameters:
          • In:
            • PduIdType TxPduId - Identifier of the PDU to be transmitted.
            • const PduInfoType* PduInfoPtr - Length of and pointer to the PDU data and pointer to MetaData.
        • Return: Std_ReturnType
          • E_OK: Transmit request has been accepted.
          • E_NOT_OK: Transmit request has not been accepted
        • Reentrant: Reentrant for different PduIds. Non reentrant for the same PduId
        • Sync/Async: Synchronous
        • Service ID: 0x49
        • Defined: CanIf.h


      • CanIf_ReadRxPduData
        • Notes:
          • This service provides the Data Length and the received data of the requested CanIfRxSduId to the calling upper layer.
          • If CanIfRxSduId has an invalid value (e.g. not configured to be stored within CanIf via CanIfRxPduReadData) then CanIf will report error code CANIF_E_INVALID_RXPDUID to DET.
          • If CanIfRxInfoPtr has an invalid value then CanIf will report development error code CANIF_E_PARAM_POINTER to DET.
        • Parameters:
          • In:
            • PduIdType CanIfRxSduId - Receive L-SDU handle specifying the corresponding CAN L-SDU ID and implicitly the CAN Driver instance as well as the corresponding CAN controller device.
          • Out:
            • PduInfoType* CanIfRxInfoPtr - Contains the length (SduLength) of the received PDU, a pointer to a buffer (SduDataPtr) containing the PDU, and the MetaData related to this PDU.
        • Return: Std_ReturnType
          • E_OK: Request for L-SDU data has been accepted
          • E_NOT_OK: No valid data has been received
        • Reentrant: Non Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x06
        • Defined: CanIf.h

      • CanIf_ReadTxNotifStatus
        • Notes:
          • This service returns the confirmation status (confirmation occurred or not) of a specific static or dynamic CAN Tx L-PDU, requested by the CanIfTxSduId.
          • This function notifies the upper layer about any transmit confirmation event to the corresponding requested L-SDU.
          • If CanIfPublicReadTxPduNotifyStatusApi and CanIfTxPduReadNotifyStatus for the transmitted L-SDU are set to TRUE, and if CanIf_ReadTxNotifStatus is called then CanIf shall reset the notification status for the transmitted L-SDU.
          • This API can be enabled or disabled at pre-compile time configuration globally by the parameter CanIfPublicReadTxPduNotifyStatusApi.
        • Parameters:
          • In:
            • PduIdType CanIfTxSduId - L-SDU handle to be transmitted. This handle specifies the corresponding CAN L-SDU ID and implicitly the CAN Driver instance as well as the corresponding CAN controller device.
        • Return: CanIf_NotifStatusType - Current confirmation status of the corresponding CAN Tx L-PDU.
        • Non Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x07
        • Defined: CanIf.h
      • CanIf_ReadRxNotifStatus
        • Notes:
          • This service returns the indication status (indication occurred or not) of a specific CAN Rx L-PDU, requested by the CanIfRxSduId.
          • This function notifies the upper layer about any receive indication event to the corresponding requested L-SDU.
          • The function CanIf_ReadRxNotifStatus() must not be used for CanIfRxSduIds, which are defined to receive multiple CAN-Ids (range reception).
          • This API can be enabled or disabled at pre-compile time configuration globally by the parameter CanIfPublicReadRxPduNotifyStatusApi.
        • Parameters:
          • In:
            • PduIdType CanIfRxSduId - Receive L-SDU handle specifying the corresponding CAN L-SDU ID and implicitly the CAN Driver instance as well as the corresponding CAN controller device. 
        • Return: CanIf_NotifStatusType - Current indication status of the corresponding CAN Rx L-PDU.
        • Reentrant: Non Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x08
        • Defined: CanIf.h


      • CanIf_SetPduMode
        • Notes:
          • This service sets the requested mode at the L-PDUs of a predefined logical PDU channel.
          • If called with invalid ControllerId then CanIf will report development error code CANIF_E_PARAM_CONTROLLERID to DET.
          • If called with invalid PduModeRequest then CanIf shall report development error code CANIF_E_PARAM_PDU_MODE to DET.
        • Parameters:
          • In:
            • uint8 ControllerId - All PDUs of the own ECU connected to the corresponding CanIf ControllerId, which is assigned to a physical CAN controller are addressed.
            • CanIf_PduModeType PduModeRequest - Requested PDU mode change.
        • Return: Std_ReturnType
          • E_OK: Request for mode transition has been accepted.
          • E_NOT_OK: Request for mode transition has not been accepted.
        • Reentrant: Non Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x09
        • Defined: CanIf.h


      • CanIf_GetPduMode
        • Notes:
          • This service reports the current mode of a requested PDU channel.
          • If ControllerId is invalid then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID to DET.
          • If PduModePtr is invalid then CanIf shall report development error code CANIF_E_PARAM_POINTER to DET.
        • Parameters:
          • In:
            • uint8 ControllerId - All PDUs of the own ECU connected to the corresponding CanIf ControllerId, which is assigned to a physical CAN controller are addressed.
          • Out:
            • CanIf_PduModeType* PduModePtr - Pointer to a memory location, where the current mode of the logical PDU channel will be stored.
        • Return: Std_ReturnType
          • E_OK: PDU mode request has been accepted.
          • E_NOT_OK: PDU mode request has not been accepted.
        • Reentrant: Reentrant (Not for the same channel) 
        • Sync/Async: Synchronous
        • Service ID: 0x0A
        • Defined: CanIf.h
      • CanIf_SetDynamicTxId
        • Notes:
          • This service reconfigures the corresponding CAN identifier of the requested CAN L-PDU.
          • If CanIfTxSduId has an invalid value, CanIf shall report development error code CANIF_E_INVALID_TXPDUID to DET.
          • If CanId has an invalid value, CanIf shall report development error code CANIF_E_PARAM_CANID to DET.
          • This function is pre compile time configurable On or Off by the parameter CanIfPublicSetDynamicTxIdApi.
        • Parameters:
          • In:
            • PduIdType CanIfTxSduId - L-SDU handle to be transmitted. This handle specifies the corresponding CAN L-SDU ID and implicitly the CAN Driver instance as well as the corresponding CAN controller device 
            • Can_IdType CanId - Standard/Extended CAN ID of CAN L-SDU that shall be transmitted as FD or conventional CAN frame.
        • Return: Void
        • Reentrant: Non Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x0C
        • Defined: CanIf.h
      • CanIf_SetTrcvMode
        • Notes:
          • This service changes the operation mode of the transceiver (TransceiverId), via calling the corresponding CAN Transceiver Driver service.
          • If TransceiverId has an invalid value then CanIf shall report error CANIF_E_PARAM_TRCV to DET.
          • If TransceiverMode has an invalid value (not CANTRCV_TRCVMODE_STANDBY, CANTRCV_TRCVMODE_SLEEP or CANTRCV_TRCVMODE_NORMAL) then CanIf shall report development error code CANIF_E_PARAM_TRCVMODE to DET.
          • The mode of a transceiver can only be changed to CANTRCV_TRCVMODE_STANDBY when the former mode of the transceiver has been CANTRCV_TRCVMODE_NORMAL but this is not checked by CanIf.
          • The mode of a transceiver can only be changed to CANTRCV_TRCVMODE_SLEEP when the former mode of the transceiver has also been CANTRCV_TRCVMODE_STANDBY but this is also not checked by CanIf. 
          • This function is pre compile time configurable On or Off by the parameter CanIfPublicSetDynamicTxIdApi.
        • Parameters:
          • In:
            • uint8 TransceiverId - Abstracted CanIf TransceiverId, which is assigned to a CAN transceiver, which is requested for mode transition.
            • CanTrcv_TrcvModeType TransceiverMode - Requested mode transition.
        • Return: Std_ReturnType
          • E_OK: Transceiver mode request has been accepted.
          • E_NOT_OK: Transceiver mode request has not been accepted
        • Reentrant: Non Reentrant
        • Sync/Async: Asynchronous
        • Service ID: 0x0D
        • Defined: CanIf.h


      • CanIf_GetTrcvMode
        • Notes:
          • This function invokes CanTrcv_GetOpMode and updates the parameter TransceiverModePtr with the value OpMode provided by CanTrcv. 
          • If TransceiverId has an invalid value then CanIf shall report error CANIF_E_PARAM_TRCV to DET.
          • If TransceiverModePtr has an invalid value then CanIf shall report development error code  CANIF_E_PARAM_POINTER to DET.
        • Parameters:
          • In:
            • uint8 TransceiverId - Abstracted CanIf TransceiverId, which is assigned to a CAN transceiver, which is requested for mode transition.
          • Out:
            • CanTrcv_TrcvModeType* TransceiverModePtr - Requested mode of requested network the Transceiver is connected to.
        • Return: Std_ReturnType
          • E_OK: Transceiver mode request has been accepted.
          • E_NOT_OK: Transceiver mode request has not been accepted
        • Reentrant: Non Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x0E
        • Defined: CanIf.h


      • CanIf_GetTrcvWakeupReason
        • Notes:
          • This service returns the reason for the wake up of the transceiver TransceiverId, via calling the corresponding CAN Transceiver Driver service.
          • If TransceiverId has an invalid value then CanIf shall report error CANIF_E_PARAM_TRCV to DET.
          • If TrcvWuReasonPtr has an invalid value then CanIf shall report development error code  CANIF_E_PARAM_POINTER to DET.
        • Parameters:
          • In:
            • uint8 TransceiverId - Abstracted CanIf TransceiverId, which is assigned to a CAN transceiver, which is requested for mode transition.
          • Out:
            • CanTrcv_TrcvWakeupReasonType* TrcvWuReasonPtr - provided pointer to where the requested transceiver wake up reason shall be returned.
        • Return: Std_ReturnType
          • E_OK: Transceiver wake up reason request has been accepted.
          • E_NOT_OK: Transceiver wake up reason request has not been accepted.
        • Reentrant: Non Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x0F
        • Defined: CanIf.h


      • CanIf_SetTrcvWakeupMode
        • Notes:
          • This function shall call CanTrcv_SetTrcvWakeupMode.
          • If TransceiverId has an invalid value then CanIf shall report error CANIF_E_PARAM_TRCV to DET.
          • If TrcvWakeupMode has an invalid value then CanIf shall report development error code CANIF_E_PARAM_TRCVWAKEUPMODE to DET.
        • Parameters:
          • In:
            • uint8 TransceiverId - Abstracted CanIf TransceiverId, which is assigned to a CAN transceiver, which is requested for mode transition.
            • CanTrcv_TrcvWakeupModeType TrcvWakeupMode - Requested transceiver wake up notification mode.
        • Return: Std_ReturnType
          • E_OK: Transceiver wake up reason request has been accepted.
          • E_NOT_OK: Transceiver wake up reason request has not been accepted.
        • Reentrant: Non Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x10
        • Defined: CanIf.h


      • CanIf_CheckWakeup
        • Notes:
          • This service checks, whether an underlying CAN driver or a CAN transceiver driver already signals a wakeup event.
          • This function should be called via integration code.
          • If WakeupSource has an invalid value then CanIf shall report development error code  CANIF_E_PARAM_WAKEUPSOURCE to DET.
        • Parameters:
          • In:
            • EcuM_WakeupSourceType WakeupSource - Source device, which initiated the wake up event: CAN controller or CAN transceiver.
        • Return: Std_ReturnType
          • E_OK: Will be returned, if the check wake up request has been accepted.
          • E_NOT_OK: Will be returned, if the check wake up request has not been accepted.
        • Reentrant: Non Reentrant
        • Sync/Async: Asynchronous
        • Service ID: 0x11
        • Defined: CanIf.h


      • CanIf_CheckValidation
        • Notes:
          • This service is performed to validate a previous wakeup event.
          • This function should be called via integration code.
          • If WakeupSource has an invalid value then CanIf shall report development error code CANIF_E_PARAM_WAKEUPSOURCE to DET.
          • This Api can be configured if no validation is needed to not exsts. this API can be omitted by setting CanIfPublicWakeupCheckValidSupport to false.
        • Parameters:
          • In:
            • EcuM_WakeupSourceType WakeupSource - Source device which initiated the wake-up event and which has to be validated: CAN controller or CAN transceiver.
        • Return: Std_ReturnType
          • E_OK: Will be returned, if the check validation request has been accepted.
          • E_NOT_OK: Will be returned, if the check validation request has not been accepted.
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x12
        • Defined: CanIf.h


      • CanIf_GetTxConfirmationState
        • Notes:
          • This service reports, if any TX confirmation has been done for the whole CAN controller since the last CAN controller start.
          • If ControllerId has an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID.
          • If BusOff Recovery of CanSm doesn’t need the status of the Tx confirmations, this API can be omitted by disabling of CanIfPublicTxConfirmPollingSupport.
        • Parameters:
          • In:
            • uint8 ControllerId - Abstracted CanIf ControllerId which is assigned to a CAN controlle
        • Return: CanIf_NotifStatusType- Combined TX confirmation status for all TX PDUs of the CAN controller.
        • Reentrant: Reentrant (Not for the same controller) 
        • Sync/Async: Synchronous
        • Service ID: 0x19
        • Defined: CanIf.h



      • CanIf_ClearTrcvWufFlag
        • Notes:
          • Requests the CanIf module to clear the WUF flag of the designated CAN transceiver.
          • If TransceiverId has an invalid value then CanIf shall report development error code CANIF_E_PARAM_TRCV to DET.
          • Whetherthe CanIf supports this function shall be pre compile time configurable via CanIfPublicPnSupport and CanIfPublicTrcvPnEnable.
        • Parameters:
          • In:
            • uint8 TransceiverId - Abstract CanIf TransceiverId, which is assigned to the designated CAN transceiver.
        • Return: Std_ReturnType E_OK:
          • Request has been accepted
          • E_NOT_OK: Request has not been accepted
        • Reentrant: Reentrant for different CAN transceivers
        • Sync/Async: Asynchronous
        • Service ID: 0x1e
        • Defined: CanIf.h



      • CanIf_CheckTrcvWakeFlag
        • Notes:
          • Requests the CanIf module to check the Wake flag of the designated CAN transceiver.
          • If TransceiverId has an invalid value then CanIf shall report development error code CANIF_E_PARAM_TRCV to DET.
          • Whetherthe CanIf supports this function shall be pre compile time configurable via CanIfPublicPnSupport and CanIfPublicTrcvPnEnable.
        • Parameters:
          • In:
            • uint8 TransceiverId - Abstract CanIf TransceiverId, which is assigned to the designated CAN transceiver.
        • Return: Std_ReturnType E_OK:
          • Request has been accepted
          • E_NOT_OK: Request has not been accepted
        • Reentrant: Reentrant for different CAN transceivers
        • Sync/Async: Asynchronous
        • Service ID: 0x1f
        • Defined: CanIf.h


      • CanIf_SetBaudrate
        • Notes:
          • This service shall set the baud rate configuration of the CAN controller. Depending on necessary baud rate modifications the controller might have to reset. 
          • If ControllerId has an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID  to DET.
          • If CanIf supports changing baud then CanIf_SetBaudrate shall be configurable via the parameter CanIfSetBaudrateApi.
        • Parameters:
          • In:
            • uint8 ControllerId - Abstract CanIf ControllerId which is assigned to a CAN controller whose baud rate shall be set.
            • uint16 BaudRateConfigID -references a baud rate configuration by ID .
        • Return: Std_ReturnType E_OK:
          • E_OK: Service request accepted, setting of (new) baud rate started.
          • E_NOT_OK: Service request not accepted.
        • Reentrant: Reentrant for different ControllerIds. Non reentrant for the same ControllerId.
        • Sync/Async: Synchronous
        • Service ID: 0x27
        • Defined: CanIf.h


      • CanIf_GetControllerRxErrorCounter
        • Notes:
          • This service calls the corresponding CAN Driver service for obtaining the Rx error counter of the CAN controller.
          • If ControllerId has an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID  to DET.
          • If RxErrorCounterPtr has an invalid value then CanIf shall report development error code CANIF_E_PARAM_POINTER to DET.
        • Parameters:
          • In:
            • uint8 ControllerId - Abstract CanIf ControllerId which is assigned to a CAN controller whose baud rate shall be set.
          • Out:
            • uint8* RxErrorCounterPtr - Pointer to a memory location, where the current Rx error counter of the CAN controller will be stored.
        • Return: Std_ReturnType E_OK:
          • E_OK: Rx error counter available.
          • E_NOT_OK: Wrong ControllerId or Rx error counter not available.
        • Reentrant: Non Reentrant for the same ControllerId.
        • Sync/Async: Synchronous
        • Service ID: 0x4d
        • Defined: CanIf.h


      • CanIf_GetControllerTxErrorCounter
        • Notes:
          • This service calls the corresponding CAN Driver service for obtaining the Rx error counter of the CAN controller.
          • If ControllerId has an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID  to DET.
          • If RxErrorCounterPtr has an invalid value then CanIf shall report development error code CANIF_E_PARAM_POINTER to DET.
        • Parameters:
          • In:
            • uint8 ControllerId - Abstract CanIf ControllerId which is assigned to a CAN controller whose baud rate shall be set.
          • Out:
            • uint8* RxErrorCounterPtr - Pointer to a memory location, where the current Tx error counter of the CAN controller will be stored.
        • Return: Std_ReturnType E_OK:
          • E_OK: Tx error counter available.
          • E_NOT_OK: Wrong ControllerId or Tx error counter not available.
        • Reentrant: Non Reentrant for the same ControllerId.
        • Sync/Async: Synchronous
        • Service ID: 0x4e
        • Defined: CanIf.h


      • CanIf_EnableBusMirroring
        • Notes:
          • Enables or disables mirroring for a CAN controller
          • If ControllerId has an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID  to DET.
        • Parameters:
          • In:
            • uint8 ControllerId - Abstract CanIf ControllerId which is assigned to a CAN controller whose baud rate shall be set.
            • boolean MirroringActive -
              • TRUE: Mirror_ReportCanFrame will be called for each frame received or transmitted on the given controller.
              • FALSE: Mirror_ReportCanFrame will not be called for the given controller.
        • Return: Std_ReturnType E_OK:
          • E_OK: Mirroring mode was changed.
          • E_NOT_OK: Wrong ControllerId or mirroring globally disabled.
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x4c
        • Defined: CanIf.h


      • CanIf_GetCurrentTime
        • Notes:
          • This service calls the corresponding CAN Driver service to retrieve the current time value out of the HW registers.
          • If Controller has an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID to DET.
          • If timeStampPtr has an invalid value then CanIf shall report development error code CANIF_E_PARAM_POINTER to DET.
          • The function shall be pre compile time configurable On/Off by the configuration parameter CanIfGlobalTimeSupport.
        • Parameters:
          • In:
            • uint8 Controller - Index of the addresses CAN controller

          • Out:
            • Can_TimeStampType* timeStampPtr - current time stamp
        • Return: Std_ReturnType E_OK:
          • E_OK: successful
          • E_NOT_OK: failed
        • Reentrant: Non Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x51
        • Defined: CanIf.h


      • CanIf_EnableEgressTimeStamp
        • Notes:
          • This service calls the corresponding CAN Driver service to activate egress time stamping on a dedicated message object.
          • If TxPduId has an invalid value then CanIf shall report development error codeCANIF_E_PARAM_LPDU to DET.
          • The function shall be pre compile time configurable On/Off by the configuration parameter CanIfGlobalTimeSupport.
        • Parameters:
          • In:
            • PduIdType TxPduId - L-PDU handle of CAN L-PDU for which the time stamping shall be enabled.
        • Return: Void.
        • Reentrant: Non Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x52
        • Defined: CanIf.h


      • CanIf_GetEgressTimeStamp
        • Notes:
          • This service calls the corresponding CAN Driver service to activate egress time stamping on a dedicated message object.
          • If TxPduId has an invalid value then CanIf shall report development error code CANIF_E_PARAM_LPDU to DET.
          • If timeStampPtr has an invalid value then CanIf shall report development error code CANIF_E_PARAM_POINTER to DET.
          • The function shall be pre compile time configurable On/Off by the configuration parameter CanIfGlobalTimeSupport.
        • Parameters:
          • In:
            • PduIdType TxPduId - L-PDU handle of CAN L-PDU for which the time stamping shall be returned.
          • Out;
            • Can_TimeStampType* timeStampPtr - current time stamp.
        • Return: Std_ReturnType:
          • E_OK: successful
          • E_NOT_OK: failed 
        • Reentrant: Non Reentrant for the same TxPduId, Reentrant for different TxPduId
        • Sync/Async: Synchronous
        • Service ID: 0x53
        • Defined: CanIf.h


      • CanIf_GetIngressTimeStamp
        • Notes:
          • This service calls the corresponding CAN Driver service to reads back the ingress time stamp on a dedicated message object. It needs to be called within the RxIndication function.
          • If TxPduId has an invalid value then CanIf shall report development error code CANIF_E_PARAM_LPDU to DET.
          • If timeStampPtr has an invalid value then CanIf shall report development error code CANIF_E_PARAM_POINTER to DET.
          • The function shall be pre compile time configurable On/Off by the configuration parameter CanIfGlobalTimeSupport.
        • Parameters:
          • In:
            • PduIdType TxPduId - L-PDU handle of CAN L-PDU for which the time stamping shall be returned.
          • Out;
            • Can_TimeStampType* timeStampPtr - current time stamp.
        • Return: Std_ReturnType:
          • E_OK: successful
          • E_NOT_OK: failed 
        • Reentrant: Non Reentrant for the same RxPduId, Reentrant for different RxPduIds.
        • Sync/Async: Synchronous
        • Service ID: 0x54
        • Defined: CanIf.h


    • Callbacks
      • CanIf_TriggerTransmit
        • Notes:
          • Within this API, the upper layer module (called module) shall check whether the available data fits into the buffer size reported by PduInfoPtr->SduLength. If it fits, it shall copy its data into the buffer provided by PduInfoPtr->SduDataPtr and update the length of the actual copied data in PduInfoPtr->SduLength. If not, it returns E_NOT_OK without changing PduInfoPtr
          • CanIf shall only provide this callback if TriggerTransmit support is enabled (CanIfTriggerTransmitSupport = True)
        • Parameters:
          • In:
            • PduIdType TxPduId - ID of the SDU that is requested to be transmitted.
            • PduInfoType* PduInfoPtr - Contains a pointer to a buffer (SduDataPtr) to where the SDU data shall be copied, and the available buffer size in SduLengh. On return, the service will indicate the length of the copied SDU data in SduLength. 
        • Return: Std_ReturnType:
          • E_OK: SDU has been copied and SduLength indicates the number of copied bytes.
          • E_NOT_OK: No SDU data has been copied. PduInfoPtr must not be used since it may contain a NULL pointer or point to invalid data.
        • Reentrant: Reentrant for different PduIds. Non reentrant for the same PduId.
        • Sync/Async: Synchronous
        • Service ID: 0x41
        • Defined: CanIf.h


      • CanIf_TxConfirmation
        •  Notes:
          • This service confirms a previously successfully processed transmission of a CAN TxPDU.
          • If CanTxPduId has an invalid value then CanIf shall report development error code CANIF_E_PARAM_LPDU.
        • Parameters:
          • In:
            • PduIdType TxPduId - L-PDU handle of CAN L-PDU successfully transmitted. This ID specifies the corresponding CAN L-PDU ID and implicitly the CAN Driver instance as well as the corresponding CAN controller device.
        • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x13
        • Defined: CanIf_Can.h


      • CanIf_RxIndication
        •  Notes:
          • This service indicates a successful reception of a received CAN Rx L-PDU to the CanIf after passing all filters and validation checks.
          • If Mailbox→Hoh has an invalid value then CanIf shall report development error code CANIF_E_PARAM_HOH to DET.
          • If Mailbox→CanId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_CANID to DET.
          • If PduInfoPtr->SduLength is an invalid value then CanIf shall report development error code CANIF_E_INVALID_DATA_LENGTH to DET.
          • If PduInfoPtr or Mailbox has an invalid value then CanIf shall report development error code CANIF_E_PARAM_POINTER to DET.
        • Parameters:
          • In:
            • const Can_HwType* Mailbox - Identifies the HRH and its corresponding CAN Controller.
            • const PduInfoType* PduInfoPtr - Pointer to the received L-PDU.
        • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x14
        • Defined: CanIf_Can.h


      • CanIf_XLRxIndication
        •  Notes:
          • This service indicates a successful reception of a received CAN XL Rx L-PDU to the CanIf after passing all filters and validation checks. It provides the CAN XL specific parameters besides the hardware and actual L-PDU  information.
          • If Mailbox→Hoh has an invalid value then CanIf shall report development error code CANIF_E_PARAM_HOH to DET.
          • If Mailbox→CanId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_CANID to DET.
          • If PduInfoPtr, Mailbox or Mailbox->XLParams  has an invalid value then CanIf shall report development error code CANIF_E_PARAM_POINTER to DET.
        • Parameters:
          • In:
            • const CanXL_HwType* Mailbox  -  Identifies the HRH and its corresponding CAN Controller.
            • const PduInfoType* PduInfoPtr - Pointer to the received L-PDU.
        • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x55
        • Defined: CanIf_Can.h


      • CanIf_ControllerBusOff
        •  Notes:
          • This service indicates a Controller BusOff event referring to the corresponding CAN Controller with the abstract CanIf ControllerId.
          • If ControllerId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID to DET.
        • Parameters:
          • In:
            • uint8 ControllerId - Abstract CanIf ControllerId which is assigned to a CAN controller where a BusOff occured.
        • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x16
        • Defined: CanIf_Can.h
    •  
      • CanIf_ConfirmPnAvailability
        •  Notes:
          • This service indicates that the transceiver is running in PN communication mode referring to the corresponding CAN transceiver with the abstract CanIf TransceiverId.
          • If TransceiverId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_TRCV to DET.
          • This function shall be pre compile time configurable ON/OFF by the configuration parameter CanIfPublicPnSupport and CanIfPublicTrcvPnEnable.
        • Parameters:
          • In:
            • uint8 TransceiverId - Abstract CanIf TransceiverId, which is assigned to a CAN transceiver which was checked for PN availability..
        • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x1a
        • Defined: CanIf_CanTrcv.h


      • CanIf_ConfirmCtrlPnAvailability
        •  Notes:
          • This service indicates that the controller is running in PN communication mode referring to the corresponding CAN controller with the abstract CanIf ControllerId.
          • If ControllerId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID to DET.
          • This function shall be pre compile time configurable ON/OFF by the configuration parameter CanIfPublicPnSupport and CanIfPublicCtrlPnEnable.
        • Parameters:
          • In:
            • uint8 ControllerId- Abstract CanIf ControllerId, which is assigned to a CAN controller which was checked for PN availability..
        • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x56
        • Defined: CanIf_CanDrv.h


      • CanIf_ClearTrcvWufFlagIndication 
        • Notes:
          • This service indicates that the transceiver has cleared the WufFlag referring to the corresponding CAN transceiver with the abstract CanIf TransceiverId.
          • If TransceiverId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_TRCV to DET.
          • This function shall be pre compile time configurable ON/OFF by the configuration parameter CanIfPublicPnSupport and CanIfPublicTrcvPnEnable.
        • Parameters:
          • In:
            • uint8 TransceiverId - Abstract CanIf TransceiverId, which is assigned to a CAN transceiver which was checked for PN availability..
        • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x20
        • Defined: CanIf_CanTrcv.h


      • CanIf_CheckTrcvWakeFlagIndication
        • Notes:
          • This service indicates that the check of the transceiver’s wake-up flag has been finished by the corresponding CAN transceiver with the abstract CanIf TransceiverId. This indication is used to cope with the asynchronous transceiver communication.
          • If TransceiverId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_TRCV to DET.
          • This function shall be pre compile time configurable ON/OFF by the configuration parameter CanIfPublicPnSupport and CanIfPublicTrcvPnEnable.
        • Parameters:
          • In:
            • uint8 TransceiverId - Abstract CanIf TransceiverId, which is assigned to a CAN transceiver which was checked for PN availability..
        • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x21
        • Defined: CanIf_CanTrcv.h


      • CanIf_ControllerModeIndication
        • Notes:
          • This service indicates a controller state transition referring to the corresponding CAN controller with the abstract CanIf ControllerId.
          • If ControllerId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID to DET.
        • Parameters:
          • In:
            • uint8 ControllerId - Abstract CanIf ControllerId which is assigned to a CAN controller which state has been transitioned.
            • Can_ControllerStateType ControllerMode - Mode to which the CAN controller transitioned.
          • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x17
        • Defined: CanIf_Can.h


      • CanIf_TrcvModeIndication
        • Notes:
          • This service indicates a transceiver state transition referring to the corresponding CAN transceiver with the abstract CanIf TransceiverId.
          • If TransceiverId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_TRCV to DET.
          • If transceivers are not supported (CanIfTrcvDrvCfg is not configured, then this function shall not be provided by CanIf.
        • Parameters:
          • In:
            • uint8 ControllerId - Abstract CanIf TransceiverId, which is assigned to a CAN transceiver which state has been transitioned. 
            • CanTrcv_TrcvModeType TransceiverMode - Mode to which the CAN transceiver transitioned.
          • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x22
        • Defined: CanIf_CanTrcv.h


      • CanIf_ControllerErrorStatePassive
        • Notes:
          • The function derives the ErrorCounterTreshold from RxErrorCounter/ TxErrorCounter values and reports it to the IdsM as security event SEV_CAN_ERRORSTATE_PASSIVE to the IdsM. It also prepares the context data for the  respective security event.
          • If ControllerId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID to DET.
        • Parameters:
          • In:
            • uint8 ControllerId - Abstracted CanIf ControllerId which is assigned to a CAN controller.
            • uint16 RxErrorCounter - Value of the Rx error counter.
            • uint16 TxErrorCounter - Value of the Tx error counter.
          • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x4f
        • Defined: CanIf_Can.h


      • CanIf_ErrorNotification
        • Notes:
          • The function shall derive the bus error source rx or tx from the parameter CanError and report the bus error as security event SEV_CAN_TX_ERROR_DETECTED or SEV_CAN_RX_ERROR_DETECTED. It also prepares the context  data for the respective security event. If ControllerId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID to DET.
          • If ControllerId has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_CONTROLLERID to DET.
          • If Can_ErrorType  has is an invalid value then CanIf shall report development error code CANIF_E_PARAM_CAN_ERROR  to DET.
        • Parameters:
          • In:
            • uint8 ControllerId - Abstracted CanIf ControllerId which is assigned to a CAN controller.
            • Can_ErrorType Can_ErrorType - Reported CAN error.
          • Return: Void
        • Reentrant: Reentrant
        • Sync/Async: Synchronous
        • Service ID: 0x50
        • Defined: CanIf_Can.h


  • Interface
    • Mandatory Interfaces/APs 
      • Can_GetControllerErrorState - This service obtains the error state of the CAN controller.
      • Can_GetControllerRxErrorCounter - Returns the Rx error counter for a CAN controller. This value might not be available for all CAN controllers, in which case E_NOT_OK would be returned. Please note that the value of the counter might not be correct at the moment the API returns it, because the Rx counter is handled asynchronously in hardware. Applications should not trust this value for any assumption about the current bus state.
      • Can_GetControllerTxErrorCounter - Returns the Tx error counter for a CAN controller. This value might not be available for all CAN controllers, in which case E_NOT_OK would be returned. Please note that the value of the counter might not
        be correct at the moment the API returns it, because the Tx counter is handled asynchronously in hardware. Applications should not trust this value for any assumption about the current bus state. 
      • Can_SetControllerMode - This function performs software triggered state transitions of the CAN controller State machine.
      • Can_Write - This function is called by CanIf to pass a CAN message to CanDrv for transmission.
      • Det_ReportRuntimeError - Service to report runtime errors. If a callout has been configured then this callout shall be called.
    • Optional Interfaces
      • Can_CheckWakeup - This function checks if a wakeup has occurred for the given controller.
      • Can_SetBaudrate - This service shall set the baud rate configuration of the CAN controller. Depending on necessary baudrate modifications the controller might have to reset.
      • CanNm_RxIndication - Indication of a received PDU from a lower layer communication interface module.
      • CanNm_TxConfirmation - The lower layer communication interface module confirms the transmission of a PDU, or the failure to transmit a PDU.
      • CanSM_CheckTransceiverWakeFlagIndication - This callback function indicates the CanIf_Check TrcvWakeFlag API process end for the notified CAN Transceiver.
      • CanSM_ClearTrcvWufFlagIndication - This callback function shall indicate the CanIf_Clear TrcvWufFlag API process end for the notified CAN Transceiver.
      • CanSM_ConfirmCtrlPnAvailability - This callback function indicates that the controller is running in PN communication mode.
      • CanSM_ConfirmPnAvailability - This callback function indicates that the transceiver is running in PN communication mode.
      • CanSM_ControllerBusOff - This callback function notifies the CanSM about a bus-off event on a certain CAN controller, which needs to be considered with the specified bus-off recovery handling for the impacted CAN network.
      • CanSM_ControllerModeIndication - This callback shall notify the CanSM module about a CAN controller mode change.
      • CanSM_TransceiverModeIndication - This callback shall notify the CanSM module about a CAN transceiver mode change.
      • CanTp_RxIndication - Indication of a received PDU from a lower layer communication interface module.
      • CanTp_TxConfirmation - The lower layer communication interface module confirms the transmission of a PDU, or the failure to transmit a PDU.
      • CanTrcv_CheckWakeFlag - Requests to check the status of the wakeup flag from the transceiver hardware.
      • CanTrcv_CheckWakeup - Service is called by underlying CANIF in case a wake up interrupt is detected.
      • CanTrcv_GetBusWuReason - Gets the wakeup reason for the Transceiver and returns it in parameter Reason.
      • CanTrcv_GetOpMode - Gets the mode of the Transceiver and returns it in OpMode.
      • CanTrcv_SetOpMode - Sets the mode of the Transceiver to the value Op Mode.
      • CanTrcv_SetWakeupMode - Enables, disables or clears wake-up events of the Transceiver according to TrcvWakeupMode.
      • CanTSyn_RxIndication - Indication of a received PDU from a lower layer communication interface module.
      • CanTSyn_TxConfirmation - The lower layer communication interface module confirms the transmission of a PDU, or the failure to transmit a PDU.
      • CanXL_Write - This function is called by CanIf to pass a CAN XL message to the CAN XL driver for transmission. It provides the CAN XL specific parameters besides the hardware handle and actual PDU information
      • Det_ReportError - Service to report development errors.
        EcuM_ValidateWakeupEvent - After wakeup, the ECU State Manager will stop the process during the WAKEUP VALIDATION state/sequence to wait for validation of the wakeup event. This API service is used to indicate to the ECU
        Manager module that the wakeup events indicated in the sources parameter have been validated.
      • IdsM_SetSecurityEventWithContextData - This API is the application interface to report security events with context data to the IdsM.
      • J1939Nm_RxIndication - Indication of a received PDU from a lower layer communication interface module.
      • J1939Nm_TxConfirmation - The lower layer communication interface module confirms the transmission of a PDU, or the failure to transmit a PDU. 
      • J1939Tp_RxIndication - Indication of a received PDU from a lower layer communication interface module.
      • J1939Tp_TxConfirmation - The lower layer communication interface module confirms the transmission of a PDU, or the failure to transmit a PDU.
      • Mirror_ReportCanFrame - Reports a received or transmitted CAN frame. All received CAN frames that pass the hardware acceptance filter are reported, independent of the software filter configuration. Transmitted CAN frames are reported when the transmission is confirmed.
      • PduR_CanIfRxIndication - Indication of a received PDU from a lower layer communication interface module. PduR_CanIfTxConfirmation PduR_CanIf.h The lower layer communication interface module confirms the transmission of a PDU, or the failure to transmit a PDU.
      • Xcp_CanIfRxIndication - Indication of a received PDU from a lower layer communication interface module.
      • Xcp_CanIfTxConfirmation - The lower layer communication interface module confirms the transmission of a PDU, or the failure to transmit a PDU.


  • No labels