@CHIP-RTOS - Data CAN API Structures

Data Structures

• Byte alignment is required for all data structures used within the API.

Component List

typedef int CAN_BOOL ;

Comments

Type used to designate Booleans used in the CAN API.   A non-zero value indicates TRUE and zero indicates FALSE.

typedef struct CAN_CONFIG_
{
    unsigned int    Baud ;          // In kHz
    unsigned int    Mode ;          // Bit field, options
    unsigned int    Mask ;          // Bits to be affected
    unsigned int    Value ;         // Values to apply under mask.
    unsigned int    Bit_Rate_Div ;  // B10:B0 = (Clk prescaler - 1)
    // Bit_Rate_Div is ignored unless all the CAN_CFG_TSEG2_MASK
    //  and CAN_CFG_TSEG2_MASK bits are set in above Config_Mask word.
}
 CAN_CONFIG ;

#define CAN_PASSIVE_MODE        (0x2)
#define CAN_LOOP_BACK_MODE      (0x4)
#define CAN_TXQ1_DRIVES_ALL     (0x8)
#define CAN_TX_PRIORITY_QUEUES  (0x10)

#define CAN_CFG_OVERWRITE_LAST_MESSAGE (0x8000)
#define CAN_CFG_TSEG2_MASK             (0x7000)
#define CAN_CFG_TSEG1_MASK             (0x0F00)
#define CAN_CFG_AUTO_RESTART           (0x0010)
#define CAN_CFG_SYNC_JMP_WIDTH         (0x000C)
#define CAN_CFG_RX_SAMPLE_3_POINTS     (0x0002)
#define CAN_CFG_RX_EDGE_SYNC_MODE      (0x0001)

Comments

The CAN_CONFIG structure is used in the CAN_Open_Port() and CAN_Reconfig() API's to specify a CAN ports bit timing configuration.

Baud

CAN baud rate, in kilo-Hertz.   The standard CAN baud rates are (in kHz) 10, 20, 50, 100, 125, 250, 500, 800 and 1000.   For these settings, the hardware can provide an exact fit baud rate. For other non-standard settings, there may be some slight error.   The resulting error is observable through the Baud read out provide by the CAN_Status() API.


Note:   The designator "Hz" is used here for "bits per second" (or "bit cycles per second" ).

Mode

This bit field specifies which mode options to use.   All bits set zero provide normal operation.   Bits set indicate the respective option should be applied:

CAN_PASSIVE_MODE:    Output is held at recessive level.   The CAN module is only listening.

CAN_LOOP_BACK_MODE:    An internal loopback between the two CAN channels is made.    (This may be useful for software testing.)

CAN_TXQ1_DRIVES_ALL:    This option specifies that the first CAN transmit FIFO designated with CAN_TX1 should be fed into all hardware transmit registers (of which there are three total) that have a zero size software queue specified.   For example, when this option is used with Tx_Q_Size[CAN_TX2] member of the CAN_PORT_INIT structure set to zero, then the CAN_TX1 FIFO will feed the hardware transmit register that otherwise would have been associated with CAN_TX2.   This option bit has no affect when used with the CAN_Reconfig().   The setting applied at the CAN_Open_Port() call remains in affect.   Refer to the CAN_Send() API documentation for further explanation of this option.

CAN_TX_PRIORITY_QUEUES:    This option sets up the CAN transmit API with two FIFO's.   One queue is normal priority and a second queue is sent with high priority.   No CAN messages will be loaded from the normal priority FIFO into the CAN hardware transmit registers unless the high priority FIFO is empty.   The CAN messages from the high priority FIFO will be loaded first.   The two queues are designated with the indexes CAN_TX_NORMAL and CAN_TX_HIGH.   These indexes replace the transmit channel designators CAN_TX1, CAN_TX2 and CAN_TX3 when operating in CAN_TX_PRIORITY_QUEUES mode. The Tx_Q_Size[CAN_TX_NORMAL] member of the CAN_PORT_INIT structure specifies the size of the normal priority queue and the Tx_Q_Size[CAN_TX_HIGH] member specifies the size of the high priority queue.   (The Tx_Q_Size[CAN_TX3] member plays no role in this mode.)    This option bit has no affect when used with the CAN_Reconfig().   The setting applied at the CAN_Open_Port() call remains in affect.   Refer to the CAN_Send() API documentation for further explanation of this option.   Note that the CAN_TXQ1_DRIVES_ALL option bit is ignored when CAN_TX_PRIORITY_QUEUES is set.

Mask

This bit field specifies which option fields in Value are applied.   Set this member to zero for default settings (which is what most users are expected to do here).   These optional settings are not expected to be needed by most users.   They are only intended as provisional.

The CAN_CFG_TSEG1_MASK and CAN_CFG_TSEG2_MASK fields must both be controlled if either one is controlled.   These in conjunction with the Bit_Rate_Div value are used to set non-standard baud rates and bit timing.

Value

This bit field specifies various options.   Only fields with corresponding bits in Mask set to '1' are applied.   All other fields are ignored.

CAN_CFG_OVERWRITE_LAST_MESSAGE:    When channel's hardware receiver FIFO is full and a new message arrives, the newest message in the hardware FIFO (the previous message) is overwritten by the latest. In default mode, the latest message would be lost under these conditions.

CAN_CFG_TSEG2_MASK:    This three bit field specifies the length (-1) of the second time segment.   CFG_TSEG2=0 is not allowed.  CFG_TSEG2=1 is only allowed in direct sampling mode.

CAN_CFG_TSEG1_MASK:    This four bit field specifies the length (-1) of the first time segment.  It includes the propagation time segment.   CFG_TSEG1=0 and CFG_TSEG1=1 are not allowed.

CAN_CFG_AUTO_RESTART:    When this bit is set to '1' the CAN is restarted automatically after 128 groups of 11 recessive bits, following a bus stop condition   (This is the CAN driver software's default mode.)   When this bit is zero, the CAN bus must be restarted manually.   The CAN_Reconfig() API can be used to restart a bus.

CAN_CFG_SYNC_JMP_WIDTH:    This two bit field specifies the synchronization jump width - 1. (By default this value is set to zero resulting in a synchronization jump width of 1 time quantum.)

CAN_CFG_RX_SAMPLE_3_POINTS:    This bit set specifies that three sampling points per data bit with majority decision be used at the receiver. (This is the default.) With this bit cleared to zero, the receiver will use only one sampling point per data bit.

CAN_CFG_RX_EDGE_SYNC_MODE:    This bit set specifies that both edges ("Recessive to Dominant" and vice-versa) are used by the receiver to synchronize to the incoming data.   With this bit cleared to zero, only the "R to D" edge is used.   (This is the driver's default.)

Bit_Rate_Div

This value will be applied directly to the CAN devices Bit Rate Divisor Register when both CAN_CFG_TSEG1_MASK and CAN_CFG_TSEG2_MASK bits in Mask are set.   This is an 11 bit value in B10:B0.   The B15:B11 upper bits should be zero.   This advanced setting in conjunction with the CFG_TSEG1 and CFG_TSEG2 fields in the Value word allow manual control over the CAN baud rate and bit sampling point.   The resulting CAN baud rate can be calculated as follows:


baud = FREQUENCY / clk_scaler


where


FREQUENCY = CPU processor frequency
clk_scaler = tq_divisor * tq_per_bit
    (Note: Notation "tq" means "Time Quanta" here.)
tq_divisor = (Bit_Rate_Div + 1)
tq_per_bit = (1 + (CFG_TSEG1 + 1) + (CFG_TSEG2 + 1))

CFG_TSEG1 = 4 bit field Value[B11:B8]
CFG_TSEG2 = 3 bit field Value[B14:B12]


The bit sampling occurs (CFG_TSEG1 + 2) time quanta past the start of the bit period.

Note that the Baud member of this structure is ignored when the CAN_CFG_TSEG1_MASK and CAN_CFG_TSEG2_MASK in Mask indicate that baud should be set manually as specified here.

Related Topics

API function CAN_Open_Port() - Open CAN port

API function CAN_Reconfig() - Reconfigure CAN port

API function CAN_Send() - Send CAN message

typedef struct CAN_ERRORS_
{
    unsigned char   TxErrCnt ;      // Bosch defined Tx Error Count
    unsigned char   RxErrCnt ;      // Bosch defined Rx Error Count

    unsigned int    BusStatus ;     // Bit field, see CAN_BS_* masks below.

} CAN_ERRORS ;

#define CAN_BS_RX96     (0x0008)        // Rx error counter >= 96
#define CAN_BS_TX96     (0x0004)        // Tx error counter >= 96
#define CAN_BS_BUS_OFF  (0x0002)        // Bus off flag
#define CAN_BS_PASSIVE  (0x0001)        // Error passive state (if not bus off)

Comments

The CAN_ERRORS structure is used to report the bus error status of a specified CAN port.   These fields are set by the CAN_Error_Counts() API.

TxErrCnt

This count is the transmitter error counter which operates according to the Bosch CAN specification.   When the transmitter error count exceeds 255, this counter stops counting and remains latched at 255.

RxErrCnt

When not in bus off state, this counter holds the receiver error count which operates according to the Bosch CAN specification.   When in bus off state, this counter counts the idle states.

BusStatus

This bit field indicates the bus error conditions.   The four lower bits are set to indicate error conditions as described by the CAN_BS_* mask defines.

CAN_BS_RX96:    This bit is set if the receiver error counter is greater than or equal to 96.

CAN_BS_TX96:    This bit is set if the transmitter error counter is greater than or equal to 96.

CAN_BS_BUS_OFF:    This bit is set if the bus is in the bus off state.

CAN_BS_PASSIVE:    The bus is in the "error passive " state if this bit is set and the CAN_BS_BUS_OFF bit is not set.

If both the CAN_BS_BUS_OFF and CAN_BS_PASSIVE bits are zero, then the bus is in its normal operation state ("error active ").

typedef struct CAN_ID_
{
    unsigned int    Normal ;
    unsigned int    Extended ;
} CAN_ID ;

Comments

The CAN_ID structure is used in the API where ever CAN identifiers must be conveyed.   This includes receiver filter initialization, message send and message receive. Normal 11 bit CAN identifiers are shifted to the left by 5 bits and placed in the Normal member with the Extended field zeroed for send and receivve messages (for receiver filters initialization, see mask bit requirements stated below).

Normal

The normal 11 bit CAN identifiers are placed here left justified in B15 through B5. This means that the 11 bit CAN identifier must be left shifted by 5 bits.    When the extended 29 bit CAN identifiers are used, this field contains identifier bits ID28 through ID13, which are the least significant 16 bits of the extended CAN identifier.

Extended

When using the 29 bit extended CAN identifiers this field holds identifier bits ID12 through ID00 left justified in bits B15 through B3.   This means that the upper half of the long value holding a extended CAN identifier must be shifted to the left by three bits. Note that for receiver filters' Id_Mask, this identifier bit field (B15:B3) must be set to all 1's in order to receive normal 11 bit CAN identifiers (=0xFFF8, or =0xFFFA if the CAN_FILT_RTR flag mentioned below is OR'ed in).

When used to initialize receiver filters, this word also carries the following input message qualifiers in two of the lower three bits:

CAN_FILT_IDE = 0x4:   Accept only 29 bit extended ID messages through this filter.
CAN_FILT_RTR = 0x2:   Accept only Remote Transmit Request (RTR) messages through this filter.

The lower three bits of this word are zero for send/receive message identifiers.

Related Topics

API function CAN_Rx_Filters() - Set receiver filters

API function CAN_Send() - Send CAN message

API function CAN_Recv() - Get received message

typedef struct CAN_MSG_
{
    CAN_ID          Id ;        // 11 or 29 bit identifier
    unsigned char   Data[8] ;   // 0..8 bytes data
    unsigned int    Len_Ctrl ;  // Data Length Count (and some flags)

} CAN_MSG ;

  // Masks for CAN_MSG.Len_Ctrl word
#define CAN_DLC_FIELD  (0x000F) // Data Length Count, [0..8]
#define CAN_IDE_FLAG   (0x0010) // Extended (29 bit) ID flag
#define CAN_RTR_FLAG   (0x0020) // Remote Request flag
#define CAN_RX_AF1     (0x0100) // Received through acceptance filter 1
#define CAN_RX_AF2     (0x0200) // Received through acceptance filter 2
#define CAN_RX_AF3     (0x0400) // Received through acceptance filter 3

Comments

The CAN_MSG structure provides a container for outgoing and incoming CAN messages.

Id

This structure carries the message's identier.

Data

The CAN message data bytes are put here, when message contains data.

Len_Ctrl

The primary purpose of this member is to state the "Data Length Count", which is the number of data bytes in the CAN message.   The lower four bits specify this count.   The legal range is from 0 to 8 bytes, inclusive.   (Illegal values here on transmit messages will be output verbatim, but no more than 8 data bytes will be transmitted.)

Two other discrete flags here indicate if the message uses a 29 bit identifier (CAN_IDE_FLAG) or is a "Remote Transmit Request" trigger (CAN_RTR_FLAG) when set.

For received messages, the three CAN_RX_AFx discrete flags indicate which of the acceptance filters permitted this message to come in.

Related Topics

API function CAN_Send() - Send CAN message

API function CAN_Recv() - Get received message

API function CAN_Peek() - Peek at received message

typedef struct CAN_PORT_INIT_
{
    CAN_BOOL        fDisable_Rx ;   // Initially disable Recvr
    CAN_CONFIG      Config ;        // Configuration Reg settings
    unsigned int    Rx_Q_Size ;     // Number of CAN msgs
    unsigned int    Tx_Q_Size[NUM_CAN_TX] ;
} CAN_PORT_INIT ;

Comments

fDisable_Rx

Set this flag if you do not want the receiver immediately enabled on return from the CAN_Open_Port() call.

Config

This data structure specifies the baud rate and other parameters.

Rx_Q_Size

This count specifies the size of the receiver ring buffer which will be created for this CAN channel.   Legal values are in the range from 1 to 500 (inclusive) messages.  

Tx_Q_Size

This array of three counts provides individual control over the lengths of the transmit ring buffers which feed the three hardware transmit registers.   Legal values are in the range from 0 to 500 (inclusive) messages.   When operating with a transmit ring buffer size zero, the CAN_Send() API will either load the hardware transmit register directly or return without taking any action.   If CAN_TX2 and CAN_TX3 FIFO's are specified with zero size when the CAN_TXQ1_DRIVES_ALL option flag is set in the Config.Mode word, then the hardware transmit register (TX2, TX3) normally driven by the FIFO corresponding with that Tx_Q_Size value will instead be loaded from the CAN_TX1 FIFO.   In this manner, a single output queue can be used to feed more than one hardware transmit register.

When the CAN_TX_PRIORITY_QUEUES option in the Config.Mode word flag is used, then the alternate indexes CAN_TX_NORMAL and CAN_TX_HIGH apply here.

Related Topics

API function CAN_Open_Port() - Open CAN port

API function CAN_Send() - Send CAN message

typedef struct CAN_RX_FILT_
{
    // Mask 1 bits = Don't care
    // Mask 0 bits = Must match specified values
    CAN_ID          Id_Mask ;       //
    unsigned int    Data_Mask ;     // 2 byte data mask
    CAN_ID          Id_Value ;      //
    unsigned int    Data_Value ;    // 2 byte data mask

} CAN_RX_FILT ;

Comments

The CAN_RX_FILT structure is used to initialize one of the CAN device's three receiver filters.   By setting a receiver filter's mask registers to all bits '1' (="Don't care"), the filter will accept all incoming CAN messages.

Id_Mask

This structure specifies which bits of the received messages identifier should be compared.   Bits set to '0' indicate bits that should be compared against those in Id_Value.   Note that to receive normal 11 bit CAN identifiers, the 13 bit field B15:B3 in the Extended member of this structure must be set to all 1's (=0xFFF8).

Data_Mask

Incoming messages can also be filtered based on contents of first two of the up to 8 bytes of CAN message data.   This 16 bit field is used to mark which data bits of incoming messages should be compared against the corresponding bits in Data_Value.   The lower byte corresponds to first CAN data byte and the upper byte corresponds to the second data byte.   Zero bits are compared and bits set to '1' are don't care.

Id_Value

This structure specifies the identifier bit values that will be compared against those received.   Only the bits set to zero in the Id_Mask are applied in the filter test.

Data_Value

These 16 bits are compared against the first two CAN data bytes.   Only the bits set to zero in the Data_Mask are applied in the filter test.

Related Topics

API function CAN_Rx_Filters() - Set receiver filters

typedef struct CAN_STATUS_
{
    CAN_BOOL        fPort_Opened ;  // TRUE if port is now open
    unsigned long   Baud ;          // In bits/second
    unsigned int    Device_Enable ; // Bit field for Rx & 3 Tx.
    unsigned int    Errors ;        // Bit field
    unsigned int    Rx_Count ;      // Messages in ring buffer
    unsigned int    Tx_Count[NUM_CAN_TX] ;

} CAN_STATUS ;

#define CAN_RX_SEL   (0x8000)   // Receiver control flag
#define CAN_TX1_SEL  (0x0800)   // TX1 reg control flag
#define CAN_TX2_SEL  (0x1000)   // TX2 reg control flag
#define CAN_TX3_SEL  (0x2000)   // TX3 reg control flag

#define CAN_ARBLOSS     0x0004      // Arbitration lost during tx
#define CAN_OVRLOAD     0x0008      // Overload condition
#define CAN_RX_OVR_ERR  0x0010      // Receiver overrun in hardware
#define CAN_BIT_ERR     0x0020      // Bit error during tx or rx
#define CAN_STUF_ERR    0x0040      // Stuffing error during tx or rx
#define CAN_ACK_ERR     0x0080      // Ack error during tx or rx
#define CAN_FORM_ERR    0x0100      // Format error during tx or rx
#define CAN_CRC_ERR     0x0200      // CRC error during tx or rx
#define CAN_BUS_OFF     0x0400      // CAN switched to bus off state
#define CAN_SW_RX_OVR   0x0800      // Software Rx ring buffer overflow.

Comments

The CAN_STATUS structure is used to report the status of a specified CAN port.   These fields are set by the CAN_Status() API.

fPort_Opened

This flag is set to one (TRUE) if the respective port is opened, otherwise it is set to zero (FALSE).

Baud

The actual baud rate (assuming an accurate clock crystal) is reported here.   This may differ slightly from the requested baud rate when a best fit must be used (for non-standard CAN baud rates) instead of an exact fit.   Note that this value is resolved to Hz (not kHz as was the requested value).  


Note:   The designator "Hz" is used here for "bits per second" (or "bit cycles per second" ).

Device_Enable

This bit field reports which devices are enabled.   The following bits are set when the corresponding device is enabled:

CAN_RX_SEL = 0x8000 - Receiver enabled
CAN_TX1_SEL= 0x0800 - Transmit register #1 enabled
CAN_TX2_SEL = 0x1000 - Transmit register #2 enabled
CAN_TX3_SEL = 0x2000 - Transmit register #3 enabled

Errors

This bit field indicates the errors which have occurred.   The bit definitions are listed above with the defined constants (e.g. CAN_ARBLOSS).   The internal error flags are cleared upon this read out.

Rx_Count

This count indicates the number of received CAN messages available for pickup.

Tx_Count

These three counts indicate the number of CAN messages awaiting output on each of the three CAN transmit registers.   This count includes any CAN message pending output in a hardware transmit register plus those awaiting in the driver's software transmit FIFO.

Related Topics

API function CAN_Status() - Check status