varch/doc/cant.md

介绍

cant 是一个用于 C 语言的简单 CAN（Controller Area Network）设备测试模块。从应用层角度对CAN总线进行测试，可以监控数据错误帧、丢帧，同时可以模拟CAN总线负载，确保在总线高压状态下的稳定性。

接口

类型定义

cant_transfer_t 函数指针类型

typedef int (*cant_transfer_t)(uint32_t canid, uint8_t *data, uint16_t length);

类型说明：这是与 CAN 传输相关的函数指针类型，可用于 CAN 数据的发送或接收函数。 参数介绍：

• canid：CAN 消息的标识符。
• data：指向要发送或接收的数据的指针。
• length：数据的长度。 返回值：函数返回一个 int 类型的值，具体含义由实际使用的函数决定。

结构体定义

CANT 结构体

typedef struct 
{
    struct 
    {
        uint8_t channel;
        uint8_t baundrate;
        uint16_t period;                        // `cant_task()` call period
        cant_transfer_t transmit;               // can transmit the drive function
        cant_transfer_t receive;                // can receive hook functions
    } config;
    
    uint16_t busload;
    uint32_t periodbits;
    uint32_t timestamp;

    struct 
    {
        uint32_t canid;
        float compression;
        float rate;
        uint16_t tarload;
        uint32_t gapbase;
        uint32_t gapcount;
        uint32_t curcount;
        uint8_t data[64];
    } dummy;

    struct 
    {
        uint32_t canid;
        uint32_t errcount;
        uint32_t curcount;
        uint32_t vercount;
        uint32_t lstcount;
    } verify;
} CANT;

结构体说明：该结构体用于表示 CAN 设备，包含了 CAN 设备的配置信息、总线负载、时间戳、虚拟数据和验证数据等内容。 子结构体及成员介绍：

• config 子结构体：包含 CAN 设备的配置信息。
  • channel：CAN 总线的通道号。
  • baundrate：CAN 总线的波特率。
  • period：cant_task() 函数的调用周期。
  • transmit：指向 CAN 数据发送函数的指针。
  • receive：指向 CAN 数据接收函数的指针。
• busload：CAN 总线的负载值。
• periodbits：与周期相关的位信息。
• timestamp：时间戳。
• dummy 子结构体：包含 CAN 设备的虚拟数据。
  • canid：CAN 消息的标识符。
  • compression：压缩因子，类型为 float。
  • rate：速率，类型为 float。
  • tarload：目标负载。
  • gapbase：间隙基值。
  • gapcount：间隙计数。
  • curcount：当前计数。
  • data：数据数组，大小为 64 字节。
• verify 子结构体：包含 CAN 设备的验证数据。
  • canid：CAN 消息的标识符。
  • errcount：错误计数。
  • curcount：当前计数。
  • vercount：验证计数。
  • lstcount：上一次计数。

函数

cant_set_dummy_canid 函数

int cant_set_dummy_canid(CANT *cant, uint32_t canid);

函数说明：设置 CAN 设备虚拟数据的 CAN 标识符。 参数介绍：

• cant：指向 CANT 结构体的指针，代表要操作的 CAN 设备。
• canid：要设置的 CAN 标识符。 返回值：
• CANT_E_OK：设置成功。
• CANT_E_INVALID：传入的 cant 指针为 NULL。
• CANT_E_ECANID：传入的 canid 为 0。

cant_set_verify_canid 函数

int cant_set_verify_canid(CANT *cant, uint32_t canid);

函数说明：设置 CAN 设备验证数据的 CAN 标识符。 参数介绍：

• cant：指向 CANT 结构体的指针，代表要操作的 CAN 设备。
• canid：要设置的 CAN 标识符。 返回值：
• CANT_E_OK：设置成功。
• CANT_E_INVALID：传入的 cant 指针为 NULL。
• CANT_E_ECANID：传入的 canid 为 0。

cant_set_busload 函数

int cant_set_busload(CANT *cant, uint16_t load);

函数说明：设置 CAN 设备的总线负载。 参数介绍：

• cant：指向 CANT 结构体的指针，代表要操作的 CAN 设备。
• load：要设置的总线负载值。 返回值：
• CANT_E_OK：设置成功。
• CANT_E_INVALID：传入的 cant 指针为 NULL。

cant_get_busload 函数

int cant_get_busload(CANT *cant, uint16_t *load);

函数说明：获取 CAN 设备的总线负载。 参数介绍：

• cant：指向 CANT 结构体的指针，代表要操作的 CAN 设备。
• load：指向用于存储总线负载值的变量的指针。 返回值：
• CANT_E_OK：获取成功。
• CANT_E_INVALID：传入的 cant 指针为 NULL。
• CANT_E_LOAD：传入的 load 指针为 NULL。

cant_transmit 函数

int cant_transmit(CANT *cant, uint32_t canid, uint8_t *data, uint16_t length);

函数说明：通过 CAN 设备发送数据。 参数介绍：

• cant：指向 CANT 结构体的指针，代表要操作的 CAN 设备。
• canid：要发送数据的 CAN 标识符。
• data：指向要发送的数据的指针。
• length：要发送的数据的长度。 返回值：
• CANT_E_OK：发送成功。
• CANT_E_INVALID：传入的 cant 指针为 NULL。
• CANT_E_DATA：传入的 data 指针为 NULL。
• CANT_E_TRANSMIT：cant 结构体中的 transmit 函数指针为 NULL。
• CANT_E_TRANSFAIL：实际的发送函数返回非零值，表示发送失败。

cant_receive 函数

int cant_receive(CANT *cant, uint32_t canid, uint8_t *data, uint16_t length);

函数说明：通过 CAN 设备接收数据。 参数介绍：

• cant：指向 CANT 结构体的指针，代表要操作的 CAN 设备。
• canid：要接收数据的 CAN 标识符。
• data：指向用于存储接收数据的缓冲区的指针。
• length：要接收的数据的长度。 返回值：
• CANT_E_OK：接收成功。
• CANT_E_INVALID：传入的 cant 指针为 NULL。

cant_init 函数

int cant_init(CANT *cant);

函数说明：初始化 CAN 设备。 参数介绍：

• cant：指向 CANT 结构体的指针，代表要初始化的 CAN 设备。 返回值：
• CANT_E_OK：初始化成功。
• CANT_E_INVALID：传入的 cant 指针为 NULL。

cant_task 函数

int cant_task(CANT *cant);

函数说明：CAN 设备的主任务函数，用于处理 CAN 设备的周期性任务。 参数介绍：

• cant：指向 CANT 结构体的指针，代表要执行任务的 CAN 设备。 返回值：
• CANT_E_OK：任务执行成功。
• CANT_E_INVALID：传入的 cant 指针为 NULL。