lby/mr-library
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

1.SPI、PIN、SERIAL使用文档更新。

Browse Source
This commit is contained in:
MacRsh
2023-09-12 01:01:46 +08:00
parent 8aa33aede6
commit af81115e60
6 changed files with 347 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -66,7 +66,7 @@ mr_device_ioctl(spi1_device, MR_DEVICE_CTRL_CONNECT, "spi1");
mr_device_open(spi0_device, MR_DEVICE_OFLAG_RDWR);
mr_device_open(spi1_device, MR_DEVICE_OFLAG_RDWR);
/* 发送数据 */
/* 写入数据 */
char buffer0[] = "hello";
char buffer1[] = "world";
mr_device_write(spi0_device, -1, buffer0, sizeof(buffer0) - 1);

3
device/spi/spi.h
View File

@@ -60,6 +60,9 @@ extern "C" {
#define MR_SPI_POS_BITS_16 16
#define MR_SPI_POS_BITS_32 32
/**
* @def SPI device control transfer flag
*/
#define MR_DEVICE_CTRL_SPI_TRANSFER 0x01000000
/**

BIN
document/resource/framework.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 72 KiB

12
document/user/device/pin.md
View File

@@ -27,12 +27,12 @@ GPIO（通用目的输入/输出）是一种可以通过软件进行控制的硬
mr_device_t mr_device_find(const char *name);
```
| 参数 | 描述 |
|:--------|:-------|
| name | PIN设备名 |
| **返回** | |
| PIN | 查找设备成功 |
| MR_NULL | 查找设备失败 |
| 参数 | 描述 |
|:----------|:----------|
| name | PIN设备名 |
| **返回** | |
| PIN | 查找设备成功 |
| MR_NULL | 查找设备失败 |
----------

127
document/user/device/serial.md
View File

@@ -10,15 +10,14 @@ UART（Universal Asynchronous Receiver/Transmitter）即通用异步收发传输
## 调用关系
![调用关系](https://gitee.com/MacRsh/mr-library/raw/master/document/resource/serial_device.png)
![调用关系](https://gitee.com/MacRsh/mr-library/raw/develop/document/resource/serial_device.png)
----------
## 准备工作
## 准备
1. 引用 `mrdrv.h` 头文件以使用驱动部分。
2. 调用SERIAL设备初始化函数（如果实现了自动初始化,则无需调用）。
3. 使能 `mrconfig.h` 头文件中SERIAL宏开关。
1. 调用SERIAL设备初始化函数（如果实现了自动初始化,则无需调用）。
2. 使能 `mrconfig.h` 头文件中SERIAL宏开关。
----------
@@ -28,39 +27,39 @@ UART（Universal Asynchronous Receiver/Transmitter）即通用异步收发传输
mr_device_t mr_device_find(const char *name);
```
| 参数 | 描述 |
|:---------|:----------|
| name | SERIAL设备名 |
| **返回** | |
| SERIAL句柄 | 查找设备成功 |
| MR_NULL | 查找设备失败 |
| 参数 | 描述 |
|:---------|:------------|
| name | SERIAL设备名 |
| **返回** | |
| SERIAL | 查找设备成功 |
| MR_NULL | 查找设备失败 |
----------
## 打开SERIAL设备
```c
mr_err_t mr_device_open(mr_device_t device, mr_uint16_t flags);
mr_err_t mr_device_open(mr_device_t device, mr_uint8_t oflags);
```
| 参数 | 描述 |
|:----------|:-----------|
| device | SERIAL设备句柄 |
| flags | 打开方式 |
| **返回** | |
| MR_ERR_OK | 打开设备成功 |
| 错误码 | 打开设备失败 |
| 参数 | 描述 |
|:------------|:-----------|
| device | SERIAL设备 |
| oflags | 打开方式 |
| **返回** | |
| MR_ERR_OK | 打开设备成功 |
| 错误码 | 打开设备失败 |
SERIAL设备支持以下打开方式：
```c
MR_OPEN_RDONLY /* 只读 */
MR_OPEN_WRONLY /* 只写 */
MR_OPEN_RDWR /* 可读可写 */
MR_OPEN_NONBLOCKING /* 非阻塞 */
MR_DEVICE_OFLAG_RDONLY /* 只读 */
MR_DEVICE_OFLAG_WRONLY /* 只写 */
MR_DEVICE_OFLAG_RDWR /* 可读可写 */
MR_DEVICE_OFLAG_NONBLOCKING /* 非阻塞 */
```
当打开方式|MR_OPEN_NONBLOCKING，对串口设备写入数据时将检测发送缓冲区空间是否为0，如果非0，数据将被压入发送缓冲区后通过中断发送。
当打开方式|MR_DEVICE_OFLAG_NONBLOCKING，对串口设备写入数据时将检测发送缓冲区空间是否为0，如果非0，数据将被压入发送缓冲区后通过中断发送。
| 缓冲区 | 打开方式 | 接收方式 | 发送方式 |
|:----|:-----|:-----|:-----|
@@ -79,7 +78,7 @@ mr_err_t mr_device_ioctl(mr_device_t device, int cmd, void *args);
| 参数 | 描述 |
|:----------|:-----------|
| device | SERIAL设备句柄 |
| device | SERIAL设备 |
| cmd | 控制命令 |
| args | 控制参数 |
| **返回** | |
@@ -89,12 +88,12 @@ mr_err_t mr_device_ioctl(mr_device_t device, int cmd, void *args);
SERIAL设备支持以下命令：
```c
MR_CTRL_SET_CONFIG /* 设置参数 */
MR_CTRL_GET_CONFIG /* 获取参数 */
MR_CTRL_SET_RX_CB /* 设置接收（接收中断）回调函数 */
MR_CTRL_SET_TX_CB /* 设置发送（发送完成中断）回调函数 */
MR_CTRL_SET_RX_BUFSZ /* 设置接收缓冲区大小 */
MR_CTRL_SET_TX_BUFSZ /* 设置发送缓冲区大小 */
MR_DEVICE_CTRL_SET_CONFIG /* 设置参数 */
MR_DEVICE_CTRL_GET_CONFIG /* 获取参数 */
MR_DEVICE_CTRL_SET_RX_CB /* 设置接收（接收中断）回调函数 */
MR_DEVICE_CTRL_SET_TX_CB /* 设置发送（发送完成中断）回调函数 */
MR_DEVICE_CTRL_SET_RX_BUFSZ /* 设置接收缓冲区大小 */
MR_DEVICE_CTRL_SET_TX_BUFSZ /* 设置发送缓冲区大小 */
```
### 配置SERIAL设备
@@ -115,6 +114,9 @@ struct mr_serial_config
- 数据位：表示每个字符所占的比特数。
```c
MR_SERIAL_DATA_BITS_5 /* 数据位5 */
MR_SERIAL_DATA_BITS_6 /* 数据位6 */
MR_SERIAL_DATA_BITS_7 /* 数据位7 */
MR_SERIAL_DATA_BITS_8 /* 数据位8 */
MR_SERIAL_DATA_BITS_9 /* 数据位9 */
```
@@ -123,8 +125,9 @@ MR_SERIAL_DATA_BITS_9 /* 数据位
```c
MR_SERIAL_STOP_BITS_1 /* 停止位1 */
MR_SERIAL_STOP_BITS_1_5 /* 停止位1.5 */
MR_SERIAL_STOP_BITS_2 /* 停止位2 */
MR_SERIAL_STOP_BITS_3 /* 停止位3 */
MR_SERIAL_STOP_BITS_4 /* 停止位4 */
```
- 奇偶校验：串口通信中的错误检测方式。
@@ -157,13 +160,13 @@ mr_device_t serial_device = mr_device_find("uart1");
/* 设置默认参数 */
struct mr_serial_config serial_config = MR_SERIAL_CONFIG_DEFAULT;
mr_device_ioctl(serial_device, MR_CTRL_SET_CONFIG, &serial_config);
mr_device_ioctl(serial_device, MR_DEVICE_CTRL_SET_CONFIG, &serial_config);
/* 获取参数 */
mr_device_ioctl(serial_device, MR_CTRL_GET_CONFIG, &serial_config);
mr_device_ioctl(serial_device, MR_DEVICE_CTRL_GET_CONFIG, &serial_config);
```
注：如未手动修改SERIAL设备参数，则默认使用默认参数。
注：如未手动修改SERIAL设备参数，则打开设备将使用默认参数。
### 设置SERIAL设备接收（发送完成）回调函数
@@ -191,8 +194,8 @@ mr_err_t serial_device_tx_cb(mr_device_t device, void *args)
mr_device_t serial_device = mr_device_find("uart1");
/* 设置接收（发送完成）回调函数 */
mr_device_ioctl(serial_device, MR_CTRL_SET_RX_CB, serial_device_rx_cb);
mr_device_ioctl(serial_device, MR_CTRL_SET_TX_CB, serial_device_tx_cb);
mr_device_ioctl(serial_device, MR_DEVICE_CTRL_SET_RX_CB, serial_device_rx_cb);
mr_device_ioctl(serial_device, MR_DEVICE_CTRL_SET_TX_CB, serial_device_tx_cb);
```
### 设置SERIAL设备接收（发送）缓冲区大小
@@ -205,8 +208,8 @@ mr_device_t serial_device = mr_device_find("uart1");
/* 设置接收（发送）缓冲区大小 */
mr_size_t bufsz = 64;
mr_device_ioctl(serial_device, MR_CTRL_SET_RX_BUFSZ, &bufsz);
mr_device_ioctl(serial_device, MR_CTRL_SET_TX_BUFSZ, &bufsz);
mr_device_ioctl(serial_device, MR_DEVICE_CTRL_SET_RX_BUFSZ, &bufsz);
mr_device_ioctl(serial_device, MR_DEVICE_CTRL_SET_TX_BUFSZ, &bufsz);
```
----------
@@ -214,17 +217,17 @@ mr_device_ioctl(serial_device, MR_CTRL_SET_TX_BUFSZ, &bufsz);
## SERIAL设备读取数据
```c
mr_ssize_t mr_device_read(mr_device_t device, mr_pos_t pos, const void *buffer, mr_size_t size);
mr_ssize_t mr_device_read(mr_device_t device, mr_off_t pos, const void *buffer, mr_size_t size);
```
| 参数 | 描述 |
|:----------|:-------------|
| device | SERIAL设备句柄 |
| pos | 读取位置 |
| buffer | 读取数据 |
| size | 读取数据大小 |
| **返回** | |
| 实际读取的数据大小 | |
| 参数 | 描述 |
|:------------|:-------------|
| device | SERIAL设备 |
| pos | 读取位置 |
| buffer | 读取数据 |
| size | 读取数据大小 |
| **返回** | |
| 实际读取的数据大小 | |
使用示例：
@@ -233,15 +236,15 @@ mr_ssize_t mr_device_read(mr_device_t device, mr_pos_t pos, const void *buffer,
mr_device_t serial_device = mr_device_find("uart1");
/* 以可读可写方式打开 */
mr_device_open(serial_device, MR_OPEN_RDWR);
mr_device_open(serial_device, MR_DEVICE_OFLAG_RDWR);
/* 设置默认参数 */
struct mr_serial_config serial_config = MR_SERIAL_CONFIG_DEFAULT;
mr_device_ioctl(serial_device, MR_CTRL_SET_CONFIG, &serial_config);
mr_device_ioctl(serial_device, MR_DEVICE_CTRL_SET_CONFIG, &serial_config);
/* 读取数据 */
char buffer[5] = {0};
mr_device_write(serial_device, 0, buffer, sizeof(buffer));
mr_device_read(serial_device, 0, buffer, sizeof(buffer));
```
----------
@@ -249,17 +252,17 @@ mr_device_write(serial_device, 0, buffer, sizeof(buffer));
## SERIAL设备写入数据
```c
mr_ssize_t mr_device_write(mr_device_t device, mr_pos_t pos, const void *buffer, mr_size_t size);
mr_ssize_t mr_device_write(mr_device_t device, mr_off_t pos, const void *buffer, mr_size_t size);
```
| 参数 | 描述 |
|:----------|:-----------|
| device | SERIAL设备句柄 |
| pos | 写入位置 |
| buffer | 写入数据 |
| size | 写入数据大小 |
| **返回** | |
| 实际写入的数据大小 | |
| 参数 | 描述 |
|:----------|:----------|
| device | SERIAL设备 |
| pos | 写入位置 |
| buffer | 写入数据 |
| size | 写入数据大小 |
| **返回** | |
| 实际写入的数据大小 | |
使用示例：
@@ -268,11 +271,11 @@ mr_ssize_t mr_device_write(mr_device_t device, mr_pos_t pos, const void *buffer,
mr_device_t serial_device = mr_device_find("uart1");
/* 以非阻塞可读可写方式打开 */
mr_device_open(serial_device, MR_OPEN_RDWR | MR_OPEN_NONBLOCKING);
mr_device_open(serial_device, MR_DEVICE_OFLAG_RDWR | MR_DEVICE_OFLAG_NONBLOCKING);
/* 设置默认参数 */
struct mr_serial_config serial_config = MR_SERIAL_CONFIG_DEFAULT;
mr_device_ioctl(serial_device, MR_CTRL_SET_CONFIG, &serial_config);
mr_device_ioctl(serial_device, MR_DEVICE_CTRL_SET_CONFIG, &serial_config);
/* 写入数据 */
char buffer[] = "hello";

272
document/user/device/spi.md Normal file
View File

@@ -0,0 +1,272 @@
# SPI设备使用指南
----------
## 概述
SPI（Serial Peripheral Interface）是一种串行外设接口，用于连接和控制嵌入式系统中的外部设备。
是一种全双工、同步的通信协议，通过时钟和数据线实现高速数据传输。SPI常用于存储器、传感器、显示器等外围设备的通信，具有简单、可靠和高速传输的特点。
----------
## 准备
1. 调用SPI设备初始化函数（如果实现了自动初始化,则无需调用）。
2. 使能 `mrconfig.h` 头文件中SPI宏开关。
----------
## 调用关系
![调用关系](https://gitee.com/MacRsh/mr-library/raw/develop/document/resource/spi_device.png)
----------
## 准备
1. 调用SPI设备初始化函数（如果实现了自动初始化,则无需调用）。
2. 使能 `mrconfig.h` 头文件中SPI宏开关。
----------
## 添加SPI设备
```c
mr_err_t mr_spi_device_add(mr_spi_device_t spi_device, const char *name, mr_off_t cs_number);
```
| 参数 | 描述 |
|:-----------|:------------|
| spi_device | SPI设备 |
| name | SPI设备名 |
| cs_number | SPI设备片选引脚编号 |
| **返回** | |
| MR_ERR_OK | 添加设备成功 |
| 错误码 | 添加设备失败 |
## 控制SPI设备
```c
mr_err_t mr_device_ioctl(mr_device_t device, int cmd, void *args);
```
| 参数 | 描述 |
|:----------|:--------|
| device | SPI设备 |
| cmd | 控制命令 |
| args | 控制参数 |
| **返回** | |
| MR_ERR_OK | 控制设备成功 |
| 错误码 | 控制设备失败 |
SPI设备支持以下命令：
```c
MR_DEVICE_CTRL_SET_CONFIG /* 设置参数 */
MR_DEVICE_CTRL_GET_CONFIG /* 获取参数 */
MR_DEVICE_CTRL_CONNECT /* 连接总线 */
```
### 配置SPI设备
```c
struct mr_spi_config
{
mr_uint32_t baud_rate; /* 波特率 */
mr_uint32_t host_slave: 1; /* 主从模式 */
mr_uint32_t mode: 2; /* 极性、相位模式 */
mr_uint32_t data_bits: 6; /* 数据位数 */
mr_uint32_t bit_order: 1; /* 高低位 */
mr_uint32_t cs_active: 2; /* 片选激活电平 */
mr_uint32_t pos_bits: 6; /* 位置位数 */
}
```
- 波特率：SPI的通信速率，表示每秒传输的比特数，常见的有18M、36M、72M等。
- 主从模式：主机模式还是从机模式。
```c
MR_SPI_HOST /* 主机模式 */
MR_SPI_SLAVE /* 从机模式 */
```
- 极性、相位模式：时钟的极性和相位。
```c
MR_SPI_MODE_0 /* CPOL = 0, CPHA = 0 */
MR_SPI_MODE_1 /* CPOL = 0, CPHA = 1 */
MR_SPI_MODE_2 /* CPOL = 1, CPHA = 0 */
MR_SPI_MODE_3 /* CPOL = 1, CPHA = 1 */
```
- 数据位：表示每次能发送的位数。
```c
MR_SPI_DATA_BITS_8 /* 8位数据 */
MR_SPI_DATA_BITS_16 /* 16位数据 */
MR_SPI_DATA_BITS_32 /* 32位数据 */
```
- 高低位：数据高位在前还是低位在前。
```c
MR_SPI_BIT_ORDER_MSB /* 高位在前 */
MR_SPI_BIT_ORDER_LSB /* 低位在前 */
```
- 片选激活电平：片选引脚有效的电平。
```c
MR_SPI_CS_ACTIVE_LOW /* 低电平有效 */
MR_SPI_CS_ACTIVE_HIGH /* 高电平有效 */
MR_SPI_CS_ACTIVE_HARDWARE /* 硬件控制 */
```
- 位置位数：发送位置时的位置的位数。
```c
MR_SPI_POS_BITS_8 /* 8位位置 */
MR_SPI_POS_BITS_16 /* 16位位置 */
MR_SPI_POS_BITS_32 /* 32位位置 */
```
### SPI设备配置，连接、断开总线
SPI设备添加后并不能立即进行读写操作，其读写操作依赖总线，所以当SPI设备未连接总线或从总线断开后，其不支持以任何形式打开。如果原先处于打开状态，其也会被强制关闭。
使用示例：
```c
/* 定义SPI设备 */
#define SPI_DEVICE0_CS_NUMBER 10
#define SPI_DEVICE1_CS_NUMBER 20
struct mr_spi_device spi_device0, spi_device1;
/* 添加SPI设备 */
mr_spi_device_add(&spi_device0, "spi10", SPI_DEVICE0_CS_NUMBER);
mr_spi_device_add(&spi_device1, "spi11", SPI_DEVICE1_CS_NUMBER);
/* 查找SPI设备 */
mr_device_t spi0_device = mr_device_find("spi10");
mr_device_t spi1_device = mr_device_find("spi11");
/* 设置默认参数 */
struct mr_spi_config spi_config = MR_SPI_CONFIG_DEFAULT;
mr_device_ioctl(spi0_device, MR_DEVICE_CTRL_SET_CONFIG, &spi_config);
mr_device_ioctl(spi1_device, MR_DEVICE_CTRL_SET_CONFIG, &spi_config);
/* 连接总线 */
mr_device_ioctl(spi0_device, MR_DEVICE_CTRL_CONNECT, "spi1");
mr_device_ioctl(spi1_device, MR_DEVICE_CTRL_CONNECT, "spi1");
/* 断开总线 */
mr_device_ioctl(spi0_device, MR_DEVICE_CTRL_CONNECT, MR_NULL);
mr_device_ioctl(spi1_device, MR_DEVICE_CTRL_CONNECT, MR_NULL);
```
### 设置SPI设备从机模式接收回调函数
- 回调函数：device为触发回调设备，args传入缓冲区数据长度。
使用示例：
```c
/* 定义回调函数 */
mr_err_t spi_device_rx_cb(mr_device_t device, void *args)
{
mr_size_t length = *(mr_size_t *)args; /* 获取接收缓冲区数据长度 */
/* Do something */
}
/* 查找SPI1设备 */
mr_device_t spi_device = mr_device_find("spi10");
/* 设置接收回调函数 */
mr_device_ioctl(spi_device, MR_DEVICE_CTRL_SET_RX_CB, spi_device_rx_cb);
```
### 设置SPI设备接收缓冲区大小
使用示例：
```c
/* 查找SPI1设备 */
mr_device_t spi_device = mr_device_find("spi10");
/* 设置接收缓冲区大小 */
mr_size_t bufsz = 64;
mr_device_ioctl(spi_device, MR_DEVICE_CTRL_SET_RX_BUFSZ, &bufsz);
```
----------
## SPI设备读取数据
```c
mr_ssize_t mr_device_read(mr_device_t device, mr_off_t pos, const void *buffer, mr_size_t size);
```
| 参数 | 描述 |
|:------------|:-------|
| device | SPI设备 |
| pos | 读取位置 |
| buffer | 读取数据 |
| size | 读取数据大小 |
| **返回** | |
| 实际读取的数据大小 | |
- 读取位置：需要读取的（寄存器）地址，如读取0x23地址数据，则pos = 0x23，有效范围：0-2147483647。地址长度根据设置的pos_bits，如不使用时请赋值：-1。
使用示例：
```c
/* 查找SPI1设备（在此之前请先添加设备并连接总线） */
mr_device_t spi_device = mr_device_find("spi10");
/* 以可读可写的方式打开SPI设备 */
mr_device_open(spi_device, MR_DEVICE_OFLAG_RDWR);
/* 读取数据 */
mr_uint8_t buffer[10];
mr_device_read(spi_device, -1, buffer, sizeof(buffer));
/* 读取0x23地址数据*/
mr_device_read(spi_device, 0x23, buffer, sizeof(buffer));
```
----------
## SPI设备写入数据
```c
mr_ssize_t mr_device_write(mr_device_t device, mr_off_t pos, const void *buffer, mr_size_t size);
```
| 参数 | 描述 |
|:------------|:-------|
| device | SPI设备 |
| pos | 写入位置 |
| buffer | 写入数据 |
| size | 写入数据大小 |
| **返回** | |
| 实际写入的数据大小 | |
- 写入位置：需要写入的（寄存器）地址，如写入0x23地址数据，则pos = 0x23，有效范围：0-2147483647。地址长度根据设置的pos_bits，如不使用时请赋值：-1。
使用示例：
```c
/* 查找SPI1设备（在此之前请先添加设备并连接总线） */
mr_device_t spi_device = mr_device_find("spi10");
/* 以可读可写的方式打开SPI设备 */
mr_device_open(spi_device, MR_DEVICE_OFLAG_RDWR);
/* 写入数据 */
char buffer[] = "hello";
mr_device_write(spi_device, -1, buffer, sizeof(buffer) - 1);
/* 向0x23地址写入数据*/
mr_device_write(spi_device, 0x23, buffer, sizeof(buffer) - 1);
```