mr-library/document/device/serial/serial_EN.md

SERIAL Device

中文

• SERIAL Device
  • Open SERIAL Device
  • Close SERIAL Device
  • Control SERIAL Device
    • Set/Get SERIAL Device Configuration
    • Set/Get Read/Write Buffer Size
    • Clear Read/Write Buffer
    • Get Read/Write Buffer Data Size
    • Set/Get Read/Write Callback Function
  • Read Data from SERIAL Device
  • Write Data to SERIAL Device
  • Example

Open SERIAL Device

int mr_dev_open(const char *name, int oflags);

Parameter	Description
name	Device name
oflags	Flags for opening the device
Return Value
>=0	Device descriptor
<0	Error code

• name: The SERIAL device name is usually serialx, such as serial1, serial2, serial3.
• oflags: Flags for opening the device, supports MR_OFLAG_RDONLY, MR_OFLAG_WRONLY, MR_OFLAG_RDWR, MR_OFLAG_NONBLOCK.

Note: When using it, different tasks should open the SERIAL device separately according to actual situations, and use appropriate oflags for management and permission control to ensure they do not interfere with each other.

Close SERIAL Device

int mr_dev_close(int desc);

Parameter	Description
desc	Device descriptor
Return Value
=0	Closed successfully
<0	Error code

Control SERIAL Device

int mr_dev_ioctl(int desc, int cmd, void *args);

Parameter	Description
desc	Device descriptor
cmd	Command code
args	Command parameter
Return Value
=0	Set successfully
<0	Error code

• cmd: Command code, supports the following commands:
  • MR_CTL_SERIAL_SET_CONFIG: Set SERIAL device configuration.
  • MR_CTL_SERIAL_SET_RD_BUFSZ: Set read buffer size.
  • MR_CTL_SERIAL_SET_WR_BUFSZ: Set write buffer size.
  • MR_CTL_SERIAL_CLR_RD_BUF: Clear read buffer.
  • MR_CTL_SERIAL_CLR_WR_BUF: Clear write buffer.
  • MR_CTL_SERIAL_SET_RD_CALL: Set read callback function.
  • MR_CTL_SERIAL_SET_WR_CALL: Set write callback function.
  • MR_CTL_SERIAL_GET_CONFIG: Get SERIAL device configuration.
  • MR_CTL_SERIAL_GET_RD_BUFSZ: Get read buffer size.
  • MR_CTL_SERIAL_GET_WR_BUFSZ: Get write buffer size.
  • MR_CTL_SERIAL_GET_RD_DATASZ: Get read buffer data size.
  • MR_CTL_SERIAL_GET_WR_DATASZ: Get write buffer data size.
  • MR_CTL_SERIAL_GET_RD_CALL: Get read callback function.
  • MR_CTL_SERIAL_GET_WR_CALL: Get write callback function.

Set/Get SERIAL Device Configuration

SERIAL device configuration:

• baud_rate: Baud rate
• data_bits: Data bits
• stop_bits: Stop bits
• parity: Parity check
• bit_order: Data transmission order
• polarity: Polarity inversion

/* Set default configuration */
struct mr_serial_config config = MR_SERIAL_CONFIG_DEFAULT;

/* Set SERIAL device configuration */
mr_dev_ioctl(ds, MR_CTL_SERIAL_SET_CONFIG, &config);

/* Get SERIAL device configuration */
mr_dev_ioctl(ds, MR_CTL_SERIAL_GET_CONFIG, &config);

Independent of SERIAL interface:

/* Set default configuration */
int config[] = {115200, 8, 1, 0, 0, 0};

/* Set SERIAL device configuration */
mr_dev_ioctl(ds, MR_CTL_SET_CONFIG, &config);

/* Get SERIAL device configuration */
mr_dev_ioctl(ds, MR_CTL_GET_CONFIG, &config);

Note: If not configured manually, the default configuration is:

• Baud rate: 115200
• Data bits: MR_SERIAL_DATA_BITS_8
• Stop bits: MR_SERIAL_STOP_BITS_1
• Parity check: MR_SERIAL_PARITY_NONE
• Data transmission order: MR_SERIAL_BIT_ORDER_LSB
• Polarity inversion: MR_SERIAL_POLARITY_NORMAL

Set/Get Read/Write Buffer Size

size_t size = 256;

/* Set read buffer size */
mr_dev_ioctl(ds, MR_CTL_SERIAL_SET_RD_BUFSZ, &size);

/* Get read buffer size */  
mr_dev_ioctl(ds, MR_CTL_SERIAL_GET_RD_BUFSZ, &size);

/* Set write buffer size */
mr_dev_ioctl(ds, MR_CTL_SERIAL_SET_WR_BUFSZ, &size);

/* Get write buffer size */
mr_dev_ioctl(ds, MR_CTL_SERIAL_GET_WR_BUFSZ, &size);

Independent of SERIAL interface:

size_t size = 256;

/* Set read buffer size */
mr_dev_ioctl(ds, MR_CTL_SET_RD_BUFSZ, &size);

/* Get read buffer size */  
mr_dev_ioctl(ds, MR_CTL_GET_RD_BUFSZ, &size);

/* Set write buffer size */
mr_dev_ioctl(ds, MR_CTL_SET_WR_BUFSZ, &size);

/* Get write buffer size */
mr_dev_ioctl(ds, MR_CTL_GET_WR_BUFSZ, &size);

Note: If not configured manually, the size configured in Kconfig will be used (default is 32Byte).

Clear Read/Write Buffer

mr_dev_ioctl(ds, MR_CTL_SERIAL_CLR_RD_BUF, MR_NULL);
mr_dev_ioctl(ds, MR_CTL_SERIAL_CLR_WR_BUF, MR_NULL);

Independent of SERIAL interface:

mr_dev_ioctl(ds, MR_CTL_CLR_RD_BUF, MR_NULL);
mr_dev_ioctl(ds, MR_CTL_CLR_WR_BUF, MR_NULL);

Get Read/Write Buffer Data Size

size_t size = 0;

/* Get read buffer data size */
mr_dev_ioctl(ds, MR_CTL_SERIAL_GET_RD_DATASZ, &size);

/* Get write buffer data size */  
mr_dev_ioctl(ds, MR_CTL_SERIAL_GET_WR_DATASZ, &size);

Independent of SERIAL interface:

size_t size = 0;

/* Get read buffer data size */
mr_dev_ioctl(ds, MR_CTL_GET_RD_DATASZ, &size);

/* Get write buffer data size */  
mr_dev_ioctl(ds, MR_CTL_GET_WR_DATASZ, &size);

Set/Get Read/Write Callback Function

/* Define callback function */
int call(int desc, void *args)
{
    /* Get buffer data size */
    ssize_t data_size = *(ssize_t *)args;
    
    /* Handle interrupt */
    
    return MR_EOK;
}
int (*callback)(int, void *args);

/* Set read callback function */
mr_dev_ioctl(ds, MR_CTL_SERIAL_SET_RD_CALL, &call);

/* Get read callback function */
mr_dev_ioctl(ds, MR_CTL_SERIAL_GET_RD_CALL, &callback);

/* Set write callback function */
mr_dev_ioctl(ds, MR_CTL_SERIAL_SET_WR_CALL, &call);

/* Get write callback function */
mr_dev_ioctl(ds, MR_CTL_SERIAL_GET_WR_CALL, &callback);

Independent of SERIAL interface:

/* Define callback function */
int call(int desc, void *args)
{
    /* Get buffer data size */
    ssize_t data_size = *(ssize_t *)args;
    
    /* Handle interrupt */
    
    return MR_EOK;
}
int (*callback)(int, void *args);

/* Set read callback function */
mr_dev_ioctl(ds, MR_CTL_SET_RD_CALL, &call);

/* Get read callback function */
mr_dev_ioctl(ds, MR_CTL_GET_RD_CALL, &callback);

/* Set write callback function */
mr_dev_ioctl(ds, MR_CTL_SET_WR_CALL, &call);

/* Get write callback function */
mr_dev_ioctl(ds, MR_CTL_GET_WR_CALL, &callback);

Read Data from SERIAL Device

ssize_t mr_dev_read(int desc, void *buf, size_t size);

Parameter	Description
desc	Device descriptor
buf	Buffer to read data into
size	Size of data to read
Return Value
>=0	Number of bytes read
<0	Error code

char buf[128];
/* Read data from SERIAL device */
ssize_t size = mr_dev_read(ds, buf, sizeof(buf));
/* Check if read successfully */  
if (size < 0) 
{
    
}

Note: When no read buffer is set, it will use polling mode for synchronous reading (cannot ensure complete reception of data). When a read buffer is set, it will read the specified amount of data from the read buffer (return the actual number of bytes read).

Write Data to SERIAL Device

ssize_t mr_dev_write(int desc, const void *buf, size_t size);

Parameter	Description
desc	Device descriptor
buf	Buffer with data to write
size	Size of data to write
Return Value
>=0	Number of bytes written
<0	Error code

char buf[] = {"hello world"};
/* Write data to SERIAL device */
ssize_t size = mr_dev_write(ds, buf, sizeof(buf));
/* Check if write successfully */
if (size < 0) 
{
    
}

Note: When no write buffer is set and not using MR_OFLAG_NONBLOCK for opening, it will use polling mode for synchronous writing. When a write buffer is set, it will write the data to the write buffer (return the actual number of bytes written), and asynchronously send the data through interrupt or DMA. The write callback function will be triggered after sending is complete. When data is being asynchronously sent, the write lock will automatically be locked, and synchronous writing is not allowed until asynchronous sending is complete.

Example

#include "include/mr_lib.h"

/* Define serial device descriptor */
int serial_ds = -1;

int serial_init(void) 
{
    /* Initialize serial */
    serial_ds = mr_dev_open("serial1", MR_OFLAG_RDWR);  
    if (serial_ds < 0)
    {
      mr_printf("serial open failed: %s\r\n", mr_strerror(serial_ds));
      return serial_ds;
    }
    
    /* Set serial configuration */
    struct mr_serial_config config = MR_SERIAL_CONFIG_DEFAULT;  
    int ret = mr_dev_ioctl(serial_ds, MR_CTL_SERIAL_SET_CONFIG, &config);
    if (ret < 0) 
    {
      mr_printf("serial set config failed: %s\r\n", mr_strerror(ret));
      return ret;
    }
    return MR_EOK;
}
/* Export to auto initialization (APP level) */
MR_INIT_APP_EXPORT(serial_init);

int main(void) 
{
    /* Auto initialization (serial_init function will be automatically called here) */
    mr_auto_init();
    
    while (1) 
    {
        /* Loopback test */
        char buf[64];
        ssize_t ret = mr_dev_read(serial_ds, buf, sizeof(buf));
        mr_dev_write(serial_ds, buf, ret); 
    }
}

Connect the computer to serial port 1. Loopback test can be performed by sending data in the serial port software and seeing the received data displayed in the serial port software.