RT-Thread引脚基础管理及IO模型
1、PIN管理
1.1 PIN设备简介
芯片上的引脚一般分为 4 类：电源、时钟、控制与 Input/Output。
I/O 口在使用模式上又分为通用I/O（General Purpose Input Output，即GPIO）、复用 I/O（如 SPI/I2C/UART 等），引脚的功能特性和裸机编程相同。
1.2 访问PIN设备
RT-Thread提供以下接口访问引脚：
| 函数 | 描述 |
|---|---|
| rt_pin_mode() | 设置引脚模式 |
| rt_pin_write() | 设置引脚电平 |
| rt_pin_read() | 读取引脚电平 |
| rt_pin_attach_irq() | 绑定引脚中断回调函数 |
| rt_pin_irq_enable() | 使能引脚中断 |
| rt_pin_detach_irq() | 脱离引脚中断回调函数 |
1.2.1 获取引脚编号
RT-Thread 提供的引脚编号需要和芯片的引脚号区分开来，它们并不是同一个概念，引脚编号由 PIN 设备驱动程序定义，和具体的芯片相关。有2种方式可以获取引脚编号：
- 使用宏定义
如果使用 rt-thread/bsp/stm32 目录下的 BSP 则可以使用下面的宏获取引脚编号：
GET_PIN(port, pin)
例如在潘多拉开发板点亮红色LED，对着引脚PE7，则
#define LEDR_PIN GET_PIN(E, 7)
- 查看驱动文件
查看 PIN 驱动代码 drv_gpio.c文件确认引脚编号。此文件里有一个数组存放了每个 PIN 脚对应的编号信息，如下所示：
#if defined(GPIOE)
__STM32_PIN(64, E, 0),
__STM32_PIN(65, E, 1),
__STM32_PIN(66, E, 2),
__STM32_PIN(67, E, 3),
__STM32_PIN(68, E, 4),
__STM32_PIN(69, E, 5),
__STM32_PIN(70, E, 6),
__STM32_PIN(71, E, 7),
……
以我们的红色LED PE7为例，其端口号为E，引脚号为7，对应上述的__STM32_PIN(71, E, 7)，则其引脚编号为71。
1.2.2 设置引脚模式
引脚在使用前需要先设置好工作模式，通过如下函数完成：
void rt_pin_mode(rt_base_t pin, rt_base_t mode);
//pin为引脚编号
//mode为工作模式
RT-Thread 支持的引脚工作模式可取如下所示的 5 种宏定义值之一：
#define PIN_MODE_OUTPUT 0x00 /* 输出 */
#define PIN_MODE_INPUT 0x01 /* 输入 */
#define PIN_MODE_INPUT_PULLUP 0x02 /* 上拉输入 */
#define PIN_MODE_INPUT_PULLDOWN 0x03 /* 下拉输入 */
#define PIN_MODE_OUTPUT_OD 0x04 /* 开漏输出 */
1.2.3 设置引脚电平
设置引脚输出电平的函数如下所示：
void rt_pin_write(rt_base_t pin, rt_base_t value);
//pin：引脚编号
//value：电平逻辑值，可取 2 种宏定义值之一：PIN_LOW 或PIN_HIGH
1.2.4 读取引脚电平
读取引脚电平的函数如下所示：
int rt_pin_read(rt_base_t pin);
//pin：引脚编号
//返回值：PIN_LOW 或PIN_HIGH
1.2.5 使用中断功能
- 绑定中断回调函数
使用如下函数将某个引脚配置为某种中断触发模式并绑定一个中断回调函数到对应引脚，当引脚中断发生时，就会执行回调函数:
rt_err_t rt_pin_attach_irq(rt_int32_t pin, rt_uint32_t mode, void (*hdr)(void *args), void *args);
中断触发模式mode可取如下 5 种宏定义值之一：
#define PIN_IRQ_MODE_RISING 0x00 /* 上升沿触发 */
#define PIN_IRQ_MODE_FALLING 0x01 /* 下降沿触发 */
#define PIN_IRQ_MODE_RISING_FALLING 0x02 /* 边沿触发（上升沿和下降沿都触发）*/
#define PIN_IRQ_MODE_HIGH_LEVEL 0x03 /* 高电平触发 */
#define PIN_IRQ_MODE_LOW_LEVEL 0x04 /* 低电平触发 */
- 使用引脚中断
绑定好引脚中断回调函数后使用下面的函数使能引脚中断：
rt_err_t rt_pin_irq_enable(rt_base_t pin, rt_uint32_t enabled);
- 脱离中断回调函数
可以使用如下函数脱离引脚中断回调函数：
rt_err_t rt_pin_detach_irq(rt_int32_t pin);
引脚脱离了中断回调函数以后，中断并没有关闭，还可以调用绑定中断回调函数再次绑定其他回调函数。
2、IO设备模型
2.1 IO设备介绍
2.1.1 IO设备模型框架
IO设备模型框架，分为图示左侧三层结构：
工作如下所示：
2.1.2 IO设备模型
RT-Thread 的设备模型是建立在内核对象模型基础之上的，设备被认为是一类对象，被纳入对象管理器的范畴。
设备对象的具体定义如下：
struct rt_device
{
struct rt_object parent; /* 内核对象基类 */
enum rt_device_class_type type; /* 设备类型 */
rt_uint16_t flag; /* 设备参数 */
rt_uint16_t open_flag; /* 设备打开标志 */
rt_uint8_t ref_count; /* 设备被引用次数 */
rt_uint8_t device_id; /* 设备 ID,0 - 255 */
/* 数据收发回调函数 */
rt_err_t (*rx_indicate)(rt_device_t dev, rt_size_t size);
rt_err_t (*tx_complete)(rt_device_t dev, void *buffer);
const struct rt_device_ops *ops; /* 设备操作方法 */
/* 设备的私有数据 */
void *user_data;
};
typedef struct rt_device *rt_device_t;
2.1.3 IO设备分类
RT-Thread 支持以下 I/O 要设备类型：
RT_Device_Class_Char /* 字符设备 */
RT_Device_Class_Block /* 块设备 */
RT_Device_Class_NetIf /* 网络接口设备 */
RT_Device_Class_MTD /* 内存设备 */
RT_Device_Class_RTC /* RTC 设备 */
RT_Device_Class_Sound /* 声音设备 */
RT_Device_Class_Graphic /* 图形设备 */
RT_Device_Class_I2CBUS /* I2C 总线设备 */
RT_Device_Class_USBDevice /* USB device 设备 */
RT_Device_Class_USBHost /* USB host 设备 */
RT_Device_Class_SPIBUS /* SPI 总线设备 */
RT_Device_Class_SPIDevice /* SPI 设备 */
RT_Device_Class_SDIO /* SDIO 设备 */
RT_Device_Class_Miscellaneous /* 杂类设备 */
2.2 创建和注册IO设备
2.2.1 创建与删除
设备驱动由驱动层负责创建，并注册到 I/O 设备管理器中。设备示例可以通过静态申明的形式创建，也可以动态创建。
动态创建IO设备的接口如下：
rt_device_t rt_device_create(int type, int attach_size);
调用该接口时，系统会从动态堆内存中分配一个设备控制块，大小为struct rt_device和attach_size的和，设备的类型由参数type 设定。
设备被创建后，需要实现它访问硬件的操作方法：
struct rt_device_ops
{
/* common device interface */
rt_err_t (*init) (rt_device_t dev);
rt_err_t (*open) (rt_device_t dev, rt_uint16_t oflag);
rt_err_t (*close) (rt_device_t dev);
rt_size_t (*read) (rt_device_t dev, rt_off_t pos, void *buffer, rt_size_t size
);
rt_size_t (*write) (rt_device_t dev, rt_off_t pos, const void *buffer,
rt_size_t size);
rt_err_t (*control)(rt_device_t dev, int cmd, void *args);
};
当一个动态创建的设备不再需要使用时可以通过如下函数来销毁：
void rt_device_destroy(rt_device_t device);
2.2.2 注册与注销
设备被创建后，需要注册到 I/O 设备管理器中，应用程序才能够访问，注册设备的函数如下所示：
rt_err_t rt_device_register(rt_device_t dev, const char* name, rt_uint8_t flags);
flags 参数支持下列参数 (可以采用或的方式支持多种参数)：
#define RT_DEVICE_FLAG_RDONLY 0x001 /* 只读 */
#define RT_DEVICE_FLAG_WRONLY 0x002 /* 只写 */
#define RT_DEVICE_FLAG_RDWR 0x003 /* 读写 */
#define RT_DEVICE_FLAG_REMOVABLE 0x004 /* 可移除 */
#define RT_DEVICE_FLAG_STANDALONE 0x008 /* 独立 */
#define RT_DEVICE_FLAG_SUSPENDED 0x020 /* 挂起 */
#define RT_DEVICE_FLAG_STREAM 0x040 /* 流模式 */
#define RT_DEVICE_FLAG_INT_RX 0x100 /* 中断接收 */
#define RT_DEVICE_FLAG_DMA_RX 0x200 /* DMA 接收 */
#define RT_DEVICE_FLAG_INT_TX 0x400 /* 中断发送 */
#define RT_DEVICE_FLAG_DMA_TX 0x800 /* DMA 发送 */
注册成功的设备可以在FinSH 命令行使用list_device命令查看系统中所有的设备信息，包括设备名称、设备类型和设备被打开次数，例如：
msh />list_device
device type ref count
-------- -------------------- ----------
e0 Network Interface 0
sd0 Block Device 1
rtc RTC 0
uart1 Character Device 0
uart0 Character Device 2
msh />
当设备注销后的，设备将从设备管理器中移除，不能再通过设备查找搜索到该设备。注销设备不会释放设备控制块占用的内存。注销设备的函数如下所示：
rt_err_t rt_device_unregister(rt_device_t dev);
2.3 访问IO设备
应用程序通过 I/O 设备管理接口来访问硬件设备，当设备驱动实现后，应用程序就可以访问该硬件。I/O 设备管理接口与 I/O 设备的操作方法的映射关系下图所示：
2.3.1 查找设备
rt_device_t rt_device_find(const char* name);
2.3.2 初始化设备
rt_err_t rt_device_init(rt_device_t dev);
2.3.3 打开和关闭
打开设备时，会检测设备是否已经初始化，没有初始化则会默认调用初始化接口初始化设备。打开设备的函数接口：
rt_err_t rt_device_open(rt_device_t dev, rt_uint16_t oflags);
oflags 支持以下的参数：
#define RT_DEVICE_OFLAG_CLOSE 0x000 /* 设备已经关闭（内部使用）*/
#define RT_DEVICE_OFLAG_RDONLY 0x001 /* 以只读方式打开设备 */
#define RT_DEVICE_OFLAG_WRONLY 0x002 /* 以只写方式打开设备 */
#define RT_DEVICE_OFLAG_RDWR 0x003 /* 以读写方式打开设备 */
#define RT_DEVICE_OFLAG_OPEN 0x008 /* 设备已经打开（内部使用）*/
#define RT_DEVICE_FLAG_STREAM 0x040 /* 设备以流模式打开 */
#define RT_DEVICE_FLAG_INT_RX 0x100 /* 设备以中断接收模式打开 */
#define RT_DEVICE_FLAG_DMA_RX 0x200 /* 设备以 DMA 接收模式打开 */
#define RT_DEVICE_FLAG_INT_TX 0x400 /* 设备以中断发送模式打开 */
#define RT_DEVICE_FLAG_DMA_TX 0x800 /* 设备以 DMA 发送模式打开 */
关闭设备的函数接口：
rt_err_t rt_device_close(rt_device_t dev);
2.3.4 控制设备
rt_err_t rt_device_control(rt_device_t dev, rt_uint8_t cmd, void* arg);
cmd 的通用设备命令可取如下宏定义：
#define RT_DEVICE_CTRL_RESUME 0x01 /* 恢复设备 */
#define RT_DEVICE_CTRL_SUSPEND 0x02 /* 挂起设备 */
#define RT_DEVICE_CTRL_CONFIG 0x03 /* 配置设备 */
#define RT_DEVICE_CTRL_SET_INT 0x10 /* 设置中断 */
#define RT_DEVICE_CTRL_CLR_INT 0x11 /* 清中断 */
#define RT_DEVICE_CTRL_GET_INT 0x12 /* 获取中断状态 */
2.3.5 读写设备
读取数据可以通过如下函数完成：从 dev 设备中读取数据，并存放在 buffer 缓冲区中，这个缓冲区的最大长度是 size，pos 根据不同的设备类别有不同的意义。
rt_size_t rt_device_read(rt_device_t dev, rt_off_t pos,void* buffer, rt_size_t size);
写入数据，可以通过如下函数完成：把缓冲区 buffer 中的数据写入到设备 dev 中，写入数据的最大长度是 size，pos 根据不同的设备类别存在不同的意义。
rt_size_t rt_device_write(rt_device_t dev, rt_off_t pos,const void* buffer, rt_size_t size);
2.3.6 数据收发回调
当硬件设备收到数据时，可以通过如下函数回调另一个函数来设置数据接收指示，通知上层应用线程有数据到达：
rt_err_t rt_device_set_rx_indicate(rt_device_t dev, rt_err_t (*rx_ind)(rt_device_t dev,rt_size_t size));
该函数的回调函数由调用者提供。当硬件设备接收到数据时，会回调这个函数并把收到的数据长度放在 size 参数中传递给上层应用。上层应用线程应在收到指示后，立刻从设备中读取数据。
在应用程序调用 rt_device_write() 写入数据时，如果底层硬件能够支持自动发送，那么上层应用可以设置一个回调函数。这个回调函数会在底层硬件数据发送完成后 (例如 DMA 传送完成或 FIFO 已经写入完毕产生完成中断时) 调用。可以通过如下函数设置设备发送完成指示，函数参数及返回值见：
rt_err_t rt_device_set_tx_complete(rt_device_t dev, rt_err_t (*tx_done)(rt_device_t dev,void *buffer));
调用这个函数时，回调函数由调用者提供，当硬件设备发送完数据时，由驱动程序回调这个函数并把发送完成的数据块地址buffer作为参数传递给上层应用。上层应用（线程）在收到指示时会根据发送buffer的情况，释放buffer内存块或将其作为下一个写数据的缓存。