varch/doc/slup.en.md

## Introduction

`slup` is a simple serial link general protocol module for the C language. It defines protocol-related configuration structures, queue structures, parser structures, and dummy data structures, etc. At the same time, it provides a series of function interfaces for initializing the protocol module, sending data, obtaining link status and rate information, setting dummy data, and other operations, which facilitates developers to implement communication functions based on serial links in C language projects.

## Interfaces

### Function Pointer Types
1. **`slup_putc_t` Function Pointer Type**:
```c
typedef int (*slup_putc_t)(char c);
```
- **Purpose**: Used to point to a function for writing a character.
- **Parameter**: `c`, the character to be written.
- **Return Value**: Of the `int` type, the specific meaning is determined by the actual function.
2. **`slup_check_t` Function Pointer Type**:
```c
typedef uint32_t (*slup_check_t)(uint8_t *data, uint16_t length);
```
- **Purpose**: Used to point to a function for checking data.
- **Parameters**:
  - `data`: A pointer to the data array to be checked.
  - `length`: The length of the data.
- **Return Value**: Of the `uint32_t` type, returns the check result.
3. **`slup_receive_t` Function Pointer Type**:
```c
typedef int (*slup_receive_t)(uint8_t *data, uint16_t length);
```
- **Purpose**: Used to point to a function for receiving data.
- **Parameters**:
  - `data`: A pointer to the buffer for receiving data.
  - `length`: The length of the data to be received.
- **Return Value**: Of the `int` type, the specific meaning is determined by the actual function.

### Structure Definitions
1. **`SLUP_CFG` Structure**:
```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;
```
- **Purpose**: Used to store the configuration information of the SLUP protocol, including the head mask, tail mask, head size, tail size, check code size, and sequence number size.
- **Member Introduction**:
  - `head`: An array storing the head mask, with a maximum size of `SLUP_HEAD_MAX`.
  - `tail`: An array storing the tail mask, with a maximum size of `SLUP_TAIL_MAX`.
  - `hsize`: The head size, occupying 4 bits.
  - `tsize`: The tail size, occupying 4 bits.
  - `csize`: The check code size, occupying 4 bits.
  - `ssize`: The sequence number size, occupying 4 bits.
2. **`SLUP_QUEUE` Structure**:
```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;
```
- **Purpose**: Used to define the SLUP queue for storing received data.
- **Member Introduction**:
  - `base`: The base address array of the queue data, with a size of `SLUP_RXQUE_SIZE`.
  - `size`: The total size of the queue.
  - `head`: The index of the queue head.
  - `tail`: The index of the queue tail.
3. **`SLUP_PARSER` Structure**:
```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;
```
- **Purpose**: A structure used to parse SLUP data, recording various states and information during the parsing process.
- **Member Introduction**:
  - `state`: The current state of the parser.
  - `hindex`: The head index, occupying 4 bits.
  - `tindex`: The tail index, occupying 4 bits.
  - `cindex`: The check code index, occupying 4 bits.
  - `sindex`: The sequence number index, occupying 4 bits.
  - `lindex`: The length index, occupying 2 bits.
  - `frame`: The frame status flag.
  - `length`: The length of the data being processed.
  - `dindex`: The index within the data.
  - `check`: The check value of the data.
  - `sn`: The sequence number.
4. **`SLUP_DUMMY` Structure**:
```c
typedef struct 
{
    float compression;
    float rate;
    uint32_t target;
    uint32_t gapbase;
    uint32_t gapcount;
    uint8_t data[64];
} SLUP_DUMMY;
```
- **Purpose**: A structure used to store SLUP dummy data.
- **Member Introduction**:
  - `compression`: The compression factor, of the floating-point type.
  - `rate`: The rate value, of the floating-point type.
  - `target`: The target value.
  - `gapbase`: The gap base value.
  - `gapcount`: The gap count.
  - `data`: An array for storing data, with a size of 64 bytes.
5. **`SLUP` Structure**:
```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;
```
- **Purpose**: The main structure of the SLUP protocol, integrating multiple parts such as configuration, queue, parser, and dummy data.
- **Member Introduction**:
  - `cfg`: The `SLUP_CFG` structure, storing protocol configuration information.
  - `queue`: The `SLUP_QUEUE` structure, storing receive queue information.
  - `parser`: The `SLUP_PARSER` structure, storing parser information.
  - `dummy`: The `SLUP_DUMMY` structure, storing dummy data information.
  - `buffer`: The buffer for storing data, with a maximum size of `SLUP_FRAME_MAX`.
  - `bsize`: The size of the buffer.
  - `sn`: The sequence number.
  - `link`: The link status flag.
  - `silent`: The silent status flag.
  - `period`: The period value.
  - `timestamp`: The timestamp.
  - `upbits`: The number of bits in the upload direction.
  - `downbits`: The number of bits in the download direction.
  - `uprate`: The upload rate.
  - `downrate`: The download rate.
  - `putc`: A function pointer of the `slup_putc_t` type, used for writing characters.
  - `check`: A function pointer of the `slup_check_t` type, used for checking data.
  - `receive`: A function pointer of the `slup_receive_t` type, used for receiving data.

### Functions
1. **`slup_init` Function**:
```c
int slup_init(SLUP *slup);
```
- **Function**: Initializes the `SLUP` structure.
- **Parameter**:
  - `slup`: A pointer to the `SLUP` structure.
- **Return Value**:
  - `SLUP_E_OK`: Initialization is successful.
  - `SLUP_E_INVALID`: The passed `slup` pointer is `NULL`.
- **Explanation**: This function initializes each field in the `SLUP` structure.
2. **`slup_send` Function**:
```c
int slup_send(SLUP *slup, uint8_t *data, uint16_t length);
```
- **Function**: Sends SLUP protocol data with the frame type `0x01`.
- **Parameters**:
  - `slup`: A pointer to the `SLUP` structure.
  - `data`: A pointer to the buffer of the data to be sent.
  - `length`: The length of the data buffer.
- **Return Value**:
  - `SLUP_E_OK`: The data is successfully sent.
  - Others: The corresponding error code.
- **Explanation**: This function simply calls the `slup_send_package` function to send the provided data with the frame type `0x01`.
3. **`slup_link_status` Function**:
```c
int slup_link_status(SLUP *slup, uint8_t *link);
```
- **Function**: Obtains the current link status from the `SLUP` structure.
- **Parameters**:
  - `slup`: A pointer to the `SLUP` structure.
  - `link`: A pointer to the variable used to store the link status.
- **Return Value**:
  - `SLUP_E_OK`: The acquisition is successful.
  - Others: The corresponding error code.
- **Explanation**: This function checks the validity of the passed pointer.
4. **`slup_upload_rate` Function**:
```c
int slup_upload_rate(SLUP *slup, uint32_t *rate);
```
- **Function**: Obtains the upload rate from the `SLUP` structure.
- **Parameters**:
  - `slup`: A pointer to the `SLUP` structure.
  - `rate`: A pointer to the variable used to store the upload rate.
- **Return Value**:
  - `SLUP_E_OK`: The acquisition is successful.
  - Others: The corresponding error code.
- **Explanation**: This function checks the validity of the passed pointer.
5. **`slup_download_rate` Function**:
```c
int slup_download_rate(SLUP *slup, uint32_t *rate);
```
- **Function**: Obtains the download rate from the `SLUP` structure.
- **Parameters**:
  - `slup`: A pointer to the `SLUP` structure.
  - `rate`: A pointer to the variable used to store the download rate.
- **Return Value**:
  - `SLUP_E_OK`: The acquisition is successful.
  - Others: The corresponding error code.
- **Explanation**: This function checks the validity of the passed pointer.
6. **`slup_set_dummy` Function**:
```c
int slup_set_dummy(SLUP *slup, uint32_t rate);
```
- **Function**: Sets the target rate of the dummy data in the `SLUP` structure.
- **Parameters**:
  - `slup`: A pointer to the `SLUP` structure.
  - `rate`: The target rate value to be set.
- **Return Value**:
  - `SLUP_E_OK`: The setting is successful.
  - `SLUP_E_INVALID`: The passed `slup` pointer is `NULL`.
- **Explanation**: This function checks the validity of the passed pointer.
7. **`slup_getc` Function**:
```c
void slup_getc(SLUP *slup, char c);
```
- **Function**: Handles the reception of a single character in the SLUP system.
- **Parameters**:
  - `slup`: A pointer to the `SLUP` structure.
  - `c`: The received character.
- **Explanation**: This function updates the link status to the receive state (sets `SLUP_LINK_RX`), clears the silent flag, updates the download statistics, and pushes the received character into the queue.
8. **`slup_task` Function**:
```c
void slup_task(SLUP *slup);
```
- **Function**: The main task function of the SLUP system.
- **Parameter**:
  - `slup`: A pointer to the `SLUP` structure.
- **Explanation**: This function updates the timestamp and performs various operations according to the timestamp value, such as sending heartbeat messages, calculating the rate, performing dummy data sending, and updating dummy data parameters, etc. It also calls the `slup_parse_task` function to parse the received data in the queue.