|
|
|
MSP432E4 DriverLib API Guide
1.11.00.03
|
Data Structures | |
| struct | tCANMsgObject |
| struct | tCANBitClkParms |
Macros | |
| #define | CAN_MAX_11BIT_MSG_ID 0x7ff |
| #define | CAN_MAX_BIT_DIVISOR 19 |
| #define | CAN_MIN_BIT_DIVISOR 4 |
| #define | CAN_MAX_PRE_DIVISOR 1024 |
| #define | CAN_MIN_PRE_DIVISOR 1 |
| #define | CAN_BIT_VALUE(seg1, seg2, sjw) |
| #define | MSG_OBJ_TX_INT_ENABLE 0x00000001 |
| This indicates that transmit interrupts are enabled. More... | |
| #define | MSG_OBJ_RX_INT_ENABLE 0x00000002 |
| This indicates that receive interrupts are enabled. More... | |
| #define | MSG_OBJ_EXTENDED_ID 0x00000004 |
| This indicates that a message object is using an extended identifier. More... | |
| #define | MSG_OBJ_USE_ID_FILTER 0x00000008 |
| #define | MSG_OBJ_NEW_DATA 0x00000080 |
| This indicates that new data was available in the message object. More... | |
| #define | MSG_OBJ_DATA_LOST 0x00000100 |
| #define | MSG_OBJ_USE_DIR_FILTER (0x00000010 | MSG_OBJ_USE_ID_FILTER) |
| #define | MSG_OBJ_USE_EXT_FILTER (0x00000020 | MSG_OBJ_USE_ID_FILTER) |
| #define | MSG_OBJ_REMOTE_FRAME 0x00000040 |
| This indicates that a message object is a remote frame. More... | |
| #define | MSG_OBJ_FIFO 0x00000200 |
| #define | MSG_OBJ_NO_FLAGS 0x00000000 |
| This indicates that a message object has no flags set. More... | |
| #define | MSG_OBJ_STATUS_MASK (MSG_OBJ_NEW_DATA | MSG_OBJ_DATA_LOST) |
| #define | CAN_INT_ERROR 0x00000008 |
| #define | CAN_INT_STATUS 0x00000004 |
| #define | CAN_INT_MASTER 0x00000002 |
| #define | CAN_STATUS_BUS_OFF 0x00000080 |
| CAN controller has entered a Bus Off state. More... | |
| #define | CAN_STATUS_EWARN 0x00000040 |
| CAN controller error level has reached warning level. More... | |
| #define | CAN_STATUS_EPASS 0x00000020 |
| CAN controller error level has reached error passive level. More... | |
| #define | CAN_STATUS_RXOK 0x00000010 |
| A message was received successfully since the last read of this status. More... | |
| #define | CAN_STATUS_TXOK 0x00000008 |
| #define | CAN_STATUS_LEC_MSK 0x00000007 |
| This is the mask for the last error code field. More... | |
| #define | CAN_STATUS_LEC_NONE 0x00000000 |
| There was no error. More... | |
| #define | CAN_STATUS_LEC_STUFF 0x00000001 |
| A bit stuffing error has occurred. More... | |
| #define | CAN_STATUS_LEC_FORM 0x00000002 |
| A formatting error has occurred. More... | |
| #define | CAN_STATUS_LEC_ACK 0x00000003 |
| An acknowledge error has occurred. More... | |
| #define | CAN_STATUS_LEC_BIT1 0x00000004 |
| The bus remained a bit level of 1 for longer than is allowed. More... | |
| #define | CAN_STATUS_LEC_BIT0 0x00000005 |
| The bus remained a bit level of 0 for longer than is allowed. More... | |
| #define | CAN_STATUS_LEC_CRC 0x00000006 |
| A CRC error has occurred. More... | |
| #define | CAN_STATUS_LEC_MASK 0x00000007 |
| This is the mask for the CAN Last Error Code (LEC). More... | |
Enumerations | |
| enum | tCANIntStsReg { CAN_INT_STS_CAUSE, CAN_INT_STS_OBJECT } |
| enum | tCANStsReg { CAN_STS_CONTROL, CAN_STS_TXREQUEST, CAN_STS_NEWDAT, CAN_STS_MSGVAL } |
| enum | tMsgObjType { MSG_OBJ_TYPE_TX, MSG_OBJ_TYPE_TX_REMOTE, MSG_OBJ_TYPE_RX, MSG_OBJ_TYPE_RX_REMOTE, MSG_OBJ_TYPE_RXTX_REMOTE } |
Functions | |
| void | CANInit (uint32_t ui32Base) |
| void | CANEnable (uint32_t ui32Base) |
| void | CANDisable (uint32_t ui32Base) |
| void | CANBitTimingGet (uint32_t ui32Base, tCANBitClkParms *psClkParms) |
| uint32_t | CANBitRateSet (uint32_t ui32Base, uint32_t ui32SourceClock, uint32_t ui32BitRate) |
| void | CANBitTimingSet (uint32_t ui32Base, tCANBitClkParms *psClkParms) |
| void | CANIntRegister (uint32_t ui32Base, void(*pfnHandler)(void)) |
| void | CANIntUnregister (uint32_t ui32Base) |
| void | CANIntEnable (uint32_t ui32Base, uint32_t ui32IntFlags) |
| void | CANIntDisable (uint32_t ui32Base, uint32_t ui32IntFlags) |
| uint32_t | CANIntStatus (uint32_t ui32Base, tCANIntStsReg eIntStsReg) |
| void | CANIntClear (uint32_t ui32Base, uint32_t ui32IntClr) |
| void | CANRetrySet (uint32_t ui32Base, bool bAutoRetry) |
| bool | CANRetryGet (uint32_t ui32Base) |
| uint32_t | CANStatusGet (uint32_t ui32Base, tCANStsReg eStatusReg) |
| bool | CANErrCntrGet (uint32_t ui32Base, uint32_t *pui32RxCount, uint32_t *pui32TxCount) |
| void | CANMessageSet (uint32_t ui32Base, uint32_t ui32ObjID, tCANMsgObject *psMsgObject, tMsgObjType eMsgType) |
| void | CANMessageGet (uint32_t ui32Base, uint32_t ui32ObjID, tCANMsgObject *psMsgObject, bool bClrPendingInt) |
| void | CANMessageClear (uint32_t ui32Base, uint32_t ui32ObjID) |
The Controller Area Network (CAN) APIs provide a set of functions for accessing the MSP432E4 CAN modules. Functions are provided to configure the CAN controllers, configure message objects, and manage CAN interrupts.
The MSP432E4 CAN module provides hardware processing of the CAN data link layer. It can be configured with message filters and preloaded message data so that it can autonomously send and receive messages on the bus and notify the application accordingly. It automatically handles generation and checking of CRCs, error processing, and retransmission of CAN messages.
The message objects are stored in the CAN controller and provide the main interface for the CAN module on the CAN bus. There are 32 message objects that can each be programmed to handle a separate message ID, or can be chained together for a sequence of frames with the same ID. The message identifier filters provide masking that can be programmed to match any or all of the message ID bits, and frame types.
The CAN APIs provide all of the functions needed by the application to implement an interrupt-driven CAN stack. These functions may be used to control any of the available CAN ports on a MSP432E4 microcontroller, and can be used with one port without causing conflicts with the other port.
The CAN module is disabled by default, so the CANInit() function must be called before any other CAN functions are called. This call initializes the message objects to a safe state prior to enabling the controller on the CAN bus. Also, the bit timing values must be programmed prior to enabling the CAN controller. The CANSetBitTiming() function should be called with the appropriate bit timing values for the CAN bus. Once these two functions have been called, a CAN controller can be enabled using CANEnable() and later disabled using CANDisable() if needed. Calling CANDisable() does not reinitialize a CAN controller, so it can be used to temporarily remove a CAN controller from the bus.
The CAN controller is highly configurable and can be programmed to automatically transmit and receive CAN messages under certain conditions. Message objects allow the application to perform some actions automatically without interaction from the microcontroller. Some examples of these actions are the following:
To configure message objects to perform any of these actions, the application must first set up one of the 32 message objects using CANMessageSet(). This function must be used to configure a message object to send data, or to configure a message object to receive data. Each message object can be configured to generate interrupts on transmission or reception of CAN messages.
When data is received from the CAN bus, the application can use the CANMessageGet() function to read the received message. This function can also be used to read a message object that is already configured in order to populate a message structure prior to making changes to the configuration of a message object. Reading the message object using this function also clears any pending interrupt on the message object.
Once a message object has been configured using CANMessageSet(), the message object has been allocated and continues to perform its programmed function unless it is released by a call to CANMessageClear(). The application is not required to clear out a message object before setting it with a new configuration, because each time CANMessageSet() is called, it overwrites any previously programmed configuration.
The 32 message objects are identical except for priority. The lowest numbered message objects have the highest priority. Priority affects operation in two ways. First, if multiple actions are ready at the same time, the one with the highest priority message object occurs first. And second, when multiple message objects have interrupts pending, the highest priority is presented first when reading the interrupt status. It is up to the application to manage the 32 message objects as a resource, and determine the best method for allocating and releasing them.
The CAN controller can generate interrupts on several conditions:
An interrupt handler must be installed in order to process CAN interrupts. If dynamic interrupt configuration is desired, the CANIntRegister() can be used to register the interrupt handler. This function places the vector in a RAM-based vector table. However, if the application uses a pre-loaded vector table in flash, then the CAN controller handler should be entered in the appropriate slot in the vector table. In this case, CANIntRegister() is not needed, but the interrupt must be enabled on the host processor master interrupt controller using the IntEnable() function. The CAN module interrupts are enabled using the CANIntEnable() function. They can be disabled by using the CANIntDisable() function.
Once CAN interrupts are enabled, the handler is invoked whenever a CAN interrupt is triggered. The handler can determine which condition caused the interrupt by using the CANIntStatus() function. Multiple conditions can be pending when an interrupt occurs, so the handler must be designed to process all pending interrupt conditions before exiting. Each interrupt condition must be cleared before exiting the handler. There are two ways to do this. The CANIntClear() function clears a specific interrupt condition without further action required by the handler. However, the handler can also clear the condition by performing certain actions. If the interrupt is a status interrupt, the interrupt can be cleared by reading the status register with CANStatusGet(). If the interrupt is caused by one of the message objects, then it can be cleared by reading the message object using CANMessageGet().
There are several status registers that can be used to help the application manage the controller. The status registers are read using the CANStatusGet() function. There is a controller status register that provides general status information such as error or warning conditions. There are also several status registers that provide information about all of the message objects at once using a 32-bit bit map of the status, with one bit representing each message object. These status registers can be used to determine:
Bus error conditions when using CAN require special handling by the application, especially in cases where the CAN controller has gone into a bus-off condition. The CAN specification requires that a controller that has seen its error counters go above 256 transmit errors removes itself from the bus and enters a bus-off state. This state is indicated when the CANStatusGet() function returns the value CAN_STATUS_BUS_OFF. There are other warning levels (CAN_STATUS_EWARN and CAN_STATUS_EPASS) that occur before a bus-off condition that indicate something is wrong on the CAN bus. After entering the bus-off condition, the CAN controller automatically disables itself just as if the application had called CANDisable(). To exit the bus-off condition, the application must call CANEnable() and then wait for the CAN_STATUS_BUS_OFF condition to clear. If the bus-off condition does not clear, then there is likely some physical condition or bit timing issue causing the controller to be unable to function properly. There is no way to shorten this sequence as this is the method for recovering from a bus-off condition specified in the CAN 2.0 specification.
Example:
This section explains how to configure the CAN message objects in various modes using the CANMessageSet() and CANMessageGet() APIs. The configuration of a message object is determined by two parameters that are passed into the CANMessageSet() API. These are the tCANMsgObject structure and the tMsgObjType type field. It is important to note that the ulObjID parameter is the index of one of the 32 message objects that are available and is not the message object's identifier.
Message objects can be defined as one of five types based on the needs of the application. They are defined in the tMsgObjType enumeration and can only be one of those values. The simplest of the message object types are MSG_OBJ_TYPE_TX and MSG_OBJ_TYPE_RX which are used to send or receive messages for a given message identifier or a range of identifiers. The message type MSG_OBJ_TYPE_TX_REMOTE is used to transmit a remote request for data from another CAN node on the network. These message objects do not transmit any data but once they send the request, they automatically turn into receive message object and wait for data from a remote CAN device. The message type MSG_OBJ_TYPE_RX_REMOTE is the receiving end of a remote request, and receives remote requests for data and generates an interrupt to let the application know when to supply and transmit data back to the CAN controller that issued the remote request for data. The message type MSG_OBJ_TYPE_RXTX_REMOTE is similar to the MSG_OBJ_TYPE_RX_REMOTE except that it automatically responds with data that the application placed in the message object.
The remaining information used to configure a CAN message object is contained in the tCANMsgObject structure which is used when calling CANMessageSet() or is filled by data read from the message object when calling CANMessageGet(). The CAN message identifier is simply stored into the ulMsgID member of the tCANMsgObject structure and is the 11- or 20-bit CAN identifier for this message object. The ulMsgIDMask is the mask that is used in combination with the ulMsgID value to determine a match when the MSG_OBJ_USE_ID_FILTER flag is set for a message object. The ulMsgIDMask is ignored if MSG_OBJ_USE_ID_FILTER flag is not set. The last of the configuration parameters are specified in the ulFlags which are defined as a combination of the MSG_OBJ_* values. The MSG_OBJ_TX_INT_ENABLE and MSG_OBJ_RX_INT_ENABLE flags enable transmit complete or receive data interrupts. If the CAN network is only using extended (20-bit) identifiers, then the MSG_OBJ_EXTENDED_ID flag should be specified. The CANMessageSet() function forces this flag to be set if the length of the identifier is greater than an 11-bit identifier can hold. The MSG_OBJ_USE_ID_FILTER is used to enable filtering based on the message identifiers as message are seen by the CAN controller. The combination of ulMsgID and ulMsgIDMask determines if a message is accepted for a given message object. In some cases it may be necessary to add a filter based on the direction of the message, so in these cases, the MSG_OBJ_USE_DIR_FILTER is used to only accept the direction specified in the message type. Another additional filter flag is MSG_OBJ_USE_EXT_FILTER which filters on only extended identifiers. In a mixed 11-bit and 20-bit identifier system, this parameter prevents an 11-bit identifier from being confused with a 20-bit identifier of the same value. It is not necessary to specify this parameter if there are only extended identifiers being used in the system. To determine if the incoming message identifier matches a given message object, the incoming message identifier is ANDed with ulMsgIDMask and compared with ulMsgID. The "C" logic would be the following:
The last of the flags to affect CANMessageSet() is the MSG_OBJ_FIFO flag. This flag is used when combining multiple message objects in a FIFO. This flag is useful when an application must receive more than the 8 bytes of data that can be received by a single CAN message object. It can also be used to reduce the likelihood of causing an overrun of data on a single message object that may be receiving data faster than the application can handle when using a single message object. If multiple message objects are going to be used in a FIFO, they must be read in sequential order based on the message object number and have the exact same message identifiers and filtering values. All but the last of the message objects in a FIFO should have the MSG_OBJ_FIFO flag set and the last message object in the FIFO should not have the MSG_OBJ_FIFO flag set, indicating that it is the last entry in the FIFO. See the CAN FIFO configuration example in the Programming Examples section of this document.
The remaining flags are all used when calling CANMessageGet() when reading data or checking the status of a message object. If the MSG_OBJ_NEW_DATA flag is set in the tCANMsgObject ulFlags variable then the data returned was new and not stale data from a previous call to CANMessageGet(). If the MSG_OBJ_DATA_LOST flag is set, then data was lost since this message object was last read with CANMessageGet(). The MSG_OBJ_REMOTE_FRAME flag is set if the message object was configured as a remote message object and a remote request was received.
When sending or receiving data, the last two variables define the size and a pointer to the data used by CANMessageGet() and CANMessageSet(). The ulMsgLen variable in tCANMsgObject specifies the number of bytes to send when calling CANMessageSet() and the number of bytes to read when calling CANMessageGet(). The pucMsgData variable in tCANMsgObject is the pointer to the data to send ulMsgLen bytes, or the pointer to the buffer to read ulMsgLen bytes into.
This example code sends out data from CAN controller 0 to be received by CAN controller 1. In order to actually receive the data, an external cable must be connected between the two ports. In this example, both controllers are configured for 1 Mbit operation.
This example code configures a set of CAN message objects in FIFO mode using CAN controller 0.
| #define CAN_MAX_11BIT_MSG_ID 0x7ff |
Referenced by CANMessageSet().
| #define CAN_MAX_BIT_DIVISOR 19 |
Referenced by CANBitRateSet().
| #define CAN_MIN_BIT_DIVISOR 4 |
Referenced by CANBitRateSet().
| #define CAN_MAX_PRE_DIVISOR 1024 |
Referenced by CANBitRateSet().
| #define CAN_MIN_PRE_DIVISOR 1 |
Referenced by CANBitRateSet().
| #define CAN_BIT_VALUE | ( | seg1, | |
| seg2, | |||
| sjw | |||
| ) |
| #define MSG_OBJ_TX_INT_ENABLE 0x00000001 |
This indicates that transmit interrupts are enabled.
Referenced by CANMessageGet(), and CANMessageSet().
| #define MSG_OBJ_RX_INT_ENABLE 0x00000002 |
This indicates that receive interrupts are enabled.
Referenced by CANMessageGet(), and CANMessageSet().
| #define MSG_OBJ_EXTENDED_ID 0x00000004 |
This indicates that a message object is using an extended identifier.
Referenced by CANMessageGet(), and CANMessageSet().
| #define MSG_OBJ_USE_ID_FILTER 0x00000008 |
This indicates that a message object is using filtering based on the object's message identifier.
Referenced by CANMessageGet(), and CANMessageSet().
| #define MSG_OBJ_NEW_DATA 0x00000080 |
This indicates that new data was available in the message object.
| #define MSG_OBJ_DATA_LOST 0x00000100 |
This indicates that data was lost since this message object was last read.
Referenced by CANMessageGet().
| #define MSG_OBJ_USE_DIR_FILTER (0x00000010 | MSG_OBJ_USE_ID_FILTER) |
This indicates that a message object uses or is using filtering based on the direction of the transfer. If the direction filtering is used, then ID filtering must also be enabled.
Referenced by CANMessageGet(), and CANMessageSet().
| #define MSG_OBJ_USE_EXT_FILTER (0x00000020 | MSG_OBJ_USE_ID_FILTER) |
This indicates that a message object uses or is using message identifier filtering based on the extended identifier. If the extended identifier filtering is used, then ID filtering must also be enabled.
Referenced by CANMessageGet(), and CANMessageSet().
| #define MSG_OBJ_REMOTE_FRAME 0x00000040 |
This indicates that a message object is a remote frame.
Referenced by CANMessageGet().
| #define MSG_OBJ_FIFO 0x00000200 |
This indicates that this message object is part of a FIFO structure and not the final message object in a FIFO.
Referenced by CANMessageSet().
| #define MSG_OBJ_NO_FLAGS 0x00000000 |
This indicates that a message object has no flags set.
Referenced by CANMessageGet().
| #define MSG_OBJ_STATUS_MASK (MSG_OBJ_NEW_DATA | MSG_OBJ_DATA_LOST) |
This define is used with the flag values to allow checking only status flags and not configuration flags.
| #define CAN_INT_ERROR 0x00000008 |
This flag is used to allow a CAN controller to generate error interrupts.
| #define CAN_INT_STATUS 0x00000004 |
This flag is used to allow a CAN controller to generate status interrupts.
| #define CAN_INT_MASTER 0x00000002 |
This flag is used to allow a CAN controller to generate any CAN interrupts. If this is not set, then no interrupts are generated by the CAN controller.
| #define CAN_STATUS_BUS_OFF 0x00000080 |
CAN controller has entered a Bus Off state.
| #define CAN_STATUS_EWARN 0x00000040 |
CAN controller error level has reached warning level.
| #define CAN_STATUS_EPASS 0x00000020 |
CAN controller error level has reached error passive level.
| #define CAN_STATUS_RXOK 0x00000010 |
A message was received successfully since the last read of this status.
| #define CAN_STATUS_TXOK 0x00000008 |
A message was transmitted successfully since the last read of this status.
| #define CAN_STATUS_LEC_MSK 0x00000007 |
This is the mask for the last error code field.
| #define CAN_STATUS_LEC_NONE 0x00000000 |
There was no error.
| #define CAN_STATUS_LEC_STUFF 0x00000001 |
A bit stuffing error has occurred.
| #define CAN_STATUS_LEC_FORM 0x00000002 |
A formatting error has occurred.
| #define CAN_STATUS_LEC_ACK 0x00000003 |
An acknowledge error has occurred.
| #define CAN_STATUS_LEC_BIT1 0x00000004 |
The bus remained a bit level of 1 for longer than is allowed.
| #define CAN_STATUS_LEC_BIT0 0x00000005 |
The bus remained a bit level of 0 for longer than is allowed.
| #define CAN_STATUS_LEC_CRC 0x00000006 |
A CRC error has occurred.
| #define CAN_STATUS_LEC_MASK 0x00000007 |
This is the mask for the CAN Last Error Code (LEC).
| enum tCANIntStsReg |
This data type is used to identify the interrupt status register. This is used when calling the CANIntStatus() function.
| Enumerator | |
|---|---|
| CAN_INT_STS_CAUSE | Read the CAN interrupt status information. |
| CAN_INT_STS_OBJECT | Read a message object's interrupt status. |
| enum tCANStsReg |
This data type is used to identify which of several status registers to read when calling the CANStatusGet() function.
| enum tMsgObjType |
This definition is used to determine the type of message object that is set up via a call to the CANMessageSet() API.
| void CANInit | ( | uint32_t | ui32Base | ) |
Initializes the CAN controller after reset.
| ui32Base | is the base address of the CAN controller. |
After reset, the CAN controller is left in the disabled state. However, the memory used for message objects contains undefined values and must be cleared prior to enabling the CAN controller the first time. This prevents unwanted transmission or reception of data before the message objects are configured. This function must be called before enabling the controller the first time.
References ASSERT, CAN_CTL_INIT, CAN_IF1CMSK_ARB, CAN_IF1CMSK_CLRINTPND, CAN_IF1CMSK_CONTROL, CAN_IF1CMSK_NEWDAT, CAN_IF1CMSK_WRNRD, CAN_IF1CRQ_BUSY, CAN_O_CTL, CAN_O_IF1ARB2, CAN_O_IF1CMSK, CAN_O_IF1CRQ, CAN_O_IF1MCTL, CAN_O_STS, and HWREG.
| void CANEnable | ( | uint32_t | ui32Base | ) |
Enables the CAN controller.
| ui32Base | is the base address of the CAN controller to enable. |
Enables the CAN controller for message processing. Once enabled, the controller automatically transmits any pending frames, and processes any received frames. The controller can be stopped by calling CANDisable(). Prior to calling CANEnable(), CANInit() must have been called to initialize the controller and the CAN bus clock must be configured by calling CANBitTimingSet().
References ASSERT, CAN_CTL_INIT, CAN_O_CTL, and HWREG.
| void CANDisable | ( | uint32_t | ui32Base | ) |
Disables the CAN controller.
| ui32Base | is the base address of the CAN controller to disable. |
Disables the CAN controller for message processing. When disabled, the controller no longer automatically processes data on the CAN bus. The controller can be restarted by calling CANEnable(). The state of the CAN controller and the message objects in the controller are left as they were before this call was made.
References ASSERT, CAN_CTL_INIT, CAN_O_CTL, and HWREG.
| void CANBitTimingGet | ( | uint32_t | ui32Base, |
| tCANBitClkParms * | psClkParms | ||
| ) |
Reads the current settings for the CAN controller bit timing.
| ui32Base | is the base address of the CAN controller. |
| psClkParms | is a pointer to a structure to hold the timing parameters. |
This function reads the current configuration of the CAN controller bit clock timing and stores the resulting information in the structure supplied by the caller. Refer to CANBitTimingSet() for the meaning of the values that are returned in the structure pointed to by psClkParms.
References ASSERT, CAN_BIT_BRP_M, CAN_BIT_SJW_M, CAN_BIT_SJW_S, CAN_BIT_TSEG1_M, CAN_BIT_TSEG1_S, CAN_BIT_TSEG2_M, CAN_BIT_TSEG2_S, CAN_BRPE_BRPE_M, CAN_O_BIT, CAN_O_BRPE, HWREG, tCANBitClkParms::ui32Phase2Seg, tCANBitClkParms::ui32QuantumPrescaler, tCANBitClkParms::ui32SJW, and tCANBitClkParms::ui32SyncPropPhase1Seg.
| uint32_t CANBitRateSet | ( | uint32_t | ui32Base, |
| uint32_t | ui32SourceClock, | ||
| uint32_t | ui32BitRate | ||
| ) |
Sets the CAN bit timing values to a nominal setting based on a desired bit rate.
| ui32Base | is the base address of the CAN controller. |
| ui32SourceClock | is the system clock for the device in Hz. |
| ui32BitRate | is the desired bit rate. |
This function sets the CAN bit timing for the bit rate passed in the ui32BitRate parameter based on the ui32SourceClock parameter. Because the CAN clock is based off of the system clock, the calling function must pass in the source clock rate either by retrieving it from SysCtlClockGet() or using a specific value in Hz. The CAN bit timing is calculated assuming a minimal amount of propagation delay, which works for most cases where the network length is short. If tighter timing requirements or longer network lengths are needed, then the CANBitTimingSet() function is available for full customization of all of the CAN bit timing values. Because not all bit rates can be matched exactly, the bit rate is set to the value closest to the desired bit rate without being higher than the ui32BitRate value.
References ASSERT, CAN_MAX_BIT_DIVISOR, CAN_MAX_PRE_DIVISOR, CAN_MIN_BIT_DIVISOR, and CAN_MIN_PRE_DIVISOR.
| void CANBitTimingSet | ( | uint32_t | ui32Base, |
| tCANBitClkParms * | psClkParms | ||
| ) |
Configures the CAN controller bit timing.
| ui32Base | is the base address of the CAN controller. |
| psClkParms | points to the structure with the clock parameters. |
Configures the various timing parameters for the CAN bus bit timing: Propagation segment, Phase Buffer 1 segment, Phase Buffer 2 segment, and the Synchronization Jump Width. The values for Propagation and Phase Buffer 1 segments are derived from the combination psClkParms->ui32SyncPropPhase1Seg parameter. Phase Buffer 2 is determined from the psClkParms->ui32Phase2Seg parameter. These two parameters, along with psClkParms->ui32SJW are based in units of bit time quanta. The actual quantum time is determined by the psClkParms->ui32QuantumPrescaler value, which specifies the divisor for the CAN module clock.
The total bit time, in quanta, is the sum of the two Seg parameters, as follows:
bit_time_q = ui32SyncPropPhase1Seg + ui32Phase2Seg + 1
Note that the Sync_Seg is always one quantum in duration, and is added to derive the correct duration of Prop_Seg and Phase1_Seg.
The equation to determine the actual bit rate is as follows:
CAN Clock / ((ui32SyncPropPhase1Seg + ui32Phase2Seg + 1) * (ui32QuantumPrescaler))
Thus with ui32SyncPropPhase1Seg = 4, ui32Phase2Seg = 1, ui32QuantumPrescaler = 2 and an 8 MHz CAN clock, the bit rate is (8 MHz) / ((5 + 2 + 1) * 2) or 500 Kbit/sec.
References ASSERT, CAN_BIT_BRP_M, CAN_BIT_SJW_M, CAN_BIT_SJW_S, CAN_BIT_TSEG1_M, CAN_BIT_TSEG1_S, CAN_BIT_TSEG2_M, CAN_BIT_TSEG2_S, CAN_BRPE_BRPE_M, CAN_CTL_CCE, CAN_CTL_INIT, CAN_O_BIT, CAN_O_BRPE, CAN_O_CTL, HWREG, tCANBitClkParms::ui32Phase2Seg, tCANBitClkParms::ui32QuantumPrescaler, tCANBitClkParms::ui32SJW, and tCANBitClkParms::ui32SyncPropPhase1Seg.
| void CANIntRegister | ( | uint32_t | ui32Base, |
| void(*)(void) | pfnHandler | ||
| ) |
Registers an interrupt handler for the CAN controller.
| ui32Base | is the base address of the CAN controller. |
| pfnHandler | is a pointer to the function to be called when the enabled CAN interrupts occur. |
This function registers the interrupt handler in the interrupt vector table, and enables CAN interrupts on the interrupt controller; specific CAN interrupt sources must be enabled using CANIntEnable(). The interrupt handler being registered must clear the source of the interrupt using CANIntClear().
If the application is using a static interrupt vector table stored in flash, then it is not necessary to register the interrupt handler this way. Instead, IntEnable() is used to enable CAN interrupts on the interrupt controller.
References ASSERT.
| void CANIntUnregister | ( | uint32_t | ui32Base | ) |
Unregisters an interrupt handler for the CAN controller.
| ui32Base | is the base address of the controller. |
This function unregisters the previously registered interrupt handler and disables the interrupt in the interrupt controller.
References ASSERT.
| void CANIntEnable | ( | uint32_t | ui32Base, |
| uint32_t | ui32IntFlags | ||
| ) |
Enables individual CAN controller interrupt sources.
| ui32Base | is the base address of the CAN controller. |
| ui32IntFlags | is the bit mask of the interrupt sources to be enabled. |
This function enables specific interrupt sources of the CAN controller. Only enabled sources cause a processor interrupt.
The ui32IntFlags parameter is the logical OR of any of the following:
In order to generate any interrupts, CAN_INT_MASTER must be enabled. Further, for any particular transaction from a message object to generate an interrupt, that message object must have interrupts enabled (see CANMessageSet()). CAN_INT_ERROR generates an interrupt if the controller enters the ``bus off'' condition, or if the error counters reach a limit. CAN_INT_STATUS generates an interrupt under quite a few status conditions and may provide more interrupts than the application needs to handle. When an interrupt occurs, use CANIntStatus() to determine the cause.
References ASSERT, CAN_CTL_EIE, CAN_CTL_IE, CAN_CTL_SIE, CAN_O_CTL, and HWREG.
| void CANIntDisable | ( | uint32_t | ui32Base, |
| uint32_t | ui32IntFlags | ||
| ) |
Disables individual CAN controller interrupt sources.
| ui32Base | is the base address of the CAN controller. |
| ui32IntFlags | is the bit mask of the interrupt sources to be disabled. |
Disables the specified CAN controller interrupt sources. Only enabled interrupt sources can cause a processor interrupt.
The ui32IntFlags parameter has the same definition as in the CANIntEnable() function.
References ASSERT, CAN_CTL_EIE, CAN_CTL_IE, CAN_CTL_SIE, CAN_O_CTL, and HWREG.
| uint32_t CANIntStatus | ( | uint32_t | ui32Base, |
| tCANIntStsReg | eIntStsReg | ||
| ) |
Returns the current CAN controller interrupt status.
| ui32Base | is the base address of the CAN controller. |
| eIntStsReg | indicates which interrupt status register to read |
This function returns the value of one of two interrupt status registers. The interrupt status register read is determined by the eIntStsReg parameter, which can have one of the following values:
CAN_INT_STS_CAUSE returns the value of the controller interrupt register and indicates the cause of the interrupt. The value returned is CAN_INT_INTID_STATUS if the cause is a status interrupt. In this case, the status register is read with the CANStatusGet() function. Calling this function to read the status also clears the status interrupt. If the value of the interrupt register is in the range 1-32, then this indicates the number of the highest priority message object that has an interrupt pending. The message object interrupt can be cleared by using the CANIntClear() function, or by reading the message using CANMessageGet() in the case of a received message. The interrupt handler can read the interrupt status again to make sure all pending interrupts are cleared before returning from the interrupt.
CAN_INT_STS_OBJECT returns a bit mask indicating which message objects have pending interrupts. This value can be used to discover all of the pending interrupts at once, as opposed to repeatedly reading the interrupt register by using CAN_INT_STS_CAUSE.
References ASSERT, CAN_INT_STS_CAUSE, CAN_INT_STS_OBJECT, CAN_MSG1INT_INTPND_M, CAN_O_INT, CAN_O_MSG1INT, CAN_O_MSG2INT, and HWREG.
| void CANIntClear | ( | uint32_t | ui32Base, |
| uint32_t | ui32IntClr | ||
| ) |
Clears a CAN interrupt source.
| ui32Base | is the base address of the CAN controller. |
| ui32IntClr | is a value indicating which interrupt source to clear. |
This function can be used to clear a specific interrupt source. The ui32IntClr parameter must be one of the following values:
It is not necessary to use this function to clear an interrupt. This function is only used if the application wants to clear an interrupt source without taking the normal interrupt action.
Normally, the status interrupt is cleared by reading the controller status using CANStatusGet(). A specific message object interrupt is normally cleared by reading the message object using CANMessageGet().
References ASSERT, CAN_IF1CMSK_CLRINTPND, CAN_IF1CRQ_BUSY, CAN_IF1CRQ_MNUM_M, CAN_INT_INTID_STATUS, CAN_O_IF1CMSK, CAN_O_IF1CRQ, CAN_O_STS, and HWREG.
| void CANRetrySet | ( | uint32_t | ui32Base, |
| bool | bAutoRetry | ||
| ) |
Sets the CAN controller automatic retransmission behavior.
| ui32Base | is the base address of the CAN controller. |
| bAutoRetry | enables automatic retransmission. |
This function enables or disables automatic retransmission of messages with detected errors. If bAutoRetry is true, then automatic retransmission is enabled, otherwise it is disabled.
References ASSERT, CAN_CTL_DAR, CAN_O_CTL, and HWREG.
| bool CANRetryGet | ( | uint32_t | ui32Base | ) |
Returns the current setting for automatic retransmission.
| ui32Base | is the base address of the CAN controller. |
This function reads the current setting for automatic retransmission in the CAN controller and returns it to the caller.
References ASSERT, CAN_CTL_DAR, CAN_O_CTL, and HWREG.
| uint32_t CANStatusGet | ( | uint32_t | ui32Base, |
| tCANStsReg | eStatusReg | ||
| ) |
Reads one of the controller status registers.
| ui32Base | is the base address of the CAN controller. |
| eStatusReg | is the status register to read. |
This function reads a status register of the CAN controller and returns it to the caller. The different status registers are:
When reading the main controller status register, a pending status interrupt is cleared. This parameter is used in the interrupt handler for the CAN controller if the cause is a status interrupt. The controller status register fields are as follows:
The remaining status registers consist of 32-bit-wide bit maps to the message objects. They can be used to quickly obtain information about the status of all the message objects without needing to query each one. They contain the following information:
References ASSERT, CAN_O_MSG1VAL, CAN_O_MSG2VAL, CAN_O_NWDA1, CAN_O_NWDA2, CAN_O_STS, CAN_O_TXRQ1, CAN_O_TXRQ2, CAN_STS_CONTROL, CAN_STS_LEC_M, CAN_STS_MSGVAL, CAN_STS_NEWDAT, CAN_STS_RXOK, CAN_STS_TXOK, CAN_STS_TXREQUEST, and HWREG.
| bool CANErrCntrGet | ( | uint32_t | ui32Base, |
| uint32_t * | pui32RxCount, | ||
| uint32_t * | pui32TxCount | ||
| ) |
Reads the CAN controller error counter register.
| ui32Base | is the base address of the CAN controller. |
| pui32RxCount | is a pointer to storage for the receive error counter. |
| pui32TxCount | is a pointer to storage for the transmit error counter. |
This function reads the error counter register and returns the transmit and receive error counts to the caller along with a flag indicating if the controller receive counter has reached the error passive limit. The values of the receive and transmit error counters are returned through the pointers provided as parameters.
After this call, *pui32RxCount holds the current receive error count and *pui32TxCount holds the current transmit error count.
References ASSERT, CAN_ERR_REC_M, CAN_ERR_REC_S, CAN_ERR_RP, CAN_ERR_TEC_M, CAN_ERR_TEC_S, CAN_O_ERR, and HWREG.
| void CANMessageSet | ( | uint32_t | ui32Base, |
| uint32_t | ui32ObjID, | ||
| tCANMsgObject * | psMsgObject, | ||
| tMsgObjType | eMsgType | ||
| ) |
Configures a message object in the CAN controller.
| ui32Base | is the base address of the CAN controller. |
| ui32ObjID | is the object number to configure (1-32). |
| psMsgObject | is a pointer to a structure containing message object settings. |
| eMsgType | indicates the type of message for this object. |
This function is used to configure any one of the 32 message objects in the CAN controller. A message object can be configured to be any type of CAN message object as well as to use automatic transmission and reception. This call also allows the message object to be configured to generate interrupts on completion of message receipt or transmission. The message object can also be configured with a filter/mask so that actions are only taken when a message that meets certain parameters is seen on the CAN bus.
The eMsgType parameter must be one of the following values:
The message object pointed to by psMsgObject must be populated by the caller, as follows:
Example: To send a data frame or remote frame (in response to a remote request), take the following steps:
Example: To receive a specific data frame, take the following steps:
If you specify a message object buffer that already contains a message definition, it is overwritten.
References ASSERT, CAN_IF1ARB1_ID_M, CAN_IF1ARB2_DIR, CAN_IF1ARB2_ID_M, CAN_IF1ARB2_MSGVAL, CAN_IF1ARB2_XTD, CAN_IF1CMSK_ARB, CAN_IF1CMSK_CONTROL, CAN_IF1CMSK_DATAA, CAN_IF1CMSK_DATAB, CAN_IF1CMSK_MASK, CAN_IF1CMSK_WRNRD, CAN_IF1CRQ_BUSY, CAN_IF1MCTL_DLC_M, CAN_IF1MCTL_EOB, CAN_IF1MCTL_RMTEN, CAN_IF1MCTL_RXIE, CAN_IF1MCTL_TXIE, CAN_IF1MCTL_TXRQST, CAN_IF1MCTL_UMASK, CAN_IF1MSK1_IDMSK_M, CAN_IF1MSK2_IDMSK_M, CAN_IF1MSK2_MDIR, CAN_IF1MSK2_MXTD, CAN_MAX_11BIT_MSG_ID, CAN_O_IF1CRQ, HWREG, MSG_OBJ_EXTENDED_ID, MSG_OBJ_FIFO, MSG_OBJ_RX_INT_ENABLE, MSG_OBJ_TX_INT_ENABLE, MSG_OBJ_TYPE_RX, MSG_OBJ_TYPE_RX_REMOTE, MSG_OBJ_TYPE_RXTX_REMOTE, MSG_OBJ_TYPE_TX, MSG_OBJ_TYPE_TX_REMOTE, MSG_OBJ_USE_DIR_FILTER, MSG_OBJ_USE_EXT_FILTER, MSG_OBJ_USE_ID_FILTER, tCANMsgObject::ui32Flags, tCANMsgObject::ui32MsgID, tCANMsgObject::ui32MsgIDMask, and tCANMsgObject::ui32MsgLen.
| void CANMessageGet | ( | uint32_t | ui32Base, |
| uint32_t | ui32ObjID, | ||
| tCANMsgObject * | psMsgObject, | ||
| bool | bClrPendingInt | ||
| ) |
Reads a CAN message from one of the message object buffers.
| ui32Base | is the base address of the CAN controller. |
| ui32ObjID | is the object number to read (1-32). |
| psMsgObject | points to a structure containing message object fields. |
| bClrPendingInt | indicates whether an associated interrupt should be cleared. |
This function is used to read the contents of one of the 32 message objects in the CAN controller and return it to the caller. The data returned is stored in the fields of the caller-supplied structure pointed to by psMsgObject. The data consists of all of the parts of a CAN message, plus some control and status information.
Normally, this function is used to read a message object that has received and stored a CAN message with a certain identifier. However, this function could also be used to read the contents of a message object in order to load the fields of the structure in case only part of the structure must be changed from a previous setting.
When using CANMessageGet(), all of the same fields of the structure are populated in the same way as when the CANMessageSet() function is used, with the following exceptions:
psMsgObject->ui32Flags:
References ASSERT, CAN_IF1ARB2_DIR, CAN_IF1ARB2_ID_M, CAN_IF1ARB2_XTD, CAN_IF1CMSK_ARB, CAN_IF1CMSK_CLRINTPND, CAN_IF1CMSK_CONTROL, CAN_IF1CMSK_DATAA, CAN_IF1CMSK_DATAB, CAN_IF1CMSK_MASK, CAN_IF1CRQ_BUSY, CAN_IF1CRQ_MNUM_M, CAN_IF1MCTL_DLC_M, CAN_IF1MCTL_MSGLST, CAN_IF1MCTL_NEWDAT, CAN_IF1MCTL_RXIE, CAN_IF1MCTL_TXIE, CAN_IF1MCTL_TXRQST, CAN_IF1MCTL_UMASK, CAN_IF1MSK2_IDMSK_M, CAN_IF1MSK2_MDIR, CAN_IF1MSK2_MXTD, CAN_O_IF2ARB1, CAN_O_IF2ARB2, CAN_O_IF2CMSK, CAN_O_IF2CRQ, CAN_O_IF2MCTL, CAN_O_IF2MSK1, CAN_O_IF2MSK2, HWREG, MSG_OBJ_DATA_LOST, MSG_OBJ_EXTENDED_ID, MSG_OBJ_NO_FLAGS, MSG_OBJ_REMOTE_FRAME, MSG_OBJ_RX_INT_ENABLE, MSG_OBJ_TX_INT_ENABLE, MSG_OBJ_USE_DIR_FILTER, MSG_OBJ_USE_EXT_FILTER, MSG_OBJ_USE_ID_FILTER, tCANMsgObject::ui32Flags, tCANMsgObject::ui32MsgID, tCANMsgObject::ui32MsgIDMask, and tCANMsgObject::ui32MsgLen.
| void CANMessageClear | ( | uint32_t | ui32Base, |
| uint32_t | ui32ObjID | ||
| ) |
Clears a message object so that it is no longer used.
| ui32Base | is the base address of the CAN controller. |
| ui32ObjID | is the message object number to disable (1-32). |
This function frees the specified message object from use. Once a message object has been ``cleared,'' it no longer automatically sends or receives messages, nor does it generate interrupts.
References ASSERT, CAN_IF1CMSK_ARB, CAN_IF1CMSK_WRNRD, CAN_IF1CRQ_BUSY, CAN_IF1CRQ_MNUM_M, CAN_O_IF1ARB1, CAN_O_IF1ARB2, CAN_O_IF1CMSK, CAN_O_IF1CRQ, and HWREG.