Detailed Description

The purpose of the Network Redundancy Layer (NRL) is the duplication of CAN frames between the application and the CAN interfaces for transmission, as well as the de-duplication of CAN frames between the CAN interfaces and the application for reception. As such, the CAN traffic on both CAN lines is intended to be identical.

The NRL functions provide an additional layer between an existing CANpie FD driver that supports at least two physical CAN interfaces and an application using the API (e.g. CANopen or J1939). From the application point of view no changes of the existing CANpie FD API have to be considered.

The NRL is initialized with the function CpNrlRegisterDriver(). This function will setup the internal driver structure, but not initialise the CAN controller, configure a certain bit-rate nor switch the CAN controller to active operation. The following core functions must be called in that order:

//----------------------------------------------------------------------------------------------
// Register driver on logical NRL channel 1:
// CAN interface 1 is DCL, CAN interface 2 is RCL
//
CpNrlRegisterDriver(eCP_NRL_CHANNEL_1, eCP_CHANNEL_1, eCP_CHANNEL_2, &tsNrlDriverS);
 
//----------------------------------------------------------------------------------------------
// Register event handler between NRL and application
//
CpNrlRegisterHandler(eCP_NRL_CHANNEL_1, MyStateChangeHandler);
 
//----------------------------------------------------------------------------------------------
// Configure deviation limit 4
//
CpNrlSetDeviationLimit(eCP_NRL_CHANNEL_1, 4);
 
//----------------------------------------------------------------------------------------------
// Configure mailbox timeout to 10 ms
//
CpNrlSetTimeout(eCP_NRL_CHANNEL_1, 10000);

The NRL configuration options allow to change options during compilation of the NRL.

Interface between NRL and CANpie FD driver

The following diagram gives an overview to functions used for providing a defined interface between the NRL and a CANpie FD driver.

Interface to CANpie FD driver

Using the NRL in non-redundant mode

The NRL can be started in non-redundant mode, i.e. only one CAN interface is used for communication. This mode allows the application to disable the functionality of the NRL during run-time. In non-redundant mode the NRL is a transparent layer between the CANpie FD driver and the application. The non-redundant mode is started by passing a value of eCP_CHANNEL_NONE for the physical interface of Redundant CAN Line upon registration.

//----------------------------------------------------------------------------------------------
// Register driver on logical NRL channel 1, but in non-redundant mode
// CAN interface 1 is used for application
//
CpNrlRegisterDriver(eCP_NRL_CHANNEL_1, eCP_CHANNEL_1, eCP_CHANNEL_NONE, &tsNrlDriverS);

Include dependency graph for cp_nrl.h:

Data Structures
struct	CpNrlDriver_s

struct	CpNrlState_s

struct	CpNrlCoreData_s

Macros
#define	CP_NRL_TIMER_PERIOD 1000

#define	CP_NRL_SUPPORT 0

#define	CP_NRL_FAULT_SIMULATION 0

#define	CP_NRL_VERSION_MAJOR 1

#define	CP_NRL_VERSION_MINOR 17

#define	CP_NRL_VERSION_BUILD 0

#define	CP_NRL_DEVIATION_LIMIT_MAX 10

Typedefs
typedef void(*	CpNrlStateHandler_Fn) (uint8_t ubNrlStateV)

Enumerations
enum	CpNrlChannel_e { eCP_NRL_CHANNEL_NONE = 0 , eCP_NRL_CHANNEL_1 = 1 , eCP_NRL_CHANNEL_2 = 2 , eCP_NRL_CHANNEL_LIMIT = eCP_NRL_CHANNEL_NONE }

enum	CpNrlFault_e { eCP_NRL_FAULT_NONE = 0 , eCP_NRL_FAULT_DISCONNECT_DCL , eCP_NRL_FAULT_DISCONNECT_RCL , eCP_NRL_FAULT_DISCONNECT_ALL }

enum	CpNrlLine_e { eCP_NRL_LINE_DCL = 0 , eCP_NRL_LINE_RCL = 1 , eCP_NRL_LINE_NONE = 2 }

enum	CpNrlState_e { eCP_NRL_STATE_INIT = 0 , eCP_NRL_STATE_ACTIVE = 1 , eCP_NRL_STATE_PASSIVE = 2 , eCP_NRL_STATE_DISABLED = 3 , eCP_NRL_STATE_DISCONNECTED = 4 , eCP_NRL_STATE_NON_REDUNDANT = 5 }

Functions
int16_t	CpNrlMboxCounter (uint8_t ubNrlChannelV, uint8_t ubBufferIdxV)

bool_t	CpNrlMboxCounterEvent (uint8_t ubPhyIfV, uint8_t ubBufferIdxV)

bool_t	CpNrlMboxFlush (CpPort_ts *ptsPortV)

void	CpNrlMboxTickEvent (void)

bool_t	CpNrlMboxTickLoad (uint8_t ubPhyIfV, uint8_t ubBufferIdxV)

CpNrlCoreData_ts *	CpNrlCoreData (uint8_t ubPhyIfV)

CpStatus_tv	CpNrlRegisterDriver (uint8_t ubNrlChannelV, uint8_t ubPhyIfDclV, uint8_t ubPhyIfRclV, CpNrlDriver_ts *ptsNrlDriverV)

CpStatus_tv	CpNrlRegisterHandler (uint8_t ubNrlChannelV, CpNrlStateHandler_Fn pfnStateHandlerV)

CpStatus_tv	CpNrlRegisterConnectionService (uint8_t ubNrlChannelV, uint32_t ulIdentifierV, uint8_t ubFormatV)

CpStatus_tv	CpNrlSendConnectionService (uint8_t ubNrlChannelV)

CpStatus_tv	CpNrlSetDeviationLimit (uint8_t ubNrlChannelV, uint8_t ubLimitV)

CpStatus_tv	CpNrlSetRecoveryTime (uint8_t ubNrlChannelV, uint32_t ulMicroSecondsV)

CpStatus_tv	CpNrlSetTimeout (uint8_t ubNrlChannelV, uint32_t ulMicroSecondsV)

CpStatus_tv	CpNrlState (uint8_t ubNrlChannelV, CpNrlState_ts *ptsStateV)

void	CpNrlTimerEvent (uint8_t ubNrlChannelV)

Variables
CpNrlDriver_ts	tsNrlDriverG

Macro Definition Documentation

◆ CP_NRL_DEVIATION_LIMIT_MAX

#define CP_NRL_DEVIATION_LIMIT_MAX 10

This symbol defines the maximum value which can be used for the deviation limit (refer to CpNrlSetDeviationLimit).

Typedef Documentation

◆ CpNrlStateHandler_Fn

typedef void(* CpNrlStateHandler_Fn) (uint8_t ubNrlStateV)

Handler for NRL state machine change event.

Parameters

[in] ubNrlStateV Current state of NRL

Enumeration Type Documentation

◆ CpNrlChannel_e

enum CpNrlChannel_e

NRL channel definitions.

A CAN device can have up to two logical NRL channel, each having two physical CAN interfaces. In default configuration (CP_NRL_CHANNEL_MAX = 0) the value of eCP_NRL_CHANNEL_LIMIT is set to eCP_NRL_CHANNEL_NONE, otherwise it is set to the appropriate enumeration value.

Enumerator
eCP_NRL_CHANNEL_NONE	NRL channel invalid
eCP_NRL_CHANNEL_1	NRL channel 1
eCP_NRL_CHANNEL_2	NRL channel 2
eCP_NRL_CHANNEL_LIMIT	NRL channel limit, marks the end of the enumeration

◆ CpNrlFault_e

enum CpNrlFault_e

NRL fault simulation definitions.

The values of the enumeration CpNrlFault_e are used to simulate fault conditions using the function CpNrlFaultSimulation().

The NRL fault simulation is only available if the symbol CP_NRL_FAULT_SIMULATION is set to 1.

Enumerator
eCP_NRL_FAULT_NONE	No fault
eCP_NRL_FAULT_DISCONNECT_DCL	Fault on DCL
eCP_NRL_FAULT_DISCONNECT_RCL	Fault on RCL
eCP_NRL_FAULT_DISCONNECT_ALL	Fault on both lines

◆ CpNrlLine_e

enum CpNrlLine_e

CAN line definitions.

The values of the enumeration CpNrlLine_e are used to define the active CAN line.

Enumerator
eCP_NRL_LINE_DCL	Default CAN line
eCP_NRL_LINE_RCL	Redundant CAN line
eCP_NRL_LINE_NONE	No CAN line active (e.g. bus-off)

◆ CpNrlState_e

enum CpNrlState_e

NRL state definitions.

The values of the enumeration CpNrlState_e are used to define the active NRL state.

Enumerator
eCP_NRL_STATE_INIT	NRL is in Initialization state
eCP_NRL_STATE_ACTIVE	NRL is in Redundancy active state
eCP_NRL_STATE_PASSIVE	NRL is in Redundancy passive state
eCP_NRL_STATE_DISABLED	NRL is in Redundancy disabled state
eCP_NRL_STATE_DISCONNECTED	NRL is is disconnected from CAN
eCP_NRL_STATE_NON_REDUNDANT	NRL is used in non-redundant mode

Function Documentation

◆ CpNrlCoreData()

CpNrlCoreData_ts * CpNrlCoreData ( uint8_t ubPhyIfV )

Parameters

[in] ubPhyIfV Physical interface

Returns: Pointer to CpNrlCoreData_ts structure

The function returns a pointer to the CpNrlCoreData_ts structure for the physical CAN interface defined by ubPhyIfV.

The function is required by the CANpie FD driver and shall not be used by the Higher Layer Protocol.

◆ CpNrlMboxCounter()

int16_t CpNrlMboxCounter	(	uint8_t	ubNrlChannelV,
		uint8_t	ubBufferIdxV
	)

Parameters

[in]	ubNrlChannelV	Channel of Network Redundancy Layer
[in]	ubBufferIdxV	Buffer number

Returns: Mailbox counter value

The function returns the current mailbox counter value of the mailbox number defined by the value of ubBufferIdxV. In case the parameter ubNrlChannelV or ubBufferIdxV are out of range the function will return CP_NRL_MAILBOX_COUNTER_UPPER_LIMIT + 1.

◆ CpNrlMboxCounterEvent()

bool_t CpNrlMboxCounterEvent	(	uint8_t	ubPhyIfV,
		uint8_t	ubBufferIdxV
	)

Parameters

[in]	ubPhyIfV	Physical interface
[in]	ubBufferIdxV	Buffer number

Returns: true if event was processed

The function processes a counter event for the physical CAN interface defined by ubPhyIfV and the mailbox number defined by ubBufferIdxV. If the physical interface is assigned to the DCL the counter variable is incremented. If the physical interface is assigned to the RCL the counter variable is decremented.

The function is implemented inside the CANpie FD driver and shall not be used by the Higher Layer Protocol.

◆ CpNrlMboxFlush()

bool_t CpNrlMboxFlush ( CpPort_ts * ptsPortV )

Parameters

[in] ptsPortV Pointer to CAN port structure

Returns: true if mailboxes are flushed

The function flushes the receive mailboxes of the Active CAN Line (ACL) after a Fault Detection event occurred. The value for the parameter ptsPortV defines which CAN port has to be flushed.

The function is implemented inside the CANpie FD driver and shall not be used by the Higher Layer Protocol.

◆ CpNrlMboxTickEvent()

void CpNrlMboxTickEvent ( void )

The function is called inside CpNrlTimerEvent() within the defined cycle period of CP_NRL_TIMER_PERIOD. Inside the CANpie FD driver the function is responsible to decrement the timer ticks associated to each mailbox.

The function is implemented inside the CANpie FD driver and shall not be used by the Higher Layer Protocol.

◆ CpNrlMboxTickLoad()

bool_t CpNrlMboxTickLoad	(	uint8_t	ubPhyIfV,
		uint8_t	ubBufferIdxV
	)

Parameters

[in]	ubPhyIfV	Physical interface
[in]	ubBufferIdxV	Buffer number

Returns: true if timer tick was reloaded

The function reloads the timer ticks calculated by CpNrlSetTimeout() for the physical CAN interface defined by ubPhyIfV and the mailbox number defined by ubBufferIdxV. The timer ticks for each individual CAN interface and mailbox are decremented to 0 by CpNrlMboxTickEvent using a timer tick value of CP_NRL_TIMER_PERIOD.

The function is implemented inside the CANpie FD driver and shall not be used by the Higher Layer Protocol.

◆ CpNrlRegisterConnectionService()

CpStatus_tv CpNrlRegisterConnectionService	(	uint8_t	ubNrlChannelV,
		uint32_t	ulIdentifierV,
		uint8_t	ubFormatV
	)

Parameters

[in]	ubNrlChannelV	Channel of Network Redundancy Layer
[in]	ulIdentifierV	Identifier value
[in]	ubFormatV	Message format

Returns: Error code defined by the CpErr_e enumeration. If no error occurred, the function will return the value eCP_ERR_NONE.

The function configures the NRL connection service for the the Network Redundancy Layer defined by ubNrlChannelV. The CAN-ID of the DCL is defined by parameter ulIdentifierV, which must be an even value. The CAN-ID of the RCL is set to a value of ulIdentifierV + 1.

◆ CpNrlRegisterDriver()

CpStatus_tv CpNrlRegisterDriver	(	uint8_t	ubNrlChannelV,
		uint8_t	ubPhyIfDclV,
		uint8_t	ubPhyIfRclV,
		CpNrlDriver_ts *	ptsNrlDriverV
	)

Parameters

[in]	ubNrlChannelV	Channel of Network Redundancy Layer
[in]	ubPhyIfDclV	Physical interface of Default CAN Line
[in]	ubPhyIfRclV	Physical interface of Redundant CAN Line
[in]	ptsNrlDriverV	Pointer to NRL driver structure

Returns: Error code defined by the CpErr_e enumeration. If no error occurred, the function will return the value eCP_ERR_NONE.

The function registers the CANpie driver to the Network Redundancy Layer. It is assigned to the channel defined by ubNrlChannelV, the parameters ubPhyIfDclV and ubPhyIfRclV are used to assign the physical CAN interfaces of the driver to the Default CAN Line (DLC) and Redundant CAN Line (RCL).

The function requires that the CAN channels are not already assigned by another application. The CAN channels must not be equal. In addition, all functions of the CpNrlDriver_ts structure have to be assigned.

◆ CpNrlRegisterHandler()

CpStatus_tv CpNrlRegisterHandler	(	uint8_t	ubNrlChannelV,
		CpNrlStateHandler_Fn	pfnStateHandlerV
	)

Parameters

[in]	ubNrlChannelV	Channel of Network Redundancy Layer
[in]	pfnStateHandlerV	Pointer to callback function

Returns: Error code defined by the CpErr_e enumeration. If no error occurred, the function will return the value eCP_ERR_NONE.

This function will install a callback routine inside the NRL processing for the specified channel ubNrlChannelV. The handler is released by setting pfnStateHandlerV to NULL. A registered handler function is called upon state change of the NRL.

◆ CpNrlSendConnectionService()

CpStatus_tv CpNrlSendConnectionService ( uint8_t ubNrlChannelV )

Parameters

[in] ubNrlChannelV Channel of Network Redundancy Layer

Returns: Error code defined by the CpErr_e enumeration. If no error occurred, the function will return the value eCP_ERR_NONE.

This function triggers the transmission of the NRL connection service. The purpose of the function is verification of the CAN connection schema (DCL/RCL). Since the NRL connection service can modify the NRL state machine it shall be used sparingly.

◆ CpNrlSetDeviationLimit()

CpStatus_tv CpNrlSetDeviationLimit	(	uint8_t	ubNrlChannelV,
		uint8_t	ubLimitV
	)

Parameters

[in]	ubNrlChannelV	Channel of Network Redundancy Layer
[in]	ubLimitV	Counter deviation limit value

Returns: Error code defined by the CpErr_e enumeration. If no error occurred, the function will return the value eCP_ERR_NONE.

This function configures the deviation limit value of the Network Redundancy Layer defined by ubNrlChannelV.

◆ CpNrlSetRecoveryTime()

CpStatus_tv CpNrlSetRecoveryTime	(	uint8_t	ubNrlChannelV,
		uint32_t	ulMicroSecondsV
	)

Parameters

[in]	ubNrlChannelV	Channel of Network Redundancy Layer
[in]	ulMicroSecondsV	Timeout value in microseconds

Returns: Error code defined by the CpErr_e enumeration. If no error occurred, the function will return the value eCP_ERR_NONE.

This function configures the recovery timeout value for the specified channel ubNrlChannelV. The value ulMicroSecondsV is given in multiples of 1 micro-second.

◆ CpNrlSetTimeout()

CpStatus_tv CpNrlSetTimeout	(	uint8_t	ubNrlChannelV,
		uint32_t	ulMicroSecondsV
	)

Parameters

[in]	ubNrlChannelV	Channel of Network Redundancy Layer
[in]	ulMicroSecondsV	Timeout value in microseconds

Returns: Error code defined by the CpErr_e enumeration. If no error occurred, the function will return the value eCP_ERR_NONE.

This function configures the mailbox timeout value for the specified channel ubNrlChannelV. The value ulMicroSecondsV is given in multiples of 1 micro-second.

◆ CpNrlState()

CpStatus_tv CpNrlState	(	uint8_t	ubNrlChannelV,
		CpNrlState_ts *	ptsStateV
	)

Parameters

[in]	ubNrlChannelV	Channel of Network Redundancy Layer
[in]	ptsStateV	Pointer to NRL state structure

Returns: Error code defined by the CpErr_e enumeration. If no error occurred, the function will return the value eCP_ERR_NONE.

This function retrieves the present state of the NRL channel defined by ubNrlChannelV. The parameter ptsStateV is a pointer to a memory location where the function will store the state.

◆ CpNrlTimerEvent()

void CpNrlTimerEvent ( uint8_t ubNrlChannelV )

Parameters

[in] ubNrlChannelV Channel of Network Redundancy Layer

This function must be called cyclically by a timer resource of the target system. It is responsible to execute the internal NRL process for the channel defined by ubNrlChannelV. The cycle time is defined in microseconds by the symbol CP_NRL_TIMER_PERIOD.

Variable Documentation

◆ tsNrlDriverG

tsNrlDriverG

extern

The global structure for CANpie FD driver registration is typically defined inside the specific CANpie FD driver implementation. The variable can be used inside the application during initialisation if no other approach is used.

CosNrlInit(eCP_NRL_CHANNEL_1, eCP_CHANNEL_1, eCP_CHANNEL_2, &tsNrlDriverG);

CosNrlInit

Status_tv CosNrlInit(uint8_t ubNrlChannelV, uint8_t ubPhyIfDclV, uint8_t ubPhyIfRclV, CpNrlDriver_ts *ptsNrlDriverV)

tsNrlDriverG

CpNrlDriver_ts tsNrlDriverG

Detailed Description

Interface between NRL and CANpie FD driver

Using the NRL in non-redundant mode

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

◆ CP_NRL_DEVIATION_LIMIT_MAX

Typedef Documentation

◆ CpNrlStateHandler_Fn

Enumeration Type Documentation

◆ CpNrlChannel_e

◆ CpNrlFault_e

◆ CpNrlLine_e

◆ CpNrlState_e

Function Documentation

◆ CpNrlCoreData()

◆ CpNrlMboxCounter()

◆ CpNrlMboxCounterEvent()

◆ CpNrlMboxFlush()

◆ CpNrlMboxTickEvent()

◆ CpNrlMboxTickLoad()

◆ CpNrlRegisterConnectionService()

◆ CpNrlRegisterDriver()

◆ CpNrlRegisterHandler()

◆ CpNrlSendConnectionService()

◆ CpNrlSetDeviationLimit()

◆ CpNrlSetRecoveryTime()

◆ CpNrlSetTimeout()

◆ CpNrlState()

◆ CpNrlTimerEvent()

Variable Documentation

◆ tsNrlDriverG