FlexRay C API

The FlexRay API consists of the following parts:

  • The FlexRay controller

  • The FlexRay controller and TX buffer configuration

  • A set of FlexRay specific messages, each with its own function to register callbacks: Message, MessageAck, Wakeup, ControllerStatus, PocStatus, Symbol, SymbolAck, CycleStart

FlexRay Controller

A FlexRay controller interacts with the configured FlexRay bus and sends FlexRay frames and other events on its own behalf. Note that it is not possible to explicitly send frames or other events, nor exist any API functions to construct these events. This is because the FlexRay bus works completely time triggered, sending preconfigured frames. To configure these frames, the API provides functions to manipulate Tx buffers.

The following functions can be used to create a FlexRay controller and manipulate its configuration:

SilKit_ReturnCode SilKit_FlexrayController_Create(SilKit_FlexrayController **outController, SilKit_Participant *participant, const char *name, const char *network)
SilKit_ReturnCode SilKit_FlexrayController_Configure(SilKit_FlexrayController *controller, const SilKit_FlexrayControllerConfig *config)

Apply the given controller configuration to the controller.

SilKit_ReturnCode SilKit_FlexrayController_ReconfigureTxBuffer(SilKit_FlexrayController *controller, uint16_t txBufferIdx, const SilKit_FlexrayTxBufferConfig *config)

Reconfigure a TX Buffer that was previously setup with SilKit_FlexrayController_Configure()

SilKit_ReturnCode SilKit_FlexrayController_UpdateTxBuffer(SilKit_FlexrayController *controller, const SilKit_FlexrayTxBufferUpdate *update)

Update the content of a previously configured TX buffer.

A FlexRay message will be sent at the time matching the configured Slot ID. If the buffer was configured with FlexrayTransmissionMode::SingleShot, the content is sent exactly once. If it is configured as FlexrayTransmissionMode::Continuous, the content is sent repeatedly according to the offset and repetition configuration.

See also

SilKit_FlexrayController_Configure(const FlexrayControllerConfig&)

The following function can be used to manipulate the controller’s state by triggering Controller Host Interface (CHI) commands:

SilKit_ReturnCode SilKit_FlexrayController_ExecuteCmd(SilKit_FlexrayController *controller, SilKit_FlexrayChiCommand cmd)

Send the given FlexrayChiCommand.

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

SilKit_ReturnCode SilKit_FlexrayController_AddFrameHandler(SilKit_FlexrayController *controller, void *context, SilKit_FlexrayFrameHandler_t handler, SilKit_HandlerId *outHandlerId)

Receive a FlexRay message from the given controller.

Parameters

  • controller – The FlexRay 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.

SilKit_ReturnCode SilKit_FlexrayController_AddFrameTransmitHandler(SilKit_FlexrayController *controller, void *context, SilKit_FlexrayFrameTransmitHandler_t handler, SilKit_HandlerId *outHandlerId)

Notification that a FlexRay message has been successfully sent.

Parameters

  • controller – The FlexRay 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.

SilKit_ReturnCode SilKit_FlexrayController_AddWakeupHandler(SilKit_FlexrayController *controller, void *context, SilKit_FlexrayWakeupHandler_t handler, SilKit_HandlerId *outHandlerId)

Notification that a wakeup has been received.

Parameters

  • controller – The FlexRay 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.

SilKit_ReturnCode SilKit_FlexrayController_AddPocStatusHandler(SilKit_FlexrayController *controller, void *context, SilKit_FlexrayPocStatusHandler_t handler, SilKit_HandlerId *outHandlerId)

Notification that the POC status has changed.

Parameters

  • controller – The FlexRay 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.

SilKit_ReturnCode SilKit_FlexrayController_AddSymbolHandler(SilKit_FlexrayController *controller, void *context, SilKit_FlexraySymbolHandler_t handler, SilKit_HandlerId *outHandlerId)

Notification that the controller has received a symbol.

The symbols relevant for interaction trigger also an additional callback, e.g., SilKit_FlexrayWakeupHandler_t.

Parameters

  • controller – The FlexRay 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.

SilKit_ReturnCode SilKit_FlexrayController_AddSymbolTransmitHandler(SilKit_FlexrayController *controller, void *context, SilKit_FlexraySymbolTransmitHandler_t handler, SilKit_HandlerId *outHandlerId)

Notification that the controller has sent a symbol.

Currently, the following SymbolPatterns can occur:

  • Wakeup() will cause sending the FlexraySymbolPattern::Wus if the bus is idle.

  • Run() will cause the transmission of FlexraySymbolPattern::CasMts if configured to coldstart the bus.

Parameters

  • controller – The FlexRay 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.

SilKit_ReturnCode SilKit_FlexrayController_AddCycleStartHandler(SilKit_FlexrayController *controller, void *context, SilKit_FlexrayCycleStartHandler_t handler, SilKit_HandlerId *outHandlerId)

Notification that a new FlexRay cycle did start.

Parameters

  • controller – The FlexRay 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.

SilKit_ReturnCode SilKit_FlexrayController_RemoveFrameHandler(SilKit_FlexrayController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_FlexrayFrameHandler_t by SilKit_HandlerId on this controller.

Parameters

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

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

SilKit_ReturnCode SilKit_FlexrayController_RemoveFrameTransmitHandler(SilKit_FlexrayController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_FlexrayFrameTransmitHandler_t by SilKit_HandlerId on this controller.

Parameters

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

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

SilKit_ReturnCode SilKit_FlexrayController_RemoveWakeupHandler(SilKit_FlexrayController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_FlexrayWakeupHandler_t by SilKit_HandlerId on this controller.

Parameters

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

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

SilKit_ReturnCode SilKit_FlexrayController_RemovePocStatusHandler(SilKit_FlexrayController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_FlexrayPocStatusHandler_t by SilKit_HandlerId on this controller.

Parameters

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

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

SilKit_ReturnCode SilKit_FlexrayController_RemoveSymbolHandler(SilKit_FlexrayController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_FlexraySymbolHandler_t by SilKit_HandlerId on this controller.

Parameters

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

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

SilKit_ReturnCode SilKit_FlexrayController_RemoveSymbolTransmitHandler(SilKit_FlexrayController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_FlexraySymbolTransmitHandler_t by SilKit_HandlerId on this controller.

Parameters

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

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

SilKit_ReturnCode SilKit_FlexrayController_RemoveCycleStartHandler(SilKit_FlexrayController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_FlexrayCycleStartHandler_t by SilKit_HandlerId on this controller.

Parameters

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

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

Data Structures

struct SilKit_FlexrayClusterParameters

Protocol relevant global cluster parameters.

Cf. ‘FlexRay Protocol Specification Version 3.0.1’ Appendix B.3.1.1 Parameters.

Public Members

SilKit_StructHeader structHeader

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

uint8_t gColdstartAttempts

Number of attempts for a cold start before giving up (range 2-31).

uint8_t gCycleCountMax

Max cycle count value in a given cluster (range 7-63, must be an odd integer).

uint16_t gdActionPointOffset

Time offset for a static slot in MacroTicks (MT) (range 1-63).

uint16_t gdDynamicSlotIdlePhase

Duration of the idle phase within a dynamic slot in gdMiniSlots (range 0-2).

uint16_t gdMiniSlot

Duration of a mini slot in MacroTicks (MT) (2-63).

uint16_t gdMiniSlotActionPointOffset

Time offset for a mini slot in MacroTicks (MT) (range 1-31).

uint16_t gdStaticSlot

Duration of a static slot in MacroTicks (MT) (3-664).

uint16_t gdSymbolWindow

Duration of the symbol window in MacroTicks (MT) (range 0-162).

uint16_t gdSymbolWindowActionPointOffset

Time offset for a static symbol windows in MacroTicks (MT) (range 1-63).

uint16_t gdTSSTransmitter

Duration of TSS (Transmission Start Sequence) in gdBits (range 1-15).

uint16_t gdWakeupTxActive

Duration of LOW Phase of a wakeup symbol in gdBit (range 15-60).

uint16_t gdWakeupTxIdle

Duration of the idle of a wakeup symbol in gdBit (45-180).

uint8_t gListenNoise

Upper limit for the startup listen timeout and wakeup listen timeout in the presence of noise. Used as a multiplier of pdListenTimeout (range 2-16).

uint16_t gMacroPerCycle

Number of MacroTicks (MT) per cycle, (range 8-16000).

uint8_t gMaxWithoutClockCorrectionFatal

Threshold used for testing the vClockCorrectionFailed counter (range 1-15).

uint8_t gMaxWithoutClockCorrectionPassive

Threshold used for testing the vClockCorrectionFailed counter (range 1-15).

uint16_t gNumberOfMiniSlots

Number of mini slots (range 0-7988).

uint16_t gNumberOfStaticSlots

Number of static slots in a cycle (range 2-1023).

uint16_t gPayloadLengthStatic

Length of the payload of a static frame in 16-Bits words (range 0-127).

uint8_t gSyncFrameIDCountMax

Max number of distinct sync frame identifiers present in a given cluster. (range 2-15).

struct SilKit_FlexrayNodeParameters

Protocol relevant global node parameters.

Cf. ‘FlexRay Protocol Specification Version 3.0.1’ Appendix B.3.2 Parameters.

Public Members

SilKit_StructHeader structHeader

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

uint8_t pAllowHaltDueToClock

Controls the transition to halt state due to clock synchronization errors. (0,1).

uint8_t pAllowPassiveToActive

Required number of consecutive even / odd cycle pairs for normal passive to normal active (range 0-31).

SilKit_FlexrayChannel pChannels

Channel(s) to which the controller is connected (values FlexrayChannel::A, FlexrayChannel::B, FlexrayChannel::AB).

uint8_t pClusterDriftDamping

Cluster drift damping factor for rate correction in MicroTicks (range 0-10).

SilKit_FlexrayMicroTick pdAcceptedStartupRange

Allowed deviation for startup frames during integration in MicroTicks (range 29-2743).

SilKit_FlexrayMicroTick pdListenTimeout

Duration of listen phase in MicroTicks (range 1926-2567692).

uint16_t pKeySlotId

Slot ID of the key slot (range 0-1023, value 0 means that there is no key slot).

uint8_t pKeySlotOnlyEnabled

Shall the node enter key slot only mode after startup. (values 0, 1) (AUTOSAR pSingleSlotEnabled).

uint8_t pKeySlotUsedForStartup

Key slot is used for startup (range 0, 1).

uint8_t pKeySlotUsedForSync

Key slot is used for sync (range 0, 1).

uint16_t pLatestTx

Last mini slot which can be transmitted (range 0-7988).

uint8_t pMacroInitialOffsetA

Initial startup offset for frame reference point on channel A (rang 2-68 MacroTicks (MT)).

uint8_t pMacroInitialOffsetB

Initial startup offset for frame reference point on channel B (rang 2-68 MacroTicks (MT)).

SilKit_FlexrayMicroTick pMicroInitialOffsetA

Offset between secondary time reference and MT boundary (range 0-239 MicroTicks).

SilKit_FlexrayMicroTick pMicroInitialOffsetB

Offset between secondary time reference and MT boundary (range 0-239 MicroTicks).

SilKit_FlexrayMicroTick pMicroPerCycle

Nominal number of MicroTicks in the communication cycle (range 960-1280000).

SilKit_FlexrayMicroTick pOffsetCorrectionOut

Maximum permissible offset correction value (range 15-16082 MicroTicks).

uint16_t pOffsetCorrectionStart

Start of the offset correction phase within the NIT, (7-15999 MT).

SilKit_FlexrayMicroTick pRateCorrectionOut

Maximum permissible rate correction value (range 3-3846 MicroTicks).

SilKit_FlexrayChannel pWakeupChannel

Channel used by the node to send a wakeup pattern (values FlexrayChannel::A, FlexrayChannel::B).

uint8_t pWakeupPattern

Number of repetitions of the wakeup symbol (range 0-63, value 0 or 1 prevents sending of WUP).

SilKit_FlexrayClockPeriod pdMicrotick

Duration of a FlexRay MicroTick (12.5ns, 25ns or 50ns).

uint8_t pSamplesPerMicrotick

Number of samples per MicroTick (values 1 or 2).

struct SilKit_FlexrayTxBufferConfig

Configuration of Tx-Buffer, used in struct FlexrayControllerConfig.

Public Members

SilKit_StructHeader structHeader

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

SilKit_FlexrayChannel channels

(values FlexrayChannel::A, FlexrayChannel::B, FlexrayChannel::AB)

uint16_t slotId

The slot Id of frame.

uint8_t offset

Base offset for cycle multiplexing (values 0-63).

uint8_t repetition

Repetition for cycle multiplexing (values 1,2,4,8,16,32,64).

SilKit_Bool hasPayloadPreambleIndicator

Set the PPindicator.

uint16_t headerCrc

Header CRC, 11 bits.

SilKit_FlexrayTransmissionMode transmissionMode

FlexrayTransmissionMode::SingleShot or FlexrayTransmissionMode::Continuous.

struct SilKit_FlexrayControllerConfig

Configure the communication parameters of the FlexRay controller.

Public Members

SilKit_StructHeader structHeader

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

SilKit_FlexrayClusterParameters *clusterParams

FlexRay cluster parameters.

SilKit_FlexrayNodeParameters *nodeParams

FlexRay node parameters.

uint32_t numBufferConfigs

FlexRay buffer configs.

SilKit_FlexrayTxBufferConfig *bufferConfigs
struct SilKit_FlexrayTxBufferUpdate

Update the content of a FlexRay TX-Buffer.

Public Members

SilKit_StructHeader structHeader

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

uint16_t txBufferIndex

Index of the TX Buffers according to the configured buffers (cf. FlexrayControllerConfig).

SilKit_Bool payloadDataValid

Payload data valid flag.

SilKit_ByteVector payload

Raw payload containing 0 to 254 bytes.

struct SilKit_FlexrayHeader

Public Members

SilKit_StructHeader structHeader

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

uint8_t flags

Flags bit map according to FlagMask. Description:

  • [7-5]: unused

  • [4]: Reserved bit

  • [3]: PPIndicator: 0, regular payload; 1, NM vector or message ID

  • [2]: NFIndicator: 0, no valid payload data and PPIndicator = 0; 1, valid payload data

  • [1]: SyFIndicator: 0, frame not used for synchronization; 1, frame shall be used for sync

  • [0]: SuFIndicator: 0, not a startup frame; 1, a startup frame

uint16_t frameId
uint8_t payloadLength
uint16_t headerCrc
uint8_t cycleCount
struct SilKit_FlexrayFrame

Public Members

SilKit_StructHeader structHeader

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

SilKit_FlexrayHeader *header

Header flags, slot, crc, and cycle indidcators.

SilKit_ByteVector payload
struct SilKit_FlexrayFrameEvent

Public Members

SilKit_StructHeader structHeader

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

SilKit_NanosecondsTime timestamp

Time at end of frame transmission.

SilKit_FlexrayChannel channel

FlexRay channel A or B. (Valid values: FlexrayChannel::A, FlexrayChannel::B).

SilKit_FlexrayFrame *frame

Received FlexRay frame.

struct SilKit_FlexrayFrameTransmitEvent

Acknowledge for the transmit on the FlexRay bus.

Public Members

SilKit_StructHeader structHeader

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

SilKit_NanosecondsTime timestamp

Time at end of frame transmission.

uint16_t txBufferIndex

Tx buffer, that was used for the transmission.

SilKit_FlexrayChannel channel

FlexRay channel A or B. (Valid values: FlexrayChannel::A, FlexrayChannel::B).

SilKit_FlexrayFrame *frame

Copy of the FlexRay frame that was successfully transmitted.

struct SilKit_FlexraySymbolEvent

A FlexRay Symbol as received on the FlexRay bus.

Public Members

SilKit_StructHeader structHeader

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

SilKit_NanosecondsTime timestamp

End time of symbol reception.

SilKit_FlexrayChannel channel

FlexRay channel A or B (values: FlexrayChannel::A, FlexrayChannel::B).

SilKit_FlexraySymbolPattern pattern

The received symbol, e.g. wakeup pattern.

struct SilKit_FlexrayCycleStartEvent

Indicate the start of a FlexRay cycle.

Public Members

SilKit_StructHeader structHeader

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

SilKit_NanosecondsTime timestamp

Cycle starting time.

uint8_t cycleCounter

Counter of FlexRay cycles.

struct SilKit_FlexrayPocStatusEvent

Protocol Operation Control status as available in the AUTOSAR FlexRay driver model.

This enhances the deprecated struct ControllerStatus by adding members that are available through the Controller Host Interface. AUTOSAR Name: Fr_POCStatusType

Public Members

SilKit_StructHeader structHeader

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

SilKit_NanosecondsTime timestamp

SIL Kit timestamp.

SilKit_FlexrayPocState state
SilKit_Bool chiHaltRequest

< Status of the Protocol Operation Control (POC).

SilKit_Bool coldstartNoise

< indicates whether a halt request was received from the CHI

SilKit_Bool freeze

< indicates noisy channel conditions during coldstart

SilKit_Bool chiReadyRequest

< indicates that the POC entered a halt state due to an error condition requiring immediate halt.

SilKit_FlexrayErrorModeType errorMode

< indicates that the CHI requested to enter ready state at the end of the communication cycle.

SilKit_FlexraySlotModeType slotMode

< indicates the error mode of the POC

SilKit_FlexrayStartupStateType startupState

< indicates the slot mode of the POC

SilKit_FlexrayWakeupStatusType wakeupStatus

< indicates states within the STARTUP mechanism

Enumerations and Typedefs

typedef int32_t SilKit_FlexrayMacroTick

FlexRay macro tick.

typedef int32_t SilKit_FlexrayMicroTick

FlexRay micro tick.

typedef uint32_t SilKit_FlexrayClockPeriod

Period of the clock (used for micro tick period and sample clock period).

12.5ns / 80MHz

typedef uint32_t SilKit_FlexrayChannel

Type and constants for the FlexRay channel parameter A, B, or AB.

typedef uint8_t SilKit_FlexraySymbolPattern

FlexRay symbols patterns.

typedef uint8_t SilKit_FlexrayChiCommand

FlexRay controller commands.

typedef uint8_t SilKit_FlexrayTransmissionMode

Transmission mode for FlexRay Tx-Buffer.

typedef uint8_t SilKit_FlexrayPocState

Protocol Operation Control (POC) state of the FlexRay communication controller AUTOSAR Name: Fr_POCStateType.

typedef uint8_t SilKit_FlexraySlotModeType

Indicates what slot mode the POC is in. AUTOSAR Name: Fr_SlotModeType.

typedef uint8_t SilKit_FlexrayErrorModeType

Indicates what error mode the POC is in. AUTOSAR Name: Fr_ErrorModeType.

typedef uint8_t SilKit_FlexrayStartupStateType

Indicates the current substate in the startup procedure. AUTOSAR Name: Fr_StartupStateType.

typedef uint8_t SilKit_FlexrayWakeupStatusType

Indicates the outcome of the wake-up mechanism. AUTOSAR Name: Fr_WakeupStateType.

typedef uint8_t SilKit_FlexrayHeader_Flag
typedef struct SilKit_FlexraySymbolEvent SilKit_FlexraySymbolTransmitEvent