rt-thread 设备驱动框架

RT-Thread 设备框架属于组件和服务层，是基于 RT-Thread 内核之上的上层软件。设备框架是针对某一类外设，抽象出来的一套统一的操作方法及接入标准，可以屏蔽硬件差异，为应用层提供统一的操作方法。

RT-Thread 设备框架分为三层：设备驱动层、设备驱动框架层、I/O 设备管理层。其中设备驱动层直接对接底层硬件设备；I/O 设备管理层向应用层提供了rt_device_find、open、read、write、close、register等访问设备的统一标准接口。而设备驱动框架层就是就是将同类型硬件设备的共同特特征提取抽象出来，并且还预留了接口，可以添加不同设备的独有特性。

其中的设备模型被认为是一类对象，每个设备对象都是由基对象派生的，每个设备都可以继承其父类对象的属性，并派生其私有属性。

正是这样的框架，使得 RT-Thread 设备框架中各模块高内聚低耦合，对于已有的设备类型，只要将底层硬件的驱动对接到设备驱动层，就可以在应用程序中，调用统一的标准接口，使用的不同厂家不同类型的硬件设备。

1.数据结构

struct rt_device{    

　　struct rt_object          parent;      //继承rt_object对象，不用管
　　enum rt_device_class_type type;  //设备类型    
   rt_uint16_t               flag;             //设备标志，设备允许访问权限    
　　rt_uint16_t               open_flag;   //当前设备的打开方式，当关闭时会根据这个标志去关闭设备    
　　rt_uint8_t                ref_count;      //打开次数 打开+1  关闭-1，到0时才会调用close函数    
　　rt_uint8_t                device_id;     //设备的ID号，感觉没用到,应该是系统自动分配ID号吧    
　　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; //设备操作方法}
　　struct rt_device_ops{    
　　　　　　　　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);                          //配置设备};

 2. 常用函数 

一、I/O设备控制块
1、I/O设备控制块
struct rt_device
{
struct rt_object parent;
/* 设备类型 */
enum rt_device_class_type type;
/* 设备参数及打开参数 */
rt_uint16_t flag, open_flag;
/* 提供给上层应用的回调函数 */
rt_err_t (*rx_indicate)(rt_device_t dev, rt_size_t size);
rt_err_t (*tx_complete)(rt_device_t dev, void* buffer);
/* 公共的设备接口(由驱动程序提供) */
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, rt_uint8_t cmd, void *args);
/* 用于支持电源管理的函数接口 */
#ifdef RT_USING_DEVICE_SUSPEND
rt_err_t (*suspend) (rt_device_t dev);
rt_err_t (*resumed) (rt_device_t dev);
#endif
/* 设备的私有数据 */
void* user_data;
};

typedef struct rt_device* rt_device_t;

当前RT-Thread支持的设备类型包括：
enum rt_device_class_type
{
RT_Device_Class_Char = 0, /* 字符设备 */
RT_Device_Class_Block, /* 块设备 */
RT_Device_Class_NetIf, /* 网络接口 */
RT_Device_Class_MTD, /* 内存设备 */
RT_Device_Class_CAN, /* CAN设备 */
RT_Device_Class_RTC, /* RTC设备 */
RT_Device_Class_Sound, /* 声音设备 */
RT_Device_Class_Display, /* 显示设备 */
RT_Device_Class_Unknown /* 未知设备 */
};

注：uspend、resume回调函数只会在RT_USING_DEVICE_SUSPEND宏使能的情况下才
会有效。
从设备控制块，我们可以看到，每个设备对象都会在内核中维护一个设备控制块结构，
这种结构是使设备对象继承rt_object基类，然后形成rt_device设备类型。

2、注册设备
一个设备能够被上层应用访问前，需要先把这个设备注册到系统中，并添加一些相应的
一些属性。这些注册的设备均可以通过设备名，采用“查找设备接口”的方式从系统中查找
到，从而获得该设备控制块（或设备句柄）。注册设备的函数接口如下：
rt_err_t rt_device_register(rt_device_t dev, const char* name, rt_uint8_t flags);

函数参数：
dev 设备句柄；
name 设备名称；
flag 设备模式标志：
flags参数支持下列参数(可以采用或的方式支持多种参数)：

#define RT_DEVICE_FLAG_DEACTIVATE 0x000 /* 未初始化设备 */
#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_ACTIVATED 0x010 /* 已激活设备 */
#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发送模式 */

设备流模式RT_DEVICE_FLAG_STREAM参数用于向串口终端输出字符串：当输出的字符
是“\n”时，自动在前面补一个“\r”做分行。
函数返回
返回RT_EOK
警告：应当避免重复注册已经注册的设备，以及注册相同名字的设备。

3、移除设备
将设备从设备系统中移除，被卸载的设备将不能再通过“查找设备接口”被查找到。卸
载设备的函数接口如下所示：
rt_err_t rt_device_unregister(rt_device_t dev)

函数参数
参数 描述
dev 设备句柄；
函数返回
返回RT_EOK
注：卸载设备并不会释放设备控制块所占用的内存

4、初始化所有设备
初始化所有注册到设备对象管理器中的未初始化的设备，可以通过如下函数接口完成：

rt_err_t rt_device_init_all(void)

函数参数
无
函数返回
返回RT_EO
• 注：此函数将逐渐废弃，不推荐在应用程序中调用。当一个设备初始化完成后它
的flags域中的RT_DEVICE_FLAG_ACTIVATED应该被置位。如果设备的flags域已经是
RT_DEVICE_FLAG_ACTIVATED，调用这个接口将不再重复做初始化。

5、查找设备
根据指定的设备名称查找设备，可以通过如下接口完成：

rt_device_t rt_device_find(const char* name)

使用这个函数接口时，系统会在设备对象类型所对应的对象容器中遍历寻找设备对象，
然后返回该设备的句柄，如果没有找到相应的设备对象，则返回RT_NULL。
函数参数
参数 描述
name 设备名称。
函数返回
查找到对应设备将返回相应的设备句柄；否则返回RT_NULL。

6、打开设备
根据设备控制块来打开设备，可以通过如下函数接口完成：

rt_err_t rt_device_open (rt_device_t dev, rt_uint16_t oflags);

函数参数
参数 描述
dev 设备句柄；
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 /* 设备已经打开（内部使用） */

函数返回
返回驱动的open函数返回值
注：如果设备注册时指定的参数中包括RT_DEVICE_FLAG_STANDALONE参数，此设备将
不允许重复打开，返回-RT_EBUSY。

7、关闭设备
根据设备控制块来关闭设备，可以通过如下函数接口完成：

rt_err_t rt_device_close(rt_device_t dev)

函数参数
参数 描述
dev 设备句柄；

函数返回
返回驱动的close函数返回值

8、读设备
从设备中读取，或获得数据，可以通过如下函数接口完成：

rt_size_t rt_device_read (rt_device_t dev, rt_off_t pos, void* buffer, rt_size_t size)

调用这个函数，会从设备dev中获得数据，并存放在buffer缓冲区中。这个缓冲区的最
大长度是size。pos根据不同的设备类别存在不同的意义。
函数参数
参数 描述
dev 设备句柄；
pos 读取数据偏移量；
buffer 内存缓冲区指针，读取的数据将会被保存在缓冲区中；
size 读取数据的大小。
函数返回

返回读到数据的实际大小（如果是字符设备，返回大小以字节为单位；如果是块设备，
返回的大小以块为单位）；如果返回0，则需要读取当前线程的errno来判断错误状态。

9、写设备
向设备中写入数据，可以通过如下函数接口完成：

rt_size_t rt_device_write(rt_device_t dev, rt_off_t pos, const void* buffer, rt_size_t size)

调用这个函数，会把缓冲区buffer中的数据写入到设备dev中。写入数据的最大长度是
size。pos根据不同的设备类别存在不同的意义。
函数参数

参数 描述
dev 设备句柄；
pos 读取数据偏移量；
buffer 内存缓冲区指针，放置要写入的数据；
size 写入数据的大小。

函数返回
返回写入数据的实际大小(如果是字符设备，返回大小以字节为单位；如果是块设备，
返回的大小以块为单位)；如果返回0，则需要读取当前线程的errno来判断错误状态
• 注：在RT-Thread的块设备中，从1.0.0版本开始， rt_device_read()/rt_device_write()接
口的pos、size参数按照以块为单位。0.3.x以前的版本则按字节为单位。

10、控制设备
根据设备控制块来控制设备，可以通过下面的函数接口完成：

rt_err_t rt_device_control(rt_device_t dev, rt_uint8_t cmd, void* arg);

函数参数
参数 描述
dev 设备句柄；
cmd 命令控制字，这个参数通常与设备驱动程序相关；
arg 控制的参数

函数返回
返回驱动控制接口的返回值。

11、设置数据接收指示
设置一个回调函数，当硬件设备收到数据时回调以通知用程序有数据到达。可以通过如
下函数接口完成设置接收指示：
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));

在调用这个函数时，回调函数rx_ind由调用者提供。当硬件设备接收到数据时，会回调
这个函数并把收到的数据长度放在size参数中传递给上层应用。上层应用线程应在收到指示
后，立刻从设备中读取数据。
函数参数
参数 描述
dev 设备句柄；
rx_ind 接收回调函数。

函数返回
返回RT_EOK

12、设置发送完成指示
在上层应用调用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))
调用这个函数时，回调函数tx_done参数由调用者提供，当硬件设备发送完数据时，由驱动程序回调这个函数并把发送完成的数据块地址buffer做为参数传递给上层应用。上层应用（线程）在收到指示时应根据发送buffer的情况，释放buffer内存块或将其做为下一个写数据的缓存。
函数参数
参数 描述
dev 设备句柄；
tx_done 发送回调函数。

函数返回
返回RT_EOK

二、设备驱动

设备驱动必须实现的接口
在10.1节中提及了RT-Thread设备接口类，我们着重看看其中包含的一套公共设备接口
(类似上节说的设备访问接口，但面向的层次已经不一样，这里是面向底层驱动)：

/* 公共的设备接口(由驱动程序提供) */
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, rt_uint8_t cmd, void *args);

/* 用于支持电源管理的函数接口 */

#ifdef RT_USING_DEVICE_SUSPEND
rt_err_t (*suspend) (rt_device_t dev);
rt_err_t (*resumed) (rt_device_t dev);
#endif

这些接口也是上层应用通过RT-Thread设备接口进行访问的实际底层接口（如设备操作接口与设备驱动程序接口的映射 ）：

即这些驱动实现的底层接口是上层应用最终访问的落脚点，例如上层应用调用rt_device_read接口进行设备读取数据操作，上层应先调用rt_device_find获得相对应的设备句柄，而在调用rt_device_read时，就是使用这个设备句柄所对应驱动的driver_read。上述的接口是一一对应关系。
I/O设备模块提供的这六个接口（rt_device_init/open/read/write/control），对应到设备驱动程序的六个接口（driver_init/open/read/write/control等），可以认为是底层设备驱动必须提供的接口：

1、init
设备的初始化。设备初始化完成后，设备控制块的flag会被置 成已激活状态(RT_DEVICE_FLAG_ACTIVATED)。如果设备控制块 的flag
不是已激活状态，那么在设备框架调用 rt_device_init_all接口时将调用此设备驱动的init接口进行 设备初始化；如果设备控制块中的flag标志已经设置成激活状 态，那么再运行初始化接口时，会立刻返回，而不会重新进行 初始化。
2、open
打开设备。有些设备并不是系统一启动就已经打开开始运行； 或者设备需要进行数据接收，但如果上层应用还未准备好，设 备也
不应默认已经使能并开始接收数据。所以建议在写底层驱 动程序时，应在调用open接口时才使能设备。

3、close
关闭设备。建议在打开设备时，设备驱动自行维护一个打开计数，在打开设备时进行+1操作，在关闭设备时进行-1操作， 当计数
器变为0时，进行真正的关闭操作。

4、read
从设备中读取数据。参数pos指出读取数据的偏移量，但是有些 设备并不一定需要指定偏移量，例如串口设备，设备驱动应忽 略这
个参数。而对于块设备来说，pos以及size都是以块设备的 数据块大小做为单位的。例如块设备的数据块大小是512，而参 数中pos= 10, size = 2，那么驱动应该返回设备中第10个块 （从第0个块做为起始），共计2个块的数据。这个接口返回的 类型rt_size_t，即读到的字节数或块数目。正常情况下应 该会返回参数中size的数值，如果返回零请设置对应的errno值。
5、write
向设备中写入数据。参数pos指出写入数据的偏移量。与读操作 类似，对于块设备来说，pos以及size都是以块设备的数据块 大小做
为单位的。这个接口返回的类型是rt_size_t，即真实写 入数据的字节数或块数目。正常情况下应该会返回参数中size 的数值，如果返回零请设置对应的errno值。

6、control
根据不同的cmd命令控制设备。命令往往是由底层各类设备驱 动自定义实现。例如参数RT_DEVICE_CTRL_BLK_GETGEOME，意思 是获取块设备的大小信息。

三、设备驱动实现的步骤

在实现一个RT-Thread设备时，可以按照如下的步骤进行（对于一些复杂的设备驱动，例如以太网接口驱动、图形设备驱动，请参看网络组件、GUI部分章节）：
• 按照RT-Thread的对象模型，扩展一个对象有两种方式：
• 定义自己的私有数据结构，然后赋值到RT-Thread设备控制块的user_data指针上；
• 从struct rt_device结构中进行派生。
• 实现RT-Thread I/O设备模块中定义的6个公共设备接口，开始可以是空函数(返回类型是rt_err_t的可默认返回RT_EOK)；
• 根据自己的设备类型定义自己的私有数据域。特别是在可能有多个相类似设备的情况下（例如串口1、2），设备接口可以共用同一套接口，不同的只是各自 的数据域(例如寄存器基地址)；
• 根据设备的类型，注册到RT-Thread设备框架中。

3. 设备驱动模型
设备驱动模型整体上可分为三层：

应用层：应用程序调用设备操作接口rt_device_find、rt_device_read等来操作设备
核心层：提供驱动对象的注册接口、把驱动对象挂载到对应设备信息的链表上
驱动相关层：定义驱动对象、实现设备操作函数、调用驱动对象的注册函数进行注册

这个函数的作用就是将rt_device中的rt_object挂载到类型为RT_Object_Class_Device设备信息的链表上，从而完成这个设备的注册。

对于应用调用流程，首先通过函数rt_object_find在类型为RT_Object_Class_Device设备信息的链表上遍历查找，通过设备名进行比对，比对成功后返回rt_device。
rt-device-read -> rt-device.read -> xxx_read;

4. 例子

http://bbs.eeworld.com.cn/thread-1255136-1-1.html