varch/doc/cant.md

## 介绍

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

## 接口

### 类型定义

#### `cant_transfer_t` 函数指针类型
```c
typedef int (*cant_transfer_t)(uint32_t canid, uint8_t *data, uint16_t length);
```
**类型说明**：这是与 CAN 传输相关的函数指针类型，可用于 CAN 数据的发送或接收函数。
**参数介绍**：
- `canid`：CAN 消息的标识符。
- `data`：指向要发送或接收的数据的指针。
- `length`：数据的长度。
**返回值**：函数返回一个 `int` 类型的值，具体含义由实际使用的函数决定。

### 结构体定义

#### `CANT` 结构体
```c
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` 函数
```c
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` 函数
```c
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` 函数
```c
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` 函数
```c
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` 函数
```c
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` 函数
```c
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` 函数
```c
int cant_init(CANT *cant);
```
**函数说明**：初始化 CAN 设备。
**参数介绍**：
- `cant`：指向 `CANT` 结构体的指针，代表要初始化的 CAN 设备。
**返回值**：
- `CANT_E_OK`：初始化成功。
- `CANT_E_INVALID`：传入的 `cant` 指针为 `NULL`。

#### `cant_task` 函数
```c
int cant_task(CANT *cant);
```
**函数说明**：CAN 设备的主任务函数，用于处理 CAN 设备的周期性任务。
**参数介绍**：
- `cant`：指向 `CANT` 结构体的指针，代表要执行任务的 CAN 设备。
**返回值**：
- `CANT_E_OK`：任务执行成功。
- `CANT_E_INVALID`：传入的 `cant` 指针为 `NULL`。