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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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.