LIN C API

The LIN API for the C language provides communication in a LIN bus master/slave-architecture. The functionality is analogous to the C++ API described in LIN Service API.

LIN Controller

A LIN controller is created with the following function:

SilKit_ReturnCode SilKit_LinController_Create(SilKit_LinController **outLinController, SilKit_Participant *participant, const char *name, const char *network)

Create a LIN controller at this SIL Kit simulation participant.

The lifetime of the resulting LIN controller is directly bound to the lifetime of the simulation participant. There is no further cleanup necessary except for destroying the simulation participant at the end of the simulation.

Parameters

  • outLinController – Pointer into which the resulting LIN controller will be written (out parameter).

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

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

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

Returns

SilKit_ReturnCode

A LIN controller’s configuration is handed over to the function:

SilKit_ReturnCode SilKit_LinController_Init(SilKit_LinController *controller, const SilKit_LinControllerConfig *config)

Initialize the LIN controller defining its role and RX/TX configuration.

All controllers must be initialized exactly once to take part in LIN communication.

AUTOSAR Name: Lin_Init

Parameters

  • controller – The LIN controller to initialize

  • config – The controller configuration contains:

    • controllerMode, either sets LIN master or LIN slave mode.

    • baudRate, determine transmission speeds (only used for detailed simulation).

    • frameResponses, a vector of LinFrameResponse. This must contain the final configuration on which LIN Ids the controller will receive (SilKit_LinFrameResponseMode_Rx) or respond to (SilKit_LinFrameResponseMode_TxUnconditional) frames. An exception is the use of SilKit_LinController_SendFrame for LinFrameResponseType::MasterResponse, which allows to extend the configuration during operation.

Returns

SilKit_ReturnCode

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

SilKit_ReturnCode SilKit_LinController_AddFrameStatusHandler(SilKit_LinController *controller, void *context, SilKit_LinFrameStatusHandler_t handler, SilKit_HandlerId *outHandlerId)

Reports the SilKit_LinFrameStatus of a SilKit_LinFrame and provides the transmitted frame.

The handler is used for reception and acknowledgement of LIN frames. The direction (prefixed with LIN_TX_ or LIN_RX_) and error state of the tranmission is encoded in the SilKit_LinFrameStatus.

Parameters

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

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

  • handler – The handler to be called.

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

Returns

SilKit_ReturnCode

SilKit_ReturnCode SilKit_LinController_AddGoToSleepHandler(SilKit_LinController *controller, void *context, SilKit_LinGoToSleepHandler_t handler, SilKit_HandlerId *outHandlerId)

The GoToSleepHandler is called whenever a go-to-sleep frame was received.

Note: The LIN controller does not automatically enter sleep mode up reception of a go-to-sleep frame. I.e., SilKit_LinController_GoToSleepInternal() must be called manually

Note: This handler will always be called, independently of the SilKit_LinFrameResponseMode configuration for LIN ID 0x3C. However, regarding the SilKit_LinFrameStatusHandler, the go-to-sleep frame is treated like every other frame, i.e. the SilKit_LinFrameStatusHandler is only called for LIN ID 0x3C if configured as SilKit_LinFrameResponseMode_Rx.

Parameters

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

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

  • handler – The handler to be called.

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

Returns

SilKit_ReturnCode

SilKit_ReturnCode SilKit_LinController_AddWakeupHandler(SilKit_LinController *controller, void *context, SilKit_LinWakeupHandler_t handler, SilKit_HandlerId *outHandlerId)

The WakeupHandler is called whenever a wake up pulse is received.

Note: The LIN controller does not automatically enter operational mode on wake up pulse detection. I.e., WakeInternal() must be called manually.

Parameters

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

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

  • handler – The handler to be called.

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

Returns

SilKit_ReturnCode

SilKit_ReturnCode SilKit_LinController_RemoveFrameStatusHandler(SilKit_LinController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_LinFrameStatusHandler_t by SilKit_HandlerId on this controller.

Parameters

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

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

Returns

SilKit_ReturnCode

SilKit_ReturnCode SilKit_LinController_RemoveGoToSleepHandler(SilKit_LinController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_LinGoToSleepHandler_t by SilKit_HandlerId on this controller.

Parameters

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

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

Returns

SilKit_ReturnCode

SilKit_ReturnCode SilKit_LinController_RemoveWakeupHandler(SilKit_LinController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_LinWakeupHandler_t by SilKit_HandlerId on this controller.

Parameters

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

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

The following functions operate on a configured controller:

SilKit_ReturnCode SilKit_LinController_Status(SilKit_LinController *controller, SilKit_LinControllerStatus *outStatus)

Get the current status of the LIN Controller, i.e., Operational or Sleep.

Parameters

  • controller – The LIN controller to retrieve the status

  • outStatus – Pointer into which the status will be written (out parameter).

Returns

SilKit_ReturnCode

SilKit_ReturnCode SilKit_LinController_SetFrameResponse(SilKit_LinController *controller, const SilKit_LinFrameResponse *response)

Set a RX/TX configuration during operation.

Parameters

  • controller – The LIN controller to set the configuration.

  • response – The frame and response mode to be configured.

Throws

SilKit::StateError – if the LIN Controller is not initialized.

SilKit_ReturnCode SilKit_LinController_SendFrame(SilKit_LinController *controller, const SilKit_LinFrame *frame, SilKit_LinFrameResponseType responseType)

Initiate a LIN data transfer of a given LinFrameResponseType (AUTOSAR LIN master interface)

The responseType determines if frame.data is used for the frame response or if a different node has to provide it:

  • MasterResponse: LinFrame is sent from this controller to all connected slaves using frame.data. The LIN Master doesn’t have to be configured with SilKit_LinFrameResponseMode_TxUnconditional on this LIN ID.

  • SlaveResponse: the frame response must be provided by a connected slave and is received by this controller.

  • SlaveToSlave: the frame response must be provided by a connected slave and is ignored by this controller.

AUTOSAR Name: Lin_SendFrame

Parameters

  • controller – The LIN controller to operate on

  • frame – Provides the LIN identifier, checksum model, and optional data.

  • responseType – Determines which LIN Node will provide the frame response.

Returns

SilKit_ReturnCode

SilKit_ReturnCode SilKit_LinController_SendFrameHeader(SilKit_LinController *controller, SilKit_LinId linId)

Initiate a LIN data transfer by sending a LIN header (AUTOSAR LIN master interface)

Parameters

  • controller – The LIN controller to operate on

  • linId – Provides the LIN header identifier. The node that is configured to respond on this ID will complete the transmission and provide the response data.

Throws

SilKit::StateError – if the LIN Controller is not initialized or not a master node.

SilKit_ReturnCode SilKit_LinController_GoToSleep(SilKit_LinController *controller)

Transmit a go-to-sleep-command and set SilKit_LinControllerStatus_Sleep and enable wake-up.

AUTOSAR Name: Lin_GoToSleep

Parameters

controller – The LIN controller to operate on

Returns

SilKit_ReturnCode_SUCCESS or SilKit_ReturnCode_WRONGSTATE if issued with wrong SilKit_LinControllerMode

SilKit_ReturnCode SilKit_LinController_GoToSleepInternal(SilKit_LinController *controller)

Set SilKit_LinControllerStatus_Sleep without sending a go-to-sleep command.

AUTOSAR Name: Lin_GoToSleepInternal

Parameters

controller – The LIN controller to operate on

Returns

SilKit_ReturnCode_SUCCESS or SilKit_ReturnCode_WRONGSTATE if issued with wrong SilKit_LinControllerMode

SilKit_ReturnCode SilKit_LinController_Wakeup(SilKit_LinController *controller)

Generate a wake up pulse and set SilKit_LinControllerStatus_Operational.

AUTOSAR Name: Lin_Wakeup

Parameters

controller – The LIN controller to operate on

Returns

SilKit_ReturnCode_SUCCESS or SilKit_ReturnCode_WRONGSTATE if issued with wrong SilKit_LinControllerMode

SilKit_ReturnCode SilKit_LinController_WakeupInternal(SilKit_LinController *controller)

Set SilKit_LinControllerStatus_Operational without generating a wake up pulse.

AUTOSAR Name: Lin_WakeupInternal

Parameters

controller – The LIN controller to operate on

Returns

SilKit_ReturnCode_SUCCESS or SilKit_ReturnCode_WRONGSTATE if issued with wrong SilKit_LinControllerMode

The following functions are experimental and might be changed or removed in future versions:

SilKit_ReturnCode SilKit_Experimental_LinController_AddLinSlaveConfigurationHandler(SilKit_LinController *controller, void *context, SilKit_Experimental_LinSlaveConfigurationHandler_t handler, SilKit_HandlerId *outHandlerId)

The LinSlaveConfigurationHandler is called whenever a remote LIN Slave is configured via SilKit_LinController_Init.

Note: This callback is mainly for diagnostic purposes and is NOT needed for regular LIN controller operation. It can be used to call SilKit_Experimental_LinController_GetSlaveConfiguration to keep track of LIN Ids, where a response of a LIN Slave is to be expected.

Requires SilKit_LinControllerMode_Master

Parameters

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

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

  • handler – The handler to be called.

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

Returns

SilKit_ReturnCode

SilKit_ReturnCode SilKit_Experimental_LinController_RemoveLinSlaveConfigurationHandler(SilKit_LinController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_Experimental_LinSlaveConfigurationHandler_t by SilKit_HandlerId on this controller.

Parameters

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

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

Returns

SilKit_ReturnCode

SilKit_ReturnCode SilKit_Experimental_LinController_GetSlaveConfiguration(SilKit_LinController *controller, SilKit_Experimental_LinSlaveConfiguration *outLinSlaveConfiguration)

Get the aggregated configuration of all LIN slaves in the network.

Requires SilKit_LinControllerMode_Master

Parameters

  • outLinSlaveConfiguration – Pointer into which the resulting LinSlaveConfiguration will be written (out parameter)

  • controller – The LIN controller to operate on

Returns

SilKit_ReturnCode_SUCCESS or SilKit_ReturnCode_WRONGSTATE if issued with wrong SilKit_LinControllerMode

Data Structures

struct SilKit_LinControllerConfig

Configuration data to initialize the LIN Controller Cf.: SilKit_LinController_Init();

Public Members

SilKit_StructHeader structHeader

The interface id specifying which version of this struct was obtained

SilKit_LinControllerMode controllerMode

Configure as LIN master or LIN slave

SilKit_LinBaudRate baudRate

The operational baud rate of the controller.

size_t numFrameResponses
SilKit_LinFrameResponse *frameResponses

LinFrameResponse configuration.

struct SilKit_LinFrame

A LIN SilKit_LinFrame.

This Type is used to provide LIN ID, checksum model, data length and data.

AUTOSAR Name: Lin_PduType

Public Members

SilKit_StructHeader structHeader

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

SilKit_LinId id

LIN Identifier.

SilKit_LinChecksumModel checksumModel

Checksum Model.

SilKit_LinDataLength dataLength

Data length.

uint8_t data[8]

The actual payload.

struct SilKit_LinFrameResponse

Configuration data for a LIN Slave task for a particular LIN ID.

Public Members

SilKit_StructHeader structHeader

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

SilKit_LinFrame *frame

frame must provide the LIN SilKit_LinId for which the response is configured.

If responseMode is SilKit_LinFrameResponseMode_TxUnconditional, the frame data is used for the transaction.

SilKit_LinFrameResponseMode responseMode

Determines if the LinFrameResponse is used for transmission (TxUnconditional), reception (Rx) or ignored (Unused).

struct SilKit_Experimental_LinSlaveConfiguration

The aggregated configuration of all LIN slaves in the network.

Param numRespondingLinIds

The number of entries in respondingLinIds.

Param respondingLinIds

An array of SilKit_LinId on which any LIN Slave has configured SilKit_LinFrameResponseMode_TxUnconditional

Public Members

SilKit_StructHeader structHeader

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

SilKit_Bool isLinIdResponding[64]
struct SilKit_LinFrameStatusEvent

A LIN frame status event delivered in the SilKit_LinFrameStatusHandler_t.

Public Members

SilKit_StructHeader structHeader

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

SilKit_NanosecondsTime timestamp

Time of the event.

SilKit_LinFrame *frame
SilKit_LinFrameStatus status
struct SilKit_LinWakeupEvent

A LIN wakeup event delivered in the SilKit_LinWakeupHandler_t.

Public Members

SilKit_StructHeader structHeader

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

SilKit_NanosecondsTime timestamp

Time of the event.

SilKit_Direction direction

The direction of the event.

struct SilKit_LinGoToSleepEvent

A LIN goToSleep event delivered in the SilKit_LinGoToSleepHandler_t.

Public Members

SilKit_StructHeader structHeader

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

SilKit_NanosecondsTime timestamp

Time of the event.

The following data structures are experimental and might be changed or removed in future versions:

struct SilKit_Experimental_LinSlaveConfigurationEvent

A LIN wakeup event delivered in the SilKit_LinWakeupHandler_t.

Public Members

SilKit_StructHeader structHeader

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

SilKit_NanosecondsTime timestamp

Time of the event.

typedef void (*SilKit_Experimental_LinSlaveConfigurationHandler_t)(void *context, SilKit_LinController *controller, const SilKit_Experimental_LinSlaveConfigurationEvent *slaveConfigurationEvent)

Callback type to indicate that a LIN Slave configuration has been received. Cf., SilKit_Experimental_LinController_AddLinSlaveConfigurationHandler;

Enumerations and Typedefs

typedef struct SilKit_LinController SilKit_LinController

The LIN controller can assume the role of a LIN master or a LIN slave. It provides two kinds of interfaces to perform data transfers and provide frame responses:

AUTOSAR-like LIN master interface:

non-AUTOSAR interface:

  • SilKit_LinController_SendFrameHeader() initiates the transmission of a LIN frame for a particular LIN identifier. For a successful transmission, exactly one LIN slave or master must have previously set a corresponding frame response for unconditional transmission. Requires SilKit_LinControllerMode_Master.

typedef uint32_t SilKit_LinControllerStatus

The operational state of the controller, i.e., operational or sleeping.

typedef uint8_t SilKit_LinControllerMode

Used to configure a LIN controller as a master or slave.

Cf. SilKit_LinControllerConfig, SilKit_LinController_Init()

typedef uint32_t SilKit_LinBaudRate

The operational baud rate of the controller. Used in detailed simulation.

Range: 200…20’000 Bd

typedef uint8_t SilKit_LinFrameResponseMode

Controls the behavior of a LIN Slave task for a particular LIN ID.

typedef uint8_t SilKit_LinId

The identifier of a LIN SilKit_LinFrame.

This type represents all valid identifier used by SilKit_LinController_SendFrame(), SilKit_LinController_SendFrameHeader().

Range: 0…0x3F

typedef uint8_t SilKit_LinChecksumModel

The checksum model of a LIN SilKit_LinFrame.

This type is used to specify the Checksum model to be used for the LIN SilKit_LinFrame.

typedef uint8_t SilKit_LinFrameResponseType

Controls the behavior of SilKit_LinController_SendFrame()

Determines whether the master also provides a frame response or if the frame response is expected to be provided from a slave.

typedef uint8_t SilKit_LinFrameStatus

The state of a LIN transmission.

Used to indicate the success or failure of a LIN transmission to a registered SilKit_LinFrameStatusHandler_t.

Note: the enumeration values directly correspond to the AUTOSAR type Lin_StatusType. Not all values are used in the SIL Kit.

AUTOSAR Doc: LIN operation states for a LIN channel or frame, as returned by the API service Lin_GetStatus().

typedef uint8_t SilKit_LinDataLength

The data length of a LIN SilKit_LinFrame in bytes.

This type is used to specify the number of data bytes to copy.

Range: 1…8

const SilKit_LinDataLength SilKit_LinDataLengthUnknown = 255u

If configured for reception with this value, the data length validation of incoming frames is skipped.

typedef void (*SilKit_LinFrameStatusHandler_t)(void *context, SilKit_LinController *controller, const SilKit_LinFrameStatusEvent *frameStatusEvent)

Callback type to indicate the end of a LIN Frame transmission.

Param context

The context provided by the user on registration.

Param controller

The LIN controller that received the acknowledge.

Param frameStatusEvent

The event containing a timestamp, the corresponding frame and the new status.

typedef void (*SilKit_LinGoToSleepHandler_t)(void *context, SilKit_LinController *controller, const SilKit_LinGoToSleepEvent *goToSleepEvent)

Callback type to indicate that a go-to-sleep frame has been received. Cf., SilKit_LinController_AddGoToSleepHandler();

typedef void (*SilKit_LinWakeupHandler_t)(void *context, SilKit_LinController *controller, const SilKit_LinWakeupEvent *wakeUpEvent)

Callback type to indicate that a wakeup pulse has been received. Cf., SilKit_LinController_AddWakeupHandler;