CANpie: cp_core.h File Reference

For a "FullCAN" controller (i.e. a CAN controller that has several message buffers) an extended set of powerful functions (CpCoreBuffer..())is provided.

Initialization Process

The CAN driver is initialized 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:

 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 baudrate detection.

Parameters:

ptsPortV

CAN channel of the hardware

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

_TvCpStatus CpCoreBaudrate	(	_TsCpPort *	ptsPortV,
		_U08	ubBaudSelV
	)

Set bitrate of CAN controller.

Parameters:

	ptsPortV	CAN channel of the hardware
	ubBaudSelV	Baudrate selection

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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 handle
	ptsBitrateV	Pointer to bit timing structure

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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	CAN channel of the hardware
	ubBufferIdxV	Buffer number
	pubDataV	Buffer for data

Returns:: Error code taken from the CpErr enumeration

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	CAN channel of the hardware
	ubBufferIdxV	Buffer number
	pubDlcV	Data Length Code

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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
	)

Initialize buffer in FullCAN controller.

Parameters:

	ptsPortV	CAN channel of the hardware
	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 occured, 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(tsMyCanMsgT);
   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	CAN channel of the hardware
	ubBufferIdxV	Buffer number

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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 handle
	ubBufferIdxV	index of message buffer

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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	CAN channel of the hardware
	ubBufferIdxV	Buffer number
	pubDataV	Pointer to data buffer

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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	CAN channel of the hardware
	ubBufferIdxV	Buffer number
	ubDlcV	Data Length Code

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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	CAN channel of the hardware
	ubModeV	Mode selection

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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
	)

Retrive status of CAN controller.

Parameters:

	ptsPortV	CAN channel of the hardware
	ptsStateV	Pointer to CAN state structure

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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
	)

Initialize the CAN driver.

Parameters:

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

Returns:: Error code taken from the CpErr enumeration.

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 succes, 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

CAN channel of the hardware

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

See also:: CpCoreDriverInit()

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

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

_TvCpStatus CpCoreFilterAll	(	_U08	ubChannelV,
		_BIT	enable
	)

Set global hardware filter for CAN messages.

Parameters:

	ubChannelV	CAN channel of the hardware
	enable	TRUE for accepting all identifiers, FALSE for rejecting all identifiers

Returns:

Error code taken from the CpErr enumeration. Possible return values are:

CpErr_NOT_SUPPORTED - Function is not supported by the driver
CpErr_OK - Function returned without error condition

This function sets up a hardware CAN identifier filter. The filter might be a firmware on an intelligent PC card.

_TvCpStatus CpCoreFilterMsg	(	_U08	ubChannelV,
		_U16	id,
		_BIT	enable
	)

Hardware filter for CAN messages.

Parameters:

	ubChannelV	CAN channel of the hardware
	id	value of the identifier
	enable	TRUE for accepting an identifier, FALSE for rejecting an identifier

Returns:

Error code taken from the CpErr enumeration. Possible return values are:

CpErr_NOT_SUPPORTED - Function is not supported by the driver
CpErr_OK - Function returned without error condition

This function sets a filter for CAN messages. If the flag enable is set to TRUE, the CAN identifier id is accepted. If the flag enable is set to FALSE, the reception of messages with the identifier id is not possible. Please notice that this function only works for standard messages (2.0A, 11 bit identifier).

_TvCpStatus CpCoreHDI	(	_TsCpPort *	ptsPortV,
		_TsCpHdi *	ptsHdiV
	)

Get hardware description information.

Parameters:

	ptsPortV	CAN channel of the hardware
	ptsHdiV	Pointer to the Hardware Description Interface structure (_TsCpHdi)

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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 handle
	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 occured, 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	CAN channel of the hardware
	ptsBufferV	Pointer to a CAN message structure
	pulBufferSizeV	Pointer to size variable

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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	CAN channel of the hardware
	ptsBufferV	Pointer to a CAN message structure
	pulBufferSizeV	Pointer to size variable

Returns:: Error code taken from the CpErr enumeration. If no error occured, 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	CAN channel of the hardware
	ptsStatsV	Pointer to statistic data structure

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

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

cp_core.h File Reference

Detailed Description

Initialization Process

Functions

Function Documentation

© MicroControl GmbH & Co. KG

CANpie - V1.93