varch/doc/slup.md

## 介绍

`slup` 是一个用于 C 语言的简单串行链路通用协议模块。它定义了协议相关的配置结构体、队列结构体、解析器结构体以及虚拟数据结构体等，同时提供了一系列函数接口，用于初始化协议模块、发送数据、获取链路状态和速率信息、设置虚拟数据等操作，方便开发者在 C 语言项目中实现基于串行链路的通信功能。

## 接口

### 函数指针类型
1. **`slup_putc_t` 函数指针类型**：
```c
typedef int (*slup_putc_t)(char c);
```
- **用途**：用于指向一个写字符的函数。
- **参数**：`c`，要写入的字符。
- **返回值**：`int` 类型，具体含义由实际函数决定。
2. **`slup_check_t` 函数指针类型**：
```c
typedef uint32_t (*slup_check_t)(uint8_t *data, uint16_t length);
```
- **用途**：用于指向一个检查数据的函数。
- **参数**：
  - `data`：指向要检查的数据数组的指针。
  - `length`：数据的长度。
- **返回值**：`uint32_t` 类型，返回检查结果。
3. **`slup_receive_t` 函数指针类型**：
```c
typedef int (*slup_receive_t)(uint8_t *data, uint16_t length);
```
- **用途**：用于指向一个接收数据的函数。
- **参数**：
  - `data`：指向接收数据缓冲区的指针。
  - `length`：接收数据的长度。
- **返回值**：`int` 类型，具体含义由实际函数决定。

### 结构体定义
1. **`SLUP_CFG` 结构体**：
```c
typedef struct 
{
    uint8_t head[SLUP_HEAD_MAX];            /**< head mask */
    uint8_t tail[SLUP_TAIL_MAX];            /**< tail mask */
    uint8_t hsize : 4;                      /**< head size */
    uint8_t tsize : 4;                      /**< tail size */
    uint8_t csize : 4;                      /**< check code size */
    uint8_t ssize : 4;                      /**< sn size */
} SLUP_CFG;
```
- **用途**：用于存储 SLUP 协议的配置信息，包括头部掩码、尾部掩码、头部大小、尾部大小、校验码大小和序列号大小。
- **成员介绍**：
  - `head`：存储头部掩码的数组，最大尺寸为 `SLUP_HEAD_MAX`。
  - `tail`：存储尾部掩码的数组，最大尺寸为 `SLUP_TAIL_MAX`。
  - `hsize`：头部大小，占用 `4` 位。
  - `tsize`：尾部大小，占用 `4` 位。
  - `csize`：校验码大小，占用 `4` 位。
  - `ssize`：序列号大小，占用 `4` 位。
2. **`SLUP_QUEUE` 结构体**：
```c
typedef struct
{
    char base[SLUP_RXQUE_SIZE];             /* base address of data */
    uint32_t size;                          /* size of queue */
    uint32_t head;                          /* index of queue head */
    uint32_t tail;                          /* index of queue tail */
} SLUP_QUEUE;
```
- **用途**：用于定义 SLUP 队列，存储接收的数据。
- **成员介绍**：
  - `base`：队列数据的基地址数组，大小为 `SLUP_RXQUE_SIZE`。
  - `size`：队列的总大小。
  - `head`：队列头部的索引。
  - `tail`：队列尾部的索引。
3. **`SLUP_PARSER` 结构体**：
```c
typedef struct 
{
    uint8_t state;
    uint8_t hindex : 4;    
    uint8_t tindex : 4; 
    uint8_t cindex : 4;                     
    uint8_t sindex : 4;  
    uint8_t lindex : 2;                    
    uint8_t frame;
    uint16_t length;
    uint16_t dindex;
    uint32_t check;
    uint32_t sn;
} SLUP_PARSER;
```
- **用途**：用于解析 SLUP 数据的结构体，记录解析过程中的各种状态和信息。
- **成员介绍**：
  - `state`：解析器的当前状态。
  - `hindex`：头部索引，占用 `4` 位。
  - `tindex`：尾部索引，占用 `4` 位。
  - `cindex`：校验码索引，占用 `4` 位。
  - `sindex`：序列号索引，占用 `4` 位。
  - `lindex`：长度索引，占用 `2` 位。
  - `frame`：帧状态标志。
  - `length`：正在处理的数据长度。
  - `dindex`：数据内的索引。
  - `check`：数据的校验值。
  - `sn`：序列号。
4. **`SLUP_DUMMY` 结构体**：
```c
typedef struct 
{
    float compression;
    float rate;
    uint32_t target;
    uint32_t gapbase;
    uint32_t gapcount;
    uint8_t data[64];
} SLUP_DUMMY;
```
- **用途**：用于存储 SLUP 虚拟数据的结构体。
- **成员介绍**：
  - `compression`：压缩因子，浮点数类型。
  - `rate`：速率值，浮点数类型。
  - `target`：目标值。
  - `gapbase`：间隙基值。
  - `gapcount`：间隙计数。
  - `data`：存储数据的数组，大小为 `64` 字节。
5. **`SLUP` 结构体**：
```c
typedef struct 
{
    SLUP_CFG cfg;
    SLUP_QUEUE queue;
    SLUP_PARSER parser;
    SLUP_DUMMY dummy;
    uint8_t buffer[SLUP_FRAME_MAX];
    uint32_t bsize;
    uint32_t sn;
    uint8_t link;
    uint8_t silent;
    uint16_t period;
    uint32_t timestamp;
    uint32_t upbits;
    uint32_t downbits;
    uint32_t uprate;
    uint32_t downrate;
    slup_putc_t putc;
    slup_check_t check;
    slup_receive_t receive;
} SLUP;
```
- **用途**：SLUP 协议的主要结构体，整合了配置、队列、解析器、虚拟数据等多个部分。
- **成员介绍**：
  - `cfg`：`SLUP_CFG` 结构体，存储协议配置信息。
  - `queue`：`SLUP_QUEUE` 结构体，存储接收队列信息。
  - `parser`：`SLUP_PARSER` 结构体，存储解析器信息。
  - `dummy`：`SLUP_DUMMY` 结构体，存储虚拟数据信息。
  - `buffer`：存储数据的缓冲区，最大尺寸为 `SLUP_FRAME_MAX`。
  - `bsize`：缓冲区的大小。
  - `sn`：序列号。
  - `link`：链路状态标志。
  - `silent`：静音状态标志。
  - `period`：周期值。
  - `timestamp`：时间戳。
  - `upbits`：上传方向的位数。
  - `downbits`：下载方向的位数。
  - `uprate`：上传速率。
  - `downrate`：下载速率。
  - `putc`：`slup_putc_t` 类型的函数指针，用于写字符。
  - `check`：`slup_check_t` 类型的函数指针，用于检查数据。
  - `receive`：`slup_receive_t` 类型的函数指针，用于接收数据。

### 函数
1. **`slup_init` 函数**：
```c
int slup_init(SLUP *slup);
```
- **功能**：初始化 SLUP 结构体。
- **参数**：
  - `slup`：指向 `SLUP` 结构体的指针。
- **返回值**：
  - `SLUP_E_OK`：初始化成功。
  - `SLUP_E_INVALID`：传入的 `slup` 指针为 `NULL`。
- **说明**：该函数初始化 `SLUP` 结构体中的各个字段。
2. **`slup_send` 函数**：
```c
int slup_send(SLUP *slup, uint8_t *data, uint16_t length);
```
- **功能**：以帧类型 `0x01` 发送 SLUP 协议数据。
- **参数**：
  - `slup`：指向 `SLUP` 结构体的指针。
  - `data`：指向要发送的数据缓冲区的指针。
  - `length`：数据缓冲区的长度。
- **返回值**：
  - `SLUP_E_OK`：数据成功发送。
  - 其他：相应的错误码。
- **说明**：该函数简单调用 `slup_send_package` 函数，以帧类型 `0x01` 发送提供的数据。
3. **`slup_link_status` 函数**：
```c
int slup_link_status(SLUP *slup, uint8_t *link);
```
- **功能**：从 SLUP 结构体中获取当前链路状态。
- **参数**：
  - `slup`：指向 `SLUP` 结构体的指针。
  - `link`：指向用于存储链路状态的变量的指针。
- **返回值**：
  - `SLUP_E_OK`：获取成功。
  - 其他：相应的错误码。
- **说明**：该函数检查传入指针的有效性。
4. **`slup_upload_rate` 函数**：
```c
int slup_upload_rate(SLUP *slup, uint32_t *rate);
```
- **功能**：从 SLUP 结构体中获取上传速率。
- **参数**：
  - `slup`：指向 `SLUP` 结构体的指针。
  - `rate`：指向用于存储上传速率的变量的指针。
- **返回值**：
  - `SLUP_E_OK`：获取成功。
  - 其他：相应的错误码。
- **说明**：该函数检查传入指针的有效性。
5. **`slup_download_rate` 函数**：
```c
int slup_download_rate(SLUP *slup, uint32_t *rate);
```
- **功能**：从 SLUP 结构体中获取下载速率。
- **参数**：
  - `slup`：指向 `SLUP` 结构体的指针。
  - `rate`：指向用于存储下载速率的变量的指针。
- **返回值**：
  - `SLUP_E_OK`：获取成功。
  - 其他：相应的错误码。
- **说明**：该函数检查传入指针的有效性。
6. **`slup_set_dummy` 函数**：
```c
int slup_set_dummy(SLUP *slup, uint32_t rate);
```
- **功能**：设置 SLUP 结构体中虚拟数据的目标速率。
- **参数**：
  - `slup`：指向 `SLUP` 结构体的指针。
  - `rate`：要设置的目标速率值。
- **返回值**：
  - `SLUP_E_OK`：设置成功。
  - `SLUP_E_INVALID`：传入的 `slup` 指针为 `NULL`。
- **说明**：该函数检查传入指针的有效性。
7. **`slup_getc` 函数**：
```c
void slup_getc(SLUP *slup, char c);
```
- **功能**：处理 SLUP 系统中单个字符的接收。
- **参数**：
  - `slup`：指向 `SLUP` 结构体的指针。
  - `c`：接收到的字符。
- **说明**：该函数更新链路状态为接收状态（设置 `SLUP_LINK_RX`），清除静音标志，更新下载统计信息，并将接收到的字符推入队列。
8. **`slup_task` 函数**：
```c
void slup_task(SLUP *slup);
```
- **功能**：SLUP 系统的主任务函数。
- **参数**：
  - `slup`：指向 `SLUP` 结构体的指针。
- **说明**：该函数更新时间戳，并根据时间戳值执行各种操作，如发送心跳消息、计算速率、执行虚拟数据发送和更新虚拟数据参数等。它还调用 `slup_parse_task` 函数来解析队列中接收到的数据。