cp_core.h File Reference

CANpie core functions. More...

Include dependency graph for cp_core.h:


Functions
_TvCpStatus	CpCoreAutobaud (_TsCpPort ptsPortV, _U08 pubBaudSelV, _U16 *puwWaitV)
_TvCpStatus	CpCoreBaudrate (_TsCpPort *ptsPortV, _U08 ubBaudSelV)
_TvCpStatus	CpCoreBittiming (_TsCpPort ptsPortV, _TsCpBitTiming ptsBitrateV)
_TvCpStatus	CpCoreBufferGetData (_TsCpPort ptsPortV, _U08 ubBufferIdxV, _U08 pubDataV)
_TvCpStatus	CpCoreBufferGetDlc (_TsCpPort ptsPortV, _U08 ubBufferIdxV, _U08 pubDlcV)
_TvCpStatus	CpCoreBufferInit (_TsCpPort ptsPortV, _TsCpCanMsg ptsCanMsgV, _U08 ubBufferIdxV, _U08 ubDirectionV)
_TvCpStatus	CpCoreBufferRelease (_TsCpPort *ptsPortV, _U08 ubBufferIdxV)
_TvCpStatus	CpCoreBufferSend (_TsCpPort *ptsPortV, _U08 ubBufferIdxV)
_TvCpStatus	CpCoreBufferSetData (_TsCpPort ptsPortV, _U08 ubBufferIdxV, _U08 pubDataV)
_TvCpStatus	CpCoreBufferSetDlc (_TsCpPort *ptsPortV, _U08 ubBufferIdxV, _U08 ubDlcV)
_TvCpStatus	CpCoreCanMode (_TsCpPort *ptsPortV, _U08 ubModeV)
_TvCpStatus	CpCoreCanState (_TsCpPort ptsPortV, _TsCpState ptsStateV)
_TvCpStatus	CpCoreDriverInit (_U08 ubPhyIfV, _TsCpPort *ptsPortV)
_TvCpStatus	CpCoreDriverRelease (_TsCpPort *ptsPortV)
_TvCpStatus	CpCoreHDI (_TsCpPort ptsPortV, _TsCpHdi ptsHdiV)
_TvCpStatus	CpCoreIntFunctions (_TsCpPort ptsPortV, _U08(pfnRcvHandler)(_TsCpCanMsg , _U08), _U08(pfnTrmHandler)(_TsCpCanMsg , _U08), _U08(pfnErrHandler)(_U08))
_TvCpStatus	CpCoreMsgRead (_TsCpPort ptsPortV, _TsCpCanMsg ptsBufferV, _U32 *pulBufferSizeV)
_TvCpStatus	CpCoreMsgWrite (_TsCpPort ptsPortV, _TsCpCanMsg ptsBufferV, _U32 *pulBufferSizeV)
_TvCpStatus	CpCoreStatistic (_TsCpPort ptsPortV, _TsCpStatistic ptsStatsV)

Detailed Description

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 CpErr_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.

Initialisation Process

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

 void MyCanInit(void)
 {
    _TsCpPort tsCanPortT; // logical CAN port
    //---------------------------------------------------
    // setup the CAN controller / open a physical CAN
    // port
    //
    CpCoreDriverInit(CP_CHANNEL_1, &tsCanPortT);
    //---------------------------------------------------
    // setup 500 kBit/s
    //
    CpCoreBaudrate(&tsCanPortT, CP_BAUD_500K);
    //---------------------------------------------------
    // start CAN operation
    //
    CpCoreCanMode(&tsCanPortT, CP_MODE_START);
    //.. now we are operational
 }

Function Documentation

_TvCpStatus CpCoreAutobaud	(	_TsCpPort *	ptsPortV,
		_U08 *	pubBaudSelV,
		_U16 *	puwWaitV
	)

Run automatic bitrate detection.

Parameters:

ptsPortV

Pointer to CAN port structure

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

_TvCpStatus CpCoreBaudrate	(	_TsCpPort *	ptsPortV,
		_U08	ubBaudSelV
	)

Set bitrate of CAN controller.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ubBaudSelV	Bitrate selection

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function directly writes to the bit timing registers of the CAN controller. The value for the parameter ubBaudSelV is taken from the CP_BAUD enumeration.

_TvCpStatus CpCoreBittiming	(	_TsCpPort *	ptsPortV,
		_TsCpBitTiming *	ptsBitrateV
	)

Set bitrate of CAN controller.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ptsBitrateV	Pointer to bit timing structure

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function directly writes to the bit timing registers of the CAN controller. Usage of the function requires a detailed knowledge of the used CAN controller hardware.

_TvCpStatus CpCoreBufferGetData	(	_TsCpPort *	ptsPortV,
		_U08	ubBufferIdxV,
		_U08 *	pubDataV
	)

Get data from message buffer.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ubBufferIdxV	Buffer number
	pubDataV	Buffer for data

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function is the fastest method to get data from a FullCAN message buffer. The buffer has to be configured by a call to CpCoreBufferInit() before.

_TvCpStatus CpCoreBufferGetDlc	(	_TsCpPort *	ptsPortV,
		_U08	ubBufferIdxV,
		_U08 *	pubDlcV
	)

Get DLC of specified buffer.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ubBufferIdxV	Buffer number
	pubDlcV	Data Length Code

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function retrieves the Data Length Code (DLC) of the selected buffer ubBufferIdxV.

_TvCpStatus CpCoreBufferInit	(	_TsCpPort *	ptsPortV,
		_TsCpCanMsg *	ptsCanMsgV,
		_U08	ubBufferIdxV,
		_U08	ubDirectionV
	)

Initialise buffer in FullCAN controller.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ptsCanMsgV	Pointer to a CAN message structure
	ubBufferIdxV	Buffer number
	ubDirectionV	Direction of message

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

See also:: CpCoreBufferRelease()

This function allocates the message buffer in a FullCAN controller. The number of the message buffer inside the FullCAN controller is denoted via the parameter ubBufferIdxV. The parameter ubDirectionV can have the following values:

CP_BUFFER_DIR_RX: receive
CP_BUFFER_DIR_TX: transmit

The following example shows the setup of a transmit buffer

void AllocateTrmBuffer(_TsCpPort * ptsCanPortV)
{
   _TsCpCanMsg tsCanMsgT;    // temporary CAN message


   //----------------------------------------------------------------
   // set message buffer 1 as transmit buffer,
   // ID = 120, DLC = 2
   //
   CpMsgClear(&tsCanMsgT);
   CpMsgSetStdId(&tsCanMsgT, 120); // ID = 120
   CpMsgSetDlc(&tsCanMsgT, 2);
   CpCoreBufferInit(ptsCanPortV, &tsCanMsgT,
                    CP_BUFFER_1, CP_BUFFER_DIR_TX);
}

An allocated transmit buffer can be sent via the function CpCoreBufferSend().

_TvCpStatus CpCoreBufferRelease	(	_TsCpPort *	ptsPortV,
		_U08	ubBufferIdxV
	)

Release message buffer of FullCAN controller.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ubBufferIdxV	Buffer number

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

See also:: CpCoreBufferInit()

_TvCpStatus CpCoreBufferSend	(	_TsCpPort *	ptsPortV,
		_U08	ubBufferIdxV
	)

Send message from message buffer.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ubBufferIdxV	Index of message buffer

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function transmits a message from the specified message buffer ubBufferIdxV. The message buffer has to be configured by a call to CpCoreBufferInit() in advance. The first message buffer starts at the index CP_BUFFER_1.

_TvCpStatus CpCoreBufferSetData	(	_TsCpPort *	ptsPortV,
		_U08	ubBufferIdxV,
		_U08 *	pubDataV
	)

Set data of message buffer.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ubBufferIdxV	Buffer number
	pubDataV	Pointer to data buffer

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function is the fastest method to set the data bytes of a CAN message. It can be used in combination with the function CpCoreBufferSend(). It will write 8 data bytes into the buffer defined by ubBufferIdxV. The buffer has to be configured by CpCoreBufferInit() in advance. The size of the data buffer pubDataV must have a size of 8 bytes.

The following example demonstrates the access to the data bytes of a CAN message:

  _U08 aubDataT[8];   // buffer for 8 bytes

 aubDataT[0] = 0x11;  // byte 0: set to 11hex
 aubDataT[1] = 0x22;  // byte 1: set to 22hex

 //--- copy the stuff to message buffer 1 ---------------
 CpCoreBufferSetData(CP_CHANNEL_1, CP_BUFFER_1, &aubDataT);

 //--- send this message out ----------------------------
 CpCoreBufferSend(CP_CHANNEL_1, CP_BUFFER_1);

_TvCpStatus CpCoreBufferSetDlc	(	_TsCpPort *	ptsPortV,
		_U08	ubBufferIdxV,
		_U08	ubDlcV
	)

Set DLC of specified buffer.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ubBufferIdxV	Buffer number
	ubDlcV	Data Length Code

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function sets the Data Length Code (DLC) of the selected buffer ubBufferIdxV. The DLC must be in the range from 0 to 8.

_TvCpStatus CpCoreCanMode	(	_TsCpPort *	ptsPortV,
		_U08	ubModeV
	)

Set state of CAN controller.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ubModeV	Mode selection

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function changes the operating mode of the CAN controller. Possible values for mode are defined in the CP_MODE enumeration.

_TvCpStatus CpCoreCanState	(	_TsCpPort *	ptsPortV,
		_TsCpState *	ptsStateV
	)

Retrieve status of CAN controller.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ptsStateV	Pointer to CAN state structure

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function retrieved the present state of the CAN controller. Possible values are defined in the CP_STATE enumeration. The state of the CAN controller is copied to the variable pointer 'ptsStateV'.

_TvCpStatus CpCoreDriverInit	(	_U08	ubPhyIfV,
		_TsCpPort *	ptsPortV
	)

Initialise the CAN driver.

Parameters:

	ubPhyIfV	CAN channel of the hardware
	ptsPortV	Pointer to CAN port structure

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

See also:: CpCoreDriverRelease()

The functions opens the physical CAN interface defined by the parameter ubPhyIfV. The value for ubPhyIfV is taken from the enumeration CP_CHANNEL. The function sets up the field members of the CAN port handle ptsPortV. On success, the function returns CpErr_OK. On failure, the function can return the following values:

An opened handle to a CAN port must be closed via the CpCoreDriverRelease() function.

_TvCpStatus CpCoreDriverRelease ( _TsCpPort * ptsPortV )

Release the CAN driver.

Parameters:

ptsPortV

Pointer to CAN port structure

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

See also:: CpCoreDriverInit()

The implementation of this function is dependent on the operating system. Typical tasks might be:

clear the interrupt vector / routine
close all open paths to the hardware

_TvCpStatus CpCoreHDI	(	_TsCpPort *	ptsPortV,
		_TsCpHdi *	ptsHdiV
	)

Get hardware description information.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ptsHdiV	Pointer to the Hardware Description Interface structure (_TsCpHdi)

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function retrieves information about the used hardware.

_TvCpStatus CpCoreIntFunctions	(	_TsCpPort *	ptsPortV,
		_U08()(_TsCpCanMsg , _U08)	pfnRcvHandler,
		_U08()(_TsCpCanMsg , _U08)	pfnTrmHandler,
		_U08(*)(_U08)	pfnErrHandler
	)

Install callback functions.

Parameters:

	ptsPortV	Pointer to CAN port structure
	pfnRcvHandler	Pointer to callback function for receive interrupt
	pfnTrmHandler	Pointer to callback function for transmit interrupt
	pfnErrHandler	Pointer to callback function for error interrupt

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

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: _U08 Handler(_TsCpCanMsg * ptsCanMsgV, _U08 ubBufferIdxV)

The callback function for the CAN status-change / error interrupt has the following syntax: _U08 Handler(_U08 ubStateV)

_TvCpStatus CpCoreMsgRead	(	_TsCpPort *	ptsPortV,
		_TsCpCanMsg *	ptsBufferV,
		_U32 *	pulBufferSizeV
	)

Read a CAN message from controller.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ptsBufferV	Pointer to a CAN message structure
	pulBufferSizeV	Pointer to size variable

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function reads the receive queue from a CAN controller.

_TvCpStatus CpCoreMsgWrite	(	_TsCpPort *	ptsPortV,
		_TsCpCanMsg *	ptsBufferV,
		_U32 *	pulBufferSizeV
	)

Transmit a CAN message.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ptsBufferV	Pointer to a CAN message structure
	pulBufferSizeV	Pointer to size variable

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function writes to the transmit queue of a CAN controller.

_TvCpStatus CpCoreStatistic	(	_TsCpPort *	ptsPortV,
		_TsCpStatistic *	ptsStatsV
	)

Read CAN controller statistics.

Parameters:

	ptsPortV	Pointer to CAN port structure
	ptsStatsV	Pointer to statistic data structure

Returns:: Error code taken from the CpErr enumeration. If no error occurred, the function will return CpErr_OK.

This function copies CAN statistic information to the structure pointed by ptsStatsV.

cp_core.h File Reference

Functions

Detailed Description

Initialisation Process

Function Documentation

© MicroControl GmbH & Co. KG

CANpie - V2.00