LIN Transceiver Driver (LinTrcv)

The LIN Transceiver Driver controls the physical LIN transceiver of a channel and decouples LinIf from the hardware. According to LinTrcv_Init, the initial mode is SLEEP. LinTrcv_SetOpMode switches between NORMAL, STANDBY, and SLEEP, and returns E_NOT_OK if the switch fails [SWS_LinTrcv_00002]. External wakeups are detected via the ICU and reported when LinIf invokes LinTrcv_CheckWakeup. In R20-11, E_OK means "wakeup detected" [SWS_LinTrcv_00012]. Wait times for state transitions must be implemented using Tm_BusyWait1us16bit.

more ›

The LIN Transceiver Driver controls the physical LIN transceiver of a channel and decouples the LIN interface from the hardware. LinIf calls its services directly: for example, LinIf_SetTrcvMode invokes LinTrcv_SetOpMode and returns its result unchanged [SWS_LinTrcv_00002] LinIf-SWS p. 90. Software and hardware states are separated. The implementation decides which hardware states are covered by a software mode LinTrcv-SWS p. 16.

The driver recognizes the modes LINTRCV_TRCV_MODE_NORMAL, LINTRCV_TRCV_MODE_STANDBY, and LINTRCV_TRCV_MODE_SLEEP [SWS_LinTrcv_00168]. It is inactive after power-on. LinTrcv_Init activates it with a configuration set [SWS_LinTrcv_00001]; the initial mode is SLEEP LinTrcv-SWS p. 1. STANDBY is optional and can be a purely internal state LinTrcv-SWS Fig. 7.1 p. 15.

State diagram: Lifecycle from power-on via LinTrcv_Init to the mode switches with LinTrcv_SetOpMode. The optional transitions are reconstructed (interpretation). Sources: LinTrcv-SWS Fig. 7.1 p. 15 [SWS_LinTrcv_00168]

The driver does not detect external wakeups via its own ISR, but via the ICU LinTrcv-SWS p. 17. LinIf queries them using LinTrcv_CheckWakeup. In R20-11, E_OK means "wakeup detected" [SWS_LinTrcv_00012]. Later releases define this differently. A detected wakeup is reported via LinIf_WakeupConfirmation [SWS_LinTrcv_91002]. LinTrcv_SetWakeupMode enables or disables notification, or clears stored events [SWS_LinTrcv_00169].

Sequence diagram: External wakeup from ICU detection via LinTrcv_CheckWakeup and LinIf_WakeupConfirmation to querying the reason. Sources: [SWS_LinTrcv_00012] [SWS_LinTrcv_91002] LinTrcv-SWS p. 17

The following boundary conditions apply to operation:

• Wait times during state transitions must be implemented using Tm_BusyWait1us16bit [SWS_LinTrcv_00171].
• On multi-core systems, LinTrcvChannel and LinChannel of a channel must reference the same partition [SWS_LinTrcv_00177].
• In the event of faulty communication to the transceiver, the queries return E_NOT_OK LinTrcv-SWS p. 26.

The DET error codes are documented only from later releases. Because R21-11 cleaned up the error codes, their names may differ in R20-11 LinTrcv-SWS p. 1.

more ›

Role between LIN Interface and Transceiver Device

The LIN Transceiver Driver (LinTrcv) encapsulates the control of the physical LIN transceiver. Its interface consists of seven services:

• Initialization with LinTrcv_Init [SWS_LinTrcv_00001]
• Mode switch with LinTrcv_SetOpMode [SWS_LinTrcv_00002]
• Mode query with LinTrcv_GetOpMode [SWS_LinTrcv_00005]
• Query of wakeup reason with LinTrcv_GetBusWuReason [SWS_LinTrcv_00007]
• Control of wakeup notification with LinTrcv_SetWakeupMode [SWS_LinTrcv_00009]
• Wakeup check with LinTrcv_CheckWakeup [SWS_LinTrcv_00012]
• Version query with LinTrcv_GetVersionInfo [SWS_LinTrcv_00008]

All services are synchronous. The software states of the driver are separated from the hardware states of the device. The device may support more transitions than the driver. The implementation decides which hardware states are covered by a software state. However, it must fully provide the described functionality LinTrcv-SWS p. 16.

Upwards, the LIN interface (LinIf) is the user substantiated in the payload. The LinIf services each invoke a LinTrcv service:

• LinIf_SetTrcvMode invokes LinTrcv_SetOpMode and returns its return value unchanged LinIf-SWS p. 90.
• LinIf_GetTrcvMode invokes LinTrcv_GetOpMode LinIf-SWS p. 91.
• LinIf_GetTrcvWakeupReason invokes LinTrcv_GetBusWuReason LinIf-SWS p. 92.
• LinIf_SetTrcvWakeupMode invokes LinTrcv_SetWakeupMode LinIf-SWS p. 93.

The types LinTrcv_TrcvModeType and LinTrcv_TrcvWakeupModeType are available via Lin_GeneralTypes.h [SWS_LinTrcv_00168] [SWS_LinTrcv_00169]. LinIf uses them directly in its signatures. The former dedicated type LinIf_TrcvModeType was replaced by LinTrcv_TrcvModeType in version 3.1.5 LinIf-SWS p. 4.

Downwards, the driver uses the following services:

• the read and write services of Dio, Det_ReportError, and EcuM_SetWakeupEvent [SWS_LinTrcv_91003]
• types from Dio, Spi, Icu, and EcuM [SWS_LinTrcv_91001]
• Icu_EnableNotification and Icu_DisableNotification for wakeup notification LinTrcv-SWS p. 17
• the time service Tm_BusyWait1us16bit for wait times during state transitions [SWS_LinTrcv_00171]

The driver reports detected wakeups to LinIf via LinIf_WakeupConfirmation [SWS_LinTrcv_91002]. LinIf then sets the wakeup flag of the affected channel LinIf-SWS p. 98.

Context diagram: LinTrcv is located between LinIf and the hardware-oriented services Dio/Spi, Icu, and Tm, and reports wakeups back to LinIf. Sources: [SWS_LinTrcv_91001] [SWS_LinTrcv_91002] [SWS_LinTrcv_91003] [SWS_LinTrcv_00171] LinTrcv-SWS p. 17 LinTrcv-SWS Fig. 10.3 p. 45

Lifecycle of Operating Modes from Power-On to Sleep

The driver recognizes three software operating modes: LINTRCV_TRCV_MODE_NORMAL, LINTRCV_TRCV_MODE_STANDBY, and LINTRCV_TRCV_MODE_SLEEP [SWS_LinTrcv_00168]. Figure 7.1 of the specification places them into a lifecycle LinTrcv-SWS Fig. 7.1 p. 15:

• After power-on, the driver is in the state NOT_ACTIVE.
• LinTrcv_Init transitions it to the state ACTIVE. The three modes lie within ACTIVE.
• A loss of power terminates the lifecycle.

LinTrcv_Init receives a pointer to the selected configuration set [SWS_LinTrcv_00001]. The structure LinTrcv_ConfigType is implementation-specific [SWS_LinTrcv_00172]. Since version 4.3.1, the initial mode after initialization is restricted to LINTRCV_TRCV_MODE_SLEEP LinTrcv-SWS p. 1.

In state ACTIVE, LinTrcv_SetOpMode switches the internal state of the addressed channel to the passed mode [SWS_LinTrcv_00002] LinTrcv-SWS p. 25. Mode LINTRCV_TRCV_MODE_STANDBY is optional. It can be a purely internal state used by the hardware for transitions. Specific hardware may not require all interfaces LinTrcv-SWS Fig. 7.1 p. 15. The specification also states conditions under which LinTrcv_SetOpMode switches the channel to STANDBY. These conditions are cut off in the present excerpt and are not detailed here LinTrcv-SWS p. 25.

LinTrcv_GetOpMode provides the current software state of the driver in the output parameter OpMode [SWS_LinTrcv_00005] LinTrcv-SWS p. 26. This is not necessarily the state of the device. A caller can use this prior to a mode switch to check which mode the channel is in. Via LinIf, this query is available as LinIf_GetTrcvMode LinIf-SWS p. 91.

State diagram: After power-on, the driver is inactive. LinTrcv_Init leads to the active area with SLEEP as the initial mode; LinTrcv_SetOpMode switches between the modes. The optional transitions are reconstructed from the captions of Fig. 7.1 (interpretation). Conditional switches to STANDBY are not shown. Sources: LinTrcv-SWS Fig. 7.1 p. 15 [SWS_LinTrcv_00168] [SWS_LinTrcv_00001] LinTrcv-SWS p. 1

Mode Switches and Queries via the LIN Interface

Each service addresses a channel via the parameter LinNetwork of type uint8 [SWS_LinTrcv_00002] [SWS_LinTrcv_00005]. In LinIf, the corresponding parameter is named Channel and has the type NetworkHandleType LinIf-SWS p. 90.

LinTrcv_SetOpMode is synchronous and non-reentrant; the service ID is 0x01. The return values indicate [SWS_LinTrcv_00002]:

• E_OK: The transceiver state has switched to the requested mode.
• E_NOT_OK: The switch was not accepted, failed, or the parameter is outside the permissible range.

LinIf must permit the call for all transceivers and all modes, even if the hardware does not support a mode LinIf-SWS p. 90. Mapping to the hardware therefore remains the responsibility of LinTrcv.

The driver implements wait times during state transitions using Tm_BusyWait1us16bit [SWS_LinTrcv_00171]. Because LinTrcv_SetOpMode operates synchronously [SWS_LinTrcv_00002], this active wait time likely occurs within the call and extends its execution time (interpretation). Question Q-54fe21bbe7c737d9 (open) When switching to standby mode, the driver also activates the ICU channels for wakeup detection LinTrcv-SWS p. 17.

The query services are reentrant. LinTrcv_GetBusWuReason returns the detected wakeup reason in type LinTrcv_TrcvWakeupReasonType [SWS_LinTrcv_00007]. Its values include LINTRCV_WU_ERROR, LINTRCV_WU_NOT_SUPPORTED, LINTRCV_WU_BY_BUS, and LINTRCV_WU_BY_PIN [SWS_LinTrcv_00170]. Exactly how wakeup reasons can be distinguished depends heavily on the transceiver hardware LinTrcv-SWS p. 28. LinTrcv_GetVersionInfo returns the version information as Std_VersionInfoType [SWS_LinTrcv_00008] LinTrcv-SWS p. 29.

Sequence diagram: A mode switch runs from LinIf to LinTrcv. LinTrcv waits via Tm, activates the ICU notification when switching to STANDBY, and returns its result unchanged via LinIf. Control via Dio/Spi and the placement of the wait time within the call are interpretations. Sources: [SWS_LinTrcv_00002] [SWS_LinTrcv_00171] LinIf-SWS p. 90 LinTrcv-SWS p. 17

Detecting, Reporting, and Controlling Wakeups

The driver distinguishes two types of wakeups LinTrcv-SWS p. 17:

• Internal wakeup: An upper layer triggers it, for example via LinTrcv_Init or LinTrcv_SetOpMode.
• External wakeup: The driver detects it on the LIN channel. LinIf must call LinTrcv_CheckWakeup so that the wakeup is reported upwards.

The driver does not provide a dedicated ISR for wakeup. Detection takes place via the ICU using Icu_EnableNotification and Icu_DisableNotification. The wakeup type is selected via the configuration parameter LinTrcvWakeUpSupport. Wakeup support can be enabled and disabled per channel using LinTrcvWakeupByBusUsed LinTrcv-SWS p. 17.

LinTrcv_CheckWakeup evaluates the wakeup on the addressed network, such as a dominant bus level or a falling edge on the wakeup pin LinTrcv-SWS p. 30. In R20-11, the return values indicate [SWS_LinTrcv_00012]:

• E_OK: A wakeup was detected.
• E_NOT_OK: No wakeup was detected.

The document passage from later releases defines the values differently, as "call accepted/not accepted". This change was introduced with R22-11 and does not apply to R20-11 LinTrcv-SWS p. 1 LinTrcv-SWS p. 30. After successful detection, the driver reports the wakeup source via LinIf_WakeupConfirmation [SWS_LinTrcv_91002]. LinTrcv does not offer its own callback notifications LinTrcv-SWS p. 32. Therefore, LinTrcv_CheckWakeup must be actively called.

LinTrcv_SetWakeupMode is synchronous and non-reentrant. It controls wakeup notification per network via LinTrcv_TrcvWakeupModeType [SWS_LinTrcv_00009] [SWS_LinTrcv_00169]:

• LINTRCV_WUMODE_ENABLE enables the notification.
• LINTRCV_WUMODE_DISABLE disables it.
• LINTRCV_WUMODE_CLEAR clears a stored wakeup event.

If a stored event is already present when enabling, the driver executes the notification during the call or immediately thereafter LinTrcv-SWS p. 31. LinIf provides this control as LinIf_SetTrcvWakeupMode LinIf-SWS p. 93.

Sequence diagram: An external wakeup is detected via the ICU. LinIf checks it with LinTrcv_CheckWakeup, LinTrcv confirms it via LinIf_WakeupConfirmation, and the reason can be queried afterwards (return values according to R20-11). Sources: [SWS_LinTrcv_00012] [SWS_LinTrcv_91002] [SWS_LinTrcv_00007] LinTrcv-SWS p. 17 LinIf-SWS p. 98

Activity diagram: LinTrcv_SetWakeupMode branches according to the requested mode. A notification follows immediately only for ENABLE with a stored event. Sources: [SWS_LinTrcv_00009] [SWS_LinTrcv_00169] LinTrcv-SWS p. 31

Hardware Access, Channel Configuration, and Partitioning

How the driver accesses the device is specified by the choice container LinTrcvAccess LinTrcv-SWS Fig. 10.3 p. 45. Exactly one of two variants must be selected:

• LinTrcvDioAccess: The transceiver pins are mapped to DIO channels.
• LinTrcvSpiSequence: An SPI-capable device is addressed via an SPI sequence.

The diagram originates from R23-11 and later releases. However, the DIO read and write services as well as the SPI types are already listed in R20-11 as used interfaces and imported types, respectively [SWS_LinTrcv_91003] [SWS_LinTrcv_91001].

The following rules apply to multi-core systems in R20-11:

• The driver must reject configurations with unsupported partition assignments [SWS_LinTrcv_00174].
• The partitions referenced via LinTrcvChannelEcucPartitionRef must be a subset of those referenced via LinTrcvEcucPartitionRef. If the module references partitions, each channel must reference exactly one of them [SWS_LinTrcv_00176].
• LinTrcvChannel and LinChannel of the same communication channel must reference the same partition [SWS_LinTrcv_00177].

Multi-core distribution was added with R19-11 and clarified in R24-11 LinTrcv-SWS p. 1.

Behavior in the event of an error

Runtime errors are reflected in the return value:

• In the case of missing or faulty communication to the transceiver, LinTrcv_GetOpMode LinTrcv-SWS p. 26 and LinTrcv_GetBusWuReason LinTrcv-SWS p. 28 return E_NOT_OK.
• LinTrcv_SetOpMode returns E_NOT_OK if a switch was not accepted or failed [SWS_LinTrcv_00002].
• LinTrcv_SetWakeupMode returns E_NOT_OK if the wakeup mode could not be set LinTrcv-SWS p. 31.
• If a wakeup reason cannot be determined due to an error, the value LINTRCV_WU_ERROR is available for this purpose [SWS_LinTrcv_00170].

The driver reports development errors via Det_ReportError [SWS_LinTrcv_91003]. In R20-11, they result in E_NOT_OK for LinTrcv_GetOpMode and LinTrcv_GetBusWuReason [SWS_LinTrcv_00005] [SWS_LinTrcv_00007]. The document passages from later releases specify concrete checks LinTrcv-SWS p. 26 LinTrcv-SWS p. 30 LinTrcv-SWS p. 29:

• Call prior to initialization: LINTRCV_E_UNINIT
• invalid network number: LINTRCV_E_INVALID_LIN_NETWORK
• Null pointer for LinTrcv_GetVersionInfo: LINTRCV_E_PARAM_POINTER

In terms of content, these checks likely also apply to R20-11 (interpretation). Question Q-58e3d310b525b810 (open) However, R20-11 cleaned up the error classification and R21-11 the error codes. Therefore, the identifiers may differ in R20-11 LinTrcv-SWS p. 1.

Part of the incorrect operations is already caught by LinIf. If Channel is invalid, LinIf_SetTrcvMode and LinIf_GetTrcvMode report the error LINIF_E_NONEXISTENT_CHANNEL LinIf-SWS p. 90. In addition, LinIf_GetTrcvMode returns E_NOT_OK LinIf-SWS p. 91 in case of an invalid channel or null pointer. If LinIf_WakeupConfirmation receives an invalid wakeup source, it triggers LINIF_E_PARAM_WAKEUPSOURCE if error detection is activated LinIf-SWS p. 98.

Further detailed evidence

• [SWS_LinTrcv_00002] with LinTrcv-SWS p. 25: mode switch, return values, and transition to STANDBY.
• [SWS_LinTrcv_00012] with LinTrcv-SWS p. 30: wakeup check. The return values in R20-11 differ from later releases.
• [SWS_LinTrcv_00009] [SWS_LinTrcv_00169] with LinTrcv-SWS p. 31: enable, disable, and clear wakeup notification.
• [SWS_LinTrcv_00168] with LinTrcv-SWS Fig. 7.1 p. 15: operating modes and lifecycle.
• [SWS_LinTrcv_00170] with LinTrcv-SWS p. 28: wakeup reasons and their hardware dependency.
• [SWS_LinTrcv_00171]: wait times via Tm_BusyWait1us16bit.
• [SWS_LinTrcv_00174] [SWS_LinTrcv_00176] [SWS_LinTrcv_00177]: partitioning on multi-core ECUs.
• [SWS_LinTrcv_91001] [SWS_LinTrcv_91002] [SWS_LinTrcv_91003]: imported types, wakeup confirmation to LinIf, and other used interfaces.
• LinTrcv-SWS p. 17: internal and external wakeups, ICU usage, and wakeup configuration.