varch/doc/slup.md

介绍

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

接口

函数指针类型

1. slup_putc_t 函数指针类型：

typedef int (*slup_putc_t)(char c);

• 用途：用于指向一个写字符的函数。
• 参数：c，要写入的字符。
• 返回值：int 类型，具体含义由实际函数决定。

2. slup_check_t 函数指针类型：

typedef uint32_t (*slup_check_t)(uint8_t *data, uint16_t length);

• 用途：用于指向一个检查数据的函数。
• 参数：
  • data：指向要检查的数据数组的指针。
  • length：数据的长度。
• 返回值：uint32_t 类型，返回检查结果。

3. slup_receive_t 函数指针类型：

typedef int (*slup_receive_t)(uint8_t *data, uint16_t length);

• 用途：用于指向一个接收数据的函数。
• 参数：
  • data：指向接收数据缓冲区的指针。
  • length：接收数据的长度。
• 返回值：int 类型，具体含义由实际函数决定。

结构体定义

1. SLUP_CFG 结构体：

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 结构体：

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 结构体：

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 结构体：

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 结构体：

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 函数：

int slup_init(SLUP *slup);

• 功能：初始化 SLUP 结构体。
• 参数：
  • slup：指向 SLUP 结构体的指针。
• 返回值：
  • SLUP_E_OK：初始化成功。
  • SLUP_E_INVALID：传入的 slup 指针为 NULL。
• 说明：该函数初始化 SLUP 结构体中的各个字段。

2. slup_send 函数：

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 函数：

int slup_link_status(SLUP *slup, uint8_t *link);

• 功能：从 SLUP 结构体中获取当前链路状态。
• 参数：
  • slup：指向 SLUP 结构体的指针。
  • link：指向用于存储链路状态的变量的指针。
• 返回值：
  • SLUP_E_OK：获取成功。
  • 其他：相应的错误码。
• 说明：该函数检查传入指针的有效性。

4. slup_upload_rate 函数：

int slup_upload_rate(SLUP *slup, uint32_t *rate);

• 功能：从 SLUP 结构体中获取上传速率。
• 参数：
  • slup：指向 SLUP 结构体的指针。
  • rate：指向用于存储上传速率的变量的指针。
• 返回值：
  • SLUP_E_OK：获取成功。
  • 其他：相应的错误码。
• 说明：该函数检查传入指针的有效性。

5. slup_download_rate 函数：

int slup_download_rate(SLUP *slup, uint32_t *rate);

• 功能：从 SLUP 结构体中获取下载速率。
• 参数：
  • slup：指向 SLUP 结构体的指针。
  • rate：指向用于存储下载速率的变量的指针。
• 返回值：
  • SLUP_E_OK：获取成功。
  • 其他：相应的错误码。
• 说明：该函数检查传入指针的有效性。

6. slup_set_dummy 函数：

int slup_set_dummy(SLUP *slup, uint32_t rate);

• 功能：设置 SLUP 结构体中虚拟数据的目标速率。
• 参数：
  • slup：指向 SLUP 结构体的指针。
  • rate：要设置的目标速率值。
• 返回值：
  • SLUP_E_OK：设置成功。
  • SLUP_E_INVALID：传入的 slup 指针为 NULL。
• 说明：该函数检查传入指针的有效性。

7. slup_getc 函数：

void slup_getc(SLUP *slup, char c);

• 功能：处理 SLUP 系统中单个字符的接收。
• 参数：
  • slup：指向 SLUP 结构体的指针。
  • c：接收到的字符。
• 说明：该函数更新链路状态为接收状态（设置 SLUP_LINK_RX），清除静音标志，更新下载统计信息，并将接收到的字符推入队列。

8. slup_task 函数：

void slup_task(SLUP *slup);

• 功能：SLUP 系统的主任务函数。
• 参数：
  • slup：指向 SLUP 结构体的指针。
• 说明：该函数更新时间戳，并根据时间戳值执行各种操作，如发送心跳消息、计算速率、执行虚拟数据发送和更新虚拟数据参数等。它还调用 slup_parse_task 函数来解析队列中接收到的数据。