CANpie FD
CAN programming interface environment - Version 3.08
|
The core functions provide the direct interface to the CAN controller (hardware). Please note that due to hardware limitations maybe certain functions are not implemented on the target platform. A call to an unsupported function will always return the error code eCP_ERR_NOT_SUPPORTED.
For a "FullCAN" controller (i.e. a CAN controller that has several message buffers) an extended set of powerful functions (CpCoreBuffer..())is provided.
The CAN driver is initialised with the function CpCoreDriverInit(). This routine will setup the CAN controller, but not configure a certain bitrate nor switch the CAN controller to active operation. The following core functions must be called in that order:
The function CpCoreDriverInit() must be called before any other core function in order to have a valid handle / pointer to the open CAN interface.
Example
Functions | |
CpStatus_tv | CpCoreBitrate (CpPort_ts *ptsPortV, int32_t slNomBitRateV, int32_t slDatBitRateV) |
CpStatus_tv | CpCoreBufferConfig (CpPort_ts *ptsPortV, uint8_t ubBufferIdxV, uint32_t ulIdentifierV, uint32_t ulAcceptMaskV, uint8_t ubFormatV, uint8_t ubDirectionV) |
CpStatus_tv | CpCoreBufferGetData (CpPort_ts *ptsPortV, uint8_t ubBufferIdxV, uint8_t *pubDestDataV, uint8_t ubStartPosV, uint8_t ubSizeV) |
CpStatus_tv | CpCoreBufferGetDlc (CpPort_ts *ptsPortV, uint8_t ubBufferIdxV, uint8_t *pubDlcV) |
CpStatus_tv | CpCoreBufferRelease (CpPort_ts *ptsPortV, uint8_t ubBufferIdxV) |
CpStatus_tv | CpCoreBufferSend (CpPort_ts *ptsPortV, uint8_t ubBufferIdxV) |
CpStatus_tv | CpCoreBufferSetData (CpPort_ts *ptsPortV, uint8_t ubBufferIdxV, uint8_t *pubSrcDataV, uint8_t ubStartPosV, uint8_t ubSizeV) |
CpStatus_tv | CpCoreBufferSetDlc (CpPort_ts *ptsPortV, uint8_t ubBufferIdxV, uint8_t ubDlcV) |
CpStatus_tv | CpCoreCanMode (CpPort_ts *ptsPortV, uint8_t ubModeV) |
CpStatus_tv | CpCoreCanState (CpPort_ts *ptsPortV, CpState_ts *ptsStateV) |
CpStatus_tv | CpCoreDriverInit (uint8_t ubPhyIfV, CpPort_ts *ptsPortV, uint8_t ubConfigV) |
CpStatus_tv | CpCoreDriverRelease (CpPort_ts *ptsPortV) |
CpStatus_tv | CpCoreFifoConfig (CpPort_ts *ptsPortV, uint8_t ubBufferIdxV, CpFifo_ts *ptsFifoV) |
CpStatus_tv | CpCoreFifoRead (CpPort_ts *ptsPortV, uint8_t ubBufferIdxV, CpCanMsg_ts *ptsCanMsgV, uint32_t *pulMsgCntV) |
CpStatus_tv | CpCoreFifoRelease (CpPort_ts *ptsPortV, uint8_t ubBufferIdxV) |
CpStatus_tv | CpCoreFifoWrite (CpPort_ts *ptsPortV, uint8_t ubBufferIdxV, CpCanMsg_ts *ptsCanMsgV, uint32_t *pulMsgCntV) |
CpStatus_tv | CpCoreHDI (CpPort_ts *ptsPortV, CpHdi_ts *ptsHdiV) |
CpStatus_tv | CpCoreIntFunctions (CpPort_ts *ptsPortV, CpRcvHandler_Fn pfnRcvHandlerV, CpTrmHandler_Fn pfnTrmHandlerV, CpErrHandler_Fn pfnErrHandlerV) |
CpStatus_tv | CpCoreStatistic (CpPort_ts *ptsPortV, CpStatistic_ts *ptsStatsV) |
CpStatus_tv CpCoreBitrate | ( | CpPort_ts * | ptsPortV, |
int32_t | slNomBitRateV, | ||
int32_t | slDatBitRateV | ||
) |
Set bit-rate of CAN controller.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | slNomBitRateV | Nominal Bit Timing selection |
[in] | slDatBitRateV | Data Bit Timing selection |
eCP_ERR_NONE
.This function initializes the bit timing registers of a CAN controller to pre-defined values. The values are defined by the enumeration CpBitrate_e. For a classical CAN controller (or if bit-rate switching is not required) the parameter slDatBitRateV
is set to eCP_BITRATE_NONE.
CpStatus_tv CpCoreBufferConfig | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubBufferIdxV, | ||
uint32_t | ulIdentifierV, | ||
uint32_t | ulAcceptMaskV, | ||
uint8_t | ubFormatV, | ||
uint8_t | ubDirectionV | ||
) |
Initialise message buffer.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubBufferIdxV | Buffer number |
[in] | ulIdentifierV | Identifier value |
[in] | ulAcceptMaskV | Acceptance mask value |
[in] | ubFormatV | Message format |
[in] | ubDirectionV | Message direction |
eCP_ERR_NONE
.This function allocates a message buffer in a CAN controller. The number of the message buffer inside the CAN controller is denoted via the parameter ubBufferIdxV
. The first buffer starts at position eCP_BUFFER_1. The message buffer is allocated with the identifier value ulIdentifierV
. If the buffer is used for reception (parameter ubDirectionV
is eCP_BUFFER_DIR_RCV), the parameter ulAcceptMaskV
is used for acceptance filtering.
The parameter ubFormatV
can have the following values:
The following example shows the setup of a transmit buffer
An allocated transmit buffer can be sent via the function CpCoreBufferSend().
The function initialises the DLC value of a message buffer to 0, a subsequent call of CpCoreBufferSetDlc() is necessary to change the default value.
CpStatus_tv CpCoreBufferGetData | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubBufferIdxV, | ||
uint8_t * | pubDestDataV, | ||
uint8_t | ubStartPosV, | ||
uint8_t | ubSizeV | ||
) |
Get data from message buffer.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubBufferIdxV | Buffer number |
[out] | pubDestDataV | Pointer to destination data buffer |
[in] | ubStartPosV | Array start position |
[in] | ubSizeV | Number of bytes to read |
eCP_ERR_NONE
.The functions copies ubSizeV
data bytes from the CAN message buffer defined by ubBufferIdxV
. The first message buffer starts at the index eCP_BUFFER_1. The parameter ubStartPosV
denotes the start position, the first data byte is at position 0. The destination buffer (pointer pubDestDataV
) must have sufficient space for the data. The buffer has to be configured by CpCoreBufferConfig() in advance.
CpStatus_tv CpCoreBufferGetDlc | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubBufferIdxV, | ||
uint8_t * | pubDlcV | ||
) |
Get DLC of specified buffer.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubBufferIdxV | Buffer number |
[out] | pubDlcV | Data Length Code |
eCP_ERR_NONE
.This function retrieves the Data Length Code (DLC) of the selected buffer ubBufferIdxV
. The first message buffer starts at the index eCP_BUFFER_1. The parameter pubDlcV
is a pointer to a memory location where the function will store the DLC value on success. The buffer has to be configured by CpCoreBufferConfig() in advance.
CpStatus_tv CpCoreBufferRelease | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubBufferIdxV | ||
) |
Release message buffer.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubBufferIdxV | Buffer number |
eCP_ERR_NONE
.The function releases the allocated message buffer specified by the parameter ubBufferIdxV
. The first message buffer starts at the index eCP_BUFFER_1. Both - reception and transmission - will be disabled on the specified message buffer afterwards.
CpStatus_tv CpCoreBufferSend | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubBufferIdxV | ||
) |
Send message from message buffer.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubBufferIdxV | Index of message buffer |
eCP_ERR_NONE
.This function transmits a message from the specified message buffer ubBufferIdxV
. The first message buffer starts at the index eCP_BUFFER_1. The message buffer has to be configured as transmit buffer (eCP_BUFFER_DIR_TRM) by a call to CpCoreBufferConfig() in advance. A transmission request on a receive buffer will fail with the return code eCP_ERR_INIT_FAIL.
CpStatus_tv CpCoreBufferSetData | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubBufferIdxV, | ||
uint8_t * | pubSrcDataV, | ||
uint8_t | ubStartPosV, | ||
uint8_t | ubSizeV | ||
) |
Set data of message buffer.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubBufferIdxV | Buffer number |
[in] | pubSrcDataV | Pointer to source data buffer |
[in] | ubStartPosV | Array start position |
[in] | ubSizeV | Number of bytes to write |
eCP_ERR_NONE
.This function copies ubSizeV
data bytes from the source buffer (pointer pubSrcDataV) into the message buffer defined by the parameter ubBufferIdxV
. The first message buffer starts at the index eCP_BUFFER_1. The parameter ubStartPosV
denotes the start position, the first data byte is at position 0. The message buffer has to be configured by CpCoreBufferConfig() in advance.
The following example demonstrates the access to the data bytes of a CAN message:
CpStatus_tv CpCoreBufferSetDlc | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubBufferIdxV, | ||
uint8_t | ubDlcV | ||
) |
Set DLC of specified buffer.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubBufferIdxV | Buffer number |
[in] | ubDlcV | Data Length Code |
eCP_ERR_NONE
.This function sets the Data Length Code (DLC) of the specified message buffer ubBufferIdxV
. The DLC value ubDlcV
must be in the range from 0 to 8 for Classical CAN frames and 0 to 15 for ISO CAN FD frames. An invalid DLC value is rejected with the return value eCP_ERR_CAN_DLC. The message buffer has to be configured by a call to CpCoreBufferConfig() in advance.
CpStatus_tv CpCoreCanMode | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubModeV | ||
) |
Set state of CAN controller.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubModeV | Mode selection |
eCP_ERR_NONE
.This function changes the operating mode of the CAN controller FSA. Possible values for the parameter ubModeV
are defined in the CpMode_e enumeration. At least the modes eCP_MODE_INIT and eCP_MODE_OPERATION shall be supported. Other modes depend on the capabilities of the CAN controller.
CpStatus_tv CpCoreCanState | ( | CpPort_ts * | ptsPortV, |
CpState_ts * | ptsStateV | ||
) |
Retrieve state of CAN controller.
[in] | ptsPortV | Pointer to CAN port structure |
[out] | ptsStateV | Pointer to CAN state structure |
eCP_ERR_NONE
.This function retrieves the present state of the CAN controller. The parameter ptsStateV
is a pointer to a memory location where the function will store the state. The value of the structure element CpState_ts::ubCanErrState is defined by the CpState_e enumeration. The value of the structure element CpState_ts::ubCanErrType is defined by the CpErrType_e enumeration.
CpStatus_tv CpCoreDriverInit | ( | uint8_t | ubPhyIfV, |
CpPort_ts * | ptsPortV, | ||
uint8_t | ubConfigV | ||
) |
Initialise the CAN driver.
[in] | ubPhyIfV | CAN channel of the hardware |
[out] | ptsPortV | Pointer to CAN port structure |
[in] | ubConfigV | This parameter is reserved for future enhancement |
eCP_ERR_NONE
.The functions opens the physical CAN interface defined by the parameter ubPhyIfV
. The value for ubPhyIfV
is taken from the enumeration CpChannel_e. The function sets up the field members of the CAN port structure CpPort_ts. The parameter ptsPortV
is a pointer to a memory location where structure CpPort_ts is stored. An opened CAN port must be closed via the CpCoreDriverRelease() function.
CpStatus_tv CpCoreDriverRelease | ( | CpPort_ts * | ptsPortV | ) |
Release the CAN driver.
[in] | ptsPortV | Pointer to CAN port structure |
eCP_ERR_NONE
.The function closes a CAN port. The parameter ptsPortV
is a pointer to a memory location where structure CpPort_ts is stored. The implementation of this function is dependent on the operating system. Typical tasks might be:
CpStatus_tv CpCoreFifoConfig | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubBufferIdxV, | ||
CpFifo_ts * | ptsFifoV | ||
) |
Assign FIFO to message buffer.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubBufferIdxV | Buffer number |
[in] | ptsFifoV | Pointer to FIFO structure |
eCP_ERR_NONE
.This function assigns a FIFO to a message buffer defined by the parameter ubBufferIdxV
. The first message buffer starts at the index eCP_BUFFER_1. The buffer has to be configured by CpCoreBufferConfig() in advance. The parameter ptsFifoV
is a pointer to a memory location where a FIFO has been initialized using the CpFifoInit() function.
The following example shows the configuration of a receive FIFO
CpStatus_tv CpCoreFifoRead | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubBufferIdxV, | ||
CpCanMsg_ts * | ptsCanMsgV, | ||
uint32_t * | pulMsgCntV | ||
) |
Read a CAN message from FIFO.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubBufferIdxV | Buffer number |
[out] | ptsCanMsgV | Pointer to a CAN message structure |
[in,out] | pulMsgCntV | Pointer to message count variable |
eCP_ERR_NONE
.This function reads CAN messages from a receive FIFO defined by the parameter ubBufferIdxV
. The first message buffer starts at the index eCP_BUFFER_1. The FIFO has to be configured by CpCoreFifoConfig() in advance. The parameter ptsCanMsgV
is a pointer to the application buffer as array of CpCanMsg_ts
objects to store the received CAN messages. The parameter pulMsgCntV
is a pointer to a memory location which has to be initialized before the call to the size of the buffer referenced by ptsCanMsgV
as multiple of CpCanMsg_ts
objects. Upon return, the driver has stored the number of messages copied into the application buffer into this parameter.
The following example shows a read operation from a receive FIFO
CpStatus_tv CpCoreFifoRelease | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubBufferIdxV | ||
) |
Release FIFO from message buffer.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubBufferIdxV | Buffer number |
eCP_ERR_NONE
.This function releases an assigned FIFO from a message buffer defined by the parameter ubBufferIdxV
. The first message buffer starts at the index eCP_BUFFER_1. The FIFO has to be configured by CpCoreFifoConfig() in advance.
CpStatus_tv CpCoreFifoWrite | ( | CpPort_ts * | ptsPortV, |
uint8_t | ubBufferIdxV, | ||
CpCanMsg_ts * | ptsCanMsgV, | ||
uint32_t * | pulMsgCntV | ||
) |
Transmit a CAN message.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ubBufferIdxV | Buffer number |
[in] | ptsCanMsgV | Pointer to a CAN message structure |
[in,out] | pulMsgCntV | Pointer to message count variable |
eCP_ERR_NONE
.This function writes CAN messages to a transmit FIFO defined by the parameter ubBufferIdxV
. The first message buffer starts at the index eCP_BUFFER_1. The FIFO has to be configured by CpCoreFifoConfig() in advance. The parameter ptsCanMsgV
is a pointer to the application buffer as array of CpCanMsg_ts
objects which contain the CAN messages that should be transmitted. The parameter pulMsgCntV
is a pointer to a memory location which has to be initialized before the call to the size of the buffer referenced by ptsCanMsgV
as multiple of CpCanMsg_ts
objects. Upon return, the driver has stored the number of messages transmitted successfully into this parameter.
CpStatus_tv CpCoreHDI | ( | CpPort_ts * | ptsPortV, |
CpHdi_ts * | ptsHdiV | ||
) |
Get hardware description information.
[in] | ptsPortV | Pointer to CAN port structure |
[out] | ptsHdiV | Pointer to the Hardware Description Interface structure (CpHdi_ts) |
eCP_ERR_NONE
.This function retrieves information about the CAN interface. The parameter ptsHdiV
is a pointer to a memory location where the function will store the information.
CpStatus_tv CpCoreIntFunctions | ( | CpPort_ts * | ptsPortV, |
CpRcvHandler_Fn | pfnRcvHandlerV, | ||
CpTrmHandler_Fn | pfnTrmHandlerV, | ||
CpErrHandler_Fn | pfnErrHandlerV | ||
) |
Install callback functions.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | pfnRcvHandlerV | Pointer to callback function for receive handler |
[in] | pfnTrmHandlerV | Pointer to callback function for transmit handler |
[in] | pfnErrHandlerV | Pointer to callback function for error handler |
eCP_ERR_NONE
.This function will install three different callback routines in the interrupt handler. If you do not want to install a callback for a certain interrupt condition the parameter must be set to NULL. The callback functions for receive and transmit interrupt have the following syntax: uint8_t Handler(CpCanMsg_ts * ptsCanMsgV, uint8_t ubBufferIdxV)
The callback function for the CAN status-change / error interrupt has the following syntax: uint8_t Handler(uint8_t ubStateV)
CpStatus_tv CpCoreStatistic | ( | CpPort_ts * | ptsPortV, |
CpStatistic_ts * | ptsStatsV | ||
) |
Read CAN controller statistics.
[in] | ptsPortV | Pointer to CAN port structure |
[in] | ptsStatsV | Pointer to statistic data structure |
eCP_ERR_NONE
.This function copies CAN statistic information to the structure pointed by ptsStatsV
.