Stellaris CAN 模块 控制器局域网（CAN）

控制器局域网（CAN）API 提供了用于访问 Stellaris CAN 模块的函数集。
函数能对 CAN控制器、报文对象进行配置和对 CAN 中断进行管理。Stellaris CAN 模块提供了 CAN 数据链接层的硬件处理。

因为它能被配置成具有报文过滤器并能预载报文数据，所以它能在总线上自动发送和接收报文，并相应用地通知应用。

它能自动地处理 CRC 的产生和检查、错误处理、和重发 CAN 报文。

报文对象存放在 CAN 控制器中，并且它能提供在 CAN 总线上的 CAN 模块的主接口。

这 32 个报文对象中的每一个都能被编程成可以处理一个独立的报文 ID，或能在同一个 ID上被一起链接成一个帧序列。报文标识符过滤器提供了能被编程为与任何或全部报文 ID 位相匹配的屏蔽，和帧类型。

驱动程序包含在 src/can.c 中，src/can.h 包含应用使用的 API 定义。

API 函数
数据结构
-tCANBitClkParms；
-tCANMsgObject。
定义
-MSG_OBJ_STATUS_MASK。
枚举
-tCANIntFlags；
-tCANIntStsReg；
-tCANObjFlags；
-tCANStatusCtrl；
-tCANStsReg；
-tMsgObjType。
函数
-void CANBitTimingGet (unsigned long ulBase, tCANBitClkParms *pClkParms)；
-void CANBitTimingSet (unsigned long ulBase, tCANBitClkParms *pClkParms)；
-void CANDisable (unsigned long ulBase)；
-void CANEnable (unsigned long ulBase)；
-tBoolean CANErrCntrGet (unsigned long ulBase, unsigned long *pulRxCount,
unsigned long *pulTxCount)；
-void CANInit (unsigned long ulBase)；
-void CANIntClear (unsigned long ulBase, unsigned long ulIntClr)
-void CANIntDisable (unsigned long ulBase, unsigned long ulIntFlags)；
-void CANIntEnable (unsigned long ulBase, unsigned long ulIntFlags)；
-void CANIntRegister (unsigned long ulBase, void (*pfnHandler)(void))；
-unsigned long CANIntStatus (unsigned long ulBase, tCANIntStsReg eIntStsReg)；
-void CANIntUnregister (unsigned long ulBase)；
-void CANMessageClear (unsigned long ulBase, unsigned long ulObjID)；
-void CANMessageGet (unsigned long ulBase, unsigned long ulObjID, tCANMsgObject
*pMsgObject, tBoolean bClrPendingInt)；
-void CANMessageSet (unsigned long ulBase, unsigned long ulObjID, tCANMsgObject
*pMsgObject, tMsgObjType eMsgType)；
-tBoolean CANRetryGet (unsigned long ulBase)；
-void CANRetrySet (unsigned long ulBase, tBoolean bAutoRetry)；
-unsigned long CANStatusGet (unsigned long ulBase, tCANStsReg eStatusReg)。

CAN API 提供了应用所需要用来实施一个中断驱动 CAN 堆栈的全部函数。
我们能使用
这些函数控制 Stellaris 微控制器的任何一个可用的 CAN 端口，并且函数能与一个端口使用
而不会与其它端口造成冲突。
默认时 CAN 模块被禁止，因此在调用任何其他的 CAN 函数前，必须要先调用 CANInit()
函数。这样就能在使能 CAN 总线上的控制器前把报文对象初始化到一个安全的状态。同样，
在使能 CAN 控制器前，必须要对位时序值进行编程。
在位时序值被编程为一个恬当的值时，
应该要调用 CAN 总线的 CANSetBitTiming()函数。一旦调用完这二个函数，那么就可使用
CANEnable()将 CAN 控制器使能，如有需要，稍后则可使用 CANDisable()将其关闭。
调用
CANDisable()并不会重新初始化一个 CAN 控制器，因此我们可以使用它来暂时把 CAN 控
制器从总线上移除。

CAN 控制器具有很高的可配置性并且包含 32 个报文对象，在某些条件下这些报文对象
能被编程为自动发送和接收 CAN 报文。报文对象允许应用程序自动执行一些操作而无需与
微控制器进行交互。以下是这些操作的一些范例：
-立即发送一个数据帧；
-当在 CAN 总线上发现（seen）一个正在匹配的远程帧时，发送一个数据帧；
-接收一个特定的数据帧；
-接收与某个标识符样式匹配的数据帧

为了把报文对象配置成可以执行这些操作中的任何一个操作，应用程序必须首先要使用
CANMessageSet()来设置 32 个报文对象中的其中一个报文对象。这个函数能把一个报文对
象配置成可以发送数据或接收数据。每一个报文对象可以被配置成在发送或接收 CAN 报文
时产生中断。
当从 CAN 总线接收到数据时，应用程序可以使用 CANMessageGet()函数读取到所接收
到的报文。同样这函数也能读取这样一个报文：在改变报文对象的配置前，报文已被配置以
便定位一个报文结构。使用这个函数读取报文对象也将会清除任何报文对象中正在挂起的中
断。
一旦已使用 CANMessageSet()来完成对一个报文对象的配置，那么此函数分配报文对象
并继续执行其编程功能，除非通过调用 CANMessageClear()将其释放。在对报文对象进行新
配置前，无需请求应用程序清除报文对象，因此每次调用 CANMessageSet()时，它将会覆盖
任何之前被编程的配置。
32 个报文对象是相同的，优先级除外。最小编号的报文对象具有最高的优先级。优先
级以二种方式影响着操作。第一种，如果在同一时间准备好多个操作，那么具有最高优先级
的报文对象将会首先发生。第二种，多个报文对象正在挂起中断时，那么在读取中断状态时，
具有最高优先级的报文对象将会首先出现。由应用负责把 32 个报文对象作为一个源来管理
并确定分配和释放它们的最佳途径。

CAN 控制器在下列条件下能够产生中断：
-当任何一个报文对象发送一个报文时；
-当任何一个报文对象接收一个报文时；
-在警告条件如一个错误计数器达到了限值或出现多个总线错误时；
-在控制器错误条件如进入总线关闭状态时。

为了能对 CAN 中断作出处理，必须要安装一个中断处理程序。
如果需要一个动态中断
配置，那么可以使用 CANIntRegister()来注册中断处理程序。
这将会把向量表放置在一个基
于 RAM 的向量表中。然后，如果应用程序使用 Flash 中的预载向量表，那么 CAN 控制器
处理程序应该处于向量表中的恬当位置。
在这种情况下，不需要使用 CANIntRegister()，但将要使用 IntEnable()函数来使能在主处理器主机中断控制器的中断。
使用 CANIntEnable()函数就可使能模块中断，而 CANIntDisable()函数则可关闭模块中断。
一旦 CAN 中断使能，只要触发一个 CAN 中断那么就将调用中断处理程序。
通过使用CANIntStatus()函数，处理程序就能确定是由哪一个条件而引起的中断。
当一个中断发生时，多个条件被挂起。因此处理程序必须被设计成在退出前对全部挂起的中断条件进行处理。
在退出处理程序前，必须清除每一个中断条件。
清除中断条件有二种方法。CANIntClear()函数将会清除一个特定的中断条件而无需进行处理程序所要求的进一步操作。
但是，处理程序也能通过执行某些操作来清除中断条件。
如果中断为一个状态中断，那么通过使用CANStatusGet()读取状态寄存器就可以清除中断。
如果中断是由其中一个报文对象引起的，那么使用 CANMessageGet()读取报文对象就可将其清除。

这里有几种状态寄存器能帮助应用程序对控制器进行管理。CANStatusGet()函数能读取
状态寄存器。其中有一个控制器状态寄存器能提供总的状态信息如错误或警告条件。
同样也有几个状态寄存器在使用 32 位状态映射（一位代表着一个报文对象）时能立即提供参报文
对象的全部信息。
这些状态寄存器能确定：

-哪些报文对象未对所接收到的数据进行处理；
-哪些报文对象正在挂起发送请求；
-哪些报文对象被分配为使用。

数据结构文件tCANBitClkParms
定义：
typedef struct
{
unsigned int uSyncPropPhase1Seg;
unsigned int uPhase2Seg;
unsigned int uSJW;
unsigned int uQuantumPrescaler;
}
tCANBitClkParms

成员：
uSyncPropPhase1Seg：这个值保存同步、传播和以 time quanta 来计量的相缓冲区 1 区
（segment）的和。此设置的有效值为 2~16。
uPhase2Seg：这个值保存以 time quanta 来计量的相缓冲区 2 区（segment）的值。
此设置的有效值为 1~8。
uSJW：这个值保存以 time quanta 来计量的再同步跳跃宽度。此设置的有效值为 1~4。
uQuantumPrescaler：这个值保存用来确定time quanta的CAN_CLK分频器。此设置的有效
值范围为1~1023。

此结构是对与设置 CAN 控制器的位时序相关的值进行压缩。当调用 CANGetBitTiming
和 CANSetBitTiming 函数时，使用此结构。

tCANMsgObject
定义
typedef struct
{
unsigned long ulMsgID;
unsigned long ulMsgIDMask;
unsigned long ulFlags;
unsigned long ulMsgLen;
unsigned char *pucMsgData;
}
tCANMsgObject

成员：
ulMsgID 用作 11 或 29 位标识符的 CAN 报文标识符。
ulMsgIDMask 在使能标识符过滤器时所使用的报文标识符屏蔽。
ulFlags 此值保存多个状态标志和 tCANObjFlags 所指定的设置。
ulMsgLen 此值是报文对象中的数据字节数。
pucMsgData 这是指向报文对象的数据的指针。

描述：
此结构是对与 CAN 控制器中的一个 CAN 报文对象相关的项目进行压缩。

定义文件
MSG_OBJ_STATUS_MASK
此定义要与 tCANObjFlags 所枚举的值一起使用，以允许只检查状态标志和非配置标志，

枚举文件
tCANIntFlags
描述
这些定义是用来指定 CANIntEnable()和 CANIntDisable()的中断源。
枚举器
CAN_INT_ERROR 这个标志是用来允许 CAN 控制器产生错误中断。
CAN_INT_STATUS 这个标志是用来允许 CAN 控制器产生状态中断。
CAN_INT_MASTER 这个标志是用来允许 CAN 控制器产生任何 CAN 中断。
如果不设置此标志，那么 CAN 控制器将不会产生中断。

tCANIntStsReg
描述：
这个数据类型是用来识别中断状态寄存器。当调用 CANIntStatus()函数时，就可使用此
数据类型。
枚举器：
CAN_INT_STS_CAUSE 读取 CAN 中断状态信息。
CAN_INT_STS_OBJECT 读取一个报文对象的中断状态。

tCANObjFlags
描述：
当调用 CANMessageSet()和 CANMessageGet()函数时，这些标志由 tCANMsgObject 变
量使用。

枚举器：
MSG_OBJ_TX_INT_ENABLE 这表明应使能或使能发送中断。
MSG_OBJ_RX_INT_ENABLE 这表明应使能或使能接收中断。
MSG_OBJ_EXTENDED_ID 这表明一个报文对象将会使用或正在使用一个扩展标识
符。
MSG_OBJ_USE_ID_FILTER 这表明一个报文对象将会使用或正在使用基于对象的报
文标识符的过滤。
MSG_OBJ_NEW_DATA 这表明报文对象的新数据可用。
MSG_OBJ_DATA_LOST 这表明数据已丢失，因为这个报文对象是最后被读取。
MSG_OBJ_USE_DIR_FILTER 这表明一个报文对象将会使用或正在使用基于传递方
向的过滤。如果使用了方向过滤，那么同样必须要使能
ID 过滤。
MSG_OBJ_USE_EXT_FILTER 这表明一个报文对象将会使用或正在使用基于扩展标
识符的报文标识符过滤。如果使用了扩展标识符，那
么同样必须要使能 ID 过滤。
MSG_OBJ_REMOTE_FRAME 这表明一个报文对象是一个远程帧。
MSG_OBJ_NO_FLAGS 这表明一个报文对象不用设置标志。