RT-Thread API参考手册  3.1.1
嵌入式实时操作系统
结构体 | 宏定义 | 类型定义 | 枚举 | 函数
设备子系统
设备管理

I/O设备子系统 更多...

结构体

struct  rt_device_ops
 设备对象的操作方法 更多...
 
struct  rt_wqueue
 等待队列控制块 更多...
 
struct  rt_device
 设备基类控制块 更多...
 
struct  rt_device_blk_geometry
 块设备扇区信息 更多...
 
struct  rt_device_blk_sectors
 块设备的扇区分布信息 更多...
 
struct  rt_device_graphic_info
 图形设备信息结构 更多...
 
struct  rt_device_rect_info
 矩形信息结构 更多...
 

宏定义

#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 发送模式
 
#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_OFLAG_MASK   0xf0f
 打开参数的掩码
 
#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
 获取中断状态命令
 
#define RT_DEVICE_CTRL_CHAR_STREAM   0x10
 字符设备上的流模式
 
#define RT_DEVICE_CTRL_BLK_GETGEOME   0x10
 获取块设备信息
 
#define RT_DEVICE_CTRL_BLK_SYNC   0x11
 将数据刷新到块设备
 
#define RT_DEVICE_CTRL_BLK_ERASE   0x12
 擦除块设备上的存储块
 
#define RT_DEVICE_CTRL_BLK_AUTOREFRESH   0x13
 块设备：进入/退出自动刷新模式
 
#define RT_DEVICE_CTRL_NETIF_GETMAC   0x10
 获取mac地址
 
#define RT_DEVICE_CTRL_MTD_FORMAT   0x10
 格式化MTD设备
 
#define RT_DEVICE_CTRL_RTC_GET_TIME   0x10
 获取时间
 
#define RT_DEVICE_CTRL_RTC_SET_TIME   0x11
 设置时间
 
#define RT_DEVICE_CTRL_RTC_GET_ALARM   0x12
 获取闹钟信息
 
#define RT_DEVICE_CTRL_RTC_SET_ALARM   0x13
 设置闹钟
 
#define RT_DEVICE_CTRL_CURSOR_SET_POSITION   0x10
 设置光标位置
 
#define RT_DEVICE_CTRL_CURSOR_SET_TYPE   0x11
 设置关闭类型
 
#define RTGRAPHIC_CTRL_RECT_UPDATE   0
 更新设备图形
 
#define RTGRAPHIC_CTRL_POWERON   1
 打开设备电源
 
#define RTGRAPHIC_CTRL_POWEROFF   2
 关闭设备电源
 
#define RTGRAPHIC_CTRL_GET_INFO   3
 获取设备信息
 
#define RTGRAPHIC_CTRL_SET_MODE   4
 设置工作模式
 
#define RTGRAPHIC_CTRL_GET_EXT   5
 获取
 
#define RTGRAPHIC_PIXEL_POSITION(x, y)   ((x << 16) | y)
 根据（x，y）坐标构建像素位置
 

类型定义

typedef struct rt_device * rt_device_t
 设备类型指针定义
 

枚举

函数

rt_err_t rt_device_register (rt_device_t dev, const char *name, rt_uint16_t flags)
 注册设备 更多...
 
rt_err_t rt_device_unregister (rt_device_t dev)
 删除设备 更多...
 
rt_device_t rt_device_find (const char *name)
 查找设备 更多...
 
rt_device_t rt_device_create (int type, int attach_size)
 创建设备 更多...
 
void rt_device_destroy (rt_device_t dev)
 销毁设备 更多...
 
rt_err_t rt_device_init (rt_device_t dev)
 初始化设备 更多...
 
rt_err_t rt_device_open (rt_device_t dev, rt_uint16_t oflag)
 打开设备 更多...
 
rt_err_t rt_device_close (rt_device_t dev)
 关闭设备 更多...
 
rt_size_t rt_device_read (rt_device_t dev, rt_off_t pos, void *buffer, rt_size_t size)
 读取设备 更多...
 
rt_size_t rt_device_write (rt_device_t dev, rt_off_t pos, const void *buffer, rt_size_t size)
 写设备 更多...
 
rt_err_t rt_device_control (rt_device_t dev, int cmd, void *arg)
 控制设备 更多...
 
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))
 设置设备接收回调函数 更多...
 
rt_err_t rt_device_set_tx_complete (rt_device_t dev, rt_err_t(*tx_done)(rt_device_t dev, void *buffer))
 设置设备发送完成回调函数 更多...
 

详细描述

I/O设备子系统

设备系统设计为简单且最小的层，用来协助应用程序和驱动程序之间的通信。

设备系统为驱动程序提供五个接口：

枚举类型说明

enum rt_device_class_type

(I/O)设备类型

枚举值
RT_Device_Class_Char 

字符设备

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_Graphic 

图形设备

RT_Device_Class_I2CBUS 

I2C 总线设备

RT_Device_Class_USBDevice 

USB从设备

RT_Device_Class_USBHost 

USB主机总线

RT_Device_Class_SPIBUS 

SPI总线设备

RT_Device_Class_SPIDevice 

SPI 从设备

RT_Device_Class_SDIO 

SDIO 设备

RT_Device_Class_PM 

电源管理设备

RT_Device_Class_Pipe 

管道设备

RT_Device_Class_Portal 

双向管道设备

RT_Device_Class_Timer 

定时器设备

RT_Device_Class_Miscellaneous 

杂项设备

RT_Device_Class_Unknown 

未知设备

函数说明

rt_err_t rt_device_register ( rt_device_t  dev,
const char *  name,
rt_uint16_t  flags 
)

注册设备

此函数注册具有指定名称的设备。设备需要注册到I/O设备管理器中，应用程序才能够访问。

参数
dev设备句柄
name设备名称
flags设备模式标志位
返回
注册成功返回 RT_EOK，失败则返回-RT_ERROR。
rt_err_t rt_device_unregister ( rt_device_t  dev)

删除设备

该函数将删除已注册的设备。当设备注销后的，设备将从设备管理器中移除， 也就不能再通过设备查找搜索到该设备。注销设备不会释放设备控制块占用的内存。

参数
dev设备句柄
返回
注册成功返回 RT_EOK。
rt_device_t rt_device_find ( const char *  name)

查找设备

该函数通过指定的名称查找设备。应用程序根据设备名称获取设备句柄，进而可以操作设备。

参数
name设备的名称
返回
成功则返回已注册的设备句柄, 失败则返回 RT_NULL 。
示例:
adc_vol_sample.c, hwtimer_sample.c, i2c_aht10_sample.c, iwdg_sample.c, pwm_led_sample.c, sd_sample.c, spi_w25q_sample.c , 以及 uart_sample.c.
rt_device_t rt_device_create ( int  type,
int  attach_size 
)

创建设备

此函数根据用户指定的设备类型动态的创建一个设备对象。 调用该接口时，系统会从动态堆内存中分配一个设备控制块， 大小为struct rt_device和attach_size的和，设备的类型由参数type设定。

参数
type设备类型
attach_size用户数据的大小
返回
成功则返回设备句柄，失败则返回RT_NULL。
void rt_device_destroy ( rt_device_t  dev)

销毁设备

该函数将销毁动态创建的设备对象。

参数
dev设备句柄
rt_err_t rt_device_init ( rt_device_t  dev)

初始化设备

该函数将初始化指定的设备。当一个设备已经初始化成功后，调用这个接口将不再重复做初始化。

参数
dev设备句柄
返回
成功返回RT_EOK；失败返回错误码。
示例:
iwdg_sample.c.
rt_err_t rt_device_open ( rt_device_t  dev,
rt_uint16_t  oflag 
)

打开设备

通过设备句柄，应用程序可以打开和关闭设备， 打开设备时会检测设备是否已经初始化，没有初始化则会默认调用初始化接口初始化设备。

参数
dev设备句柄
oflag设备的打开模式标志位
返回
成功返回RT_EOK；失败则返回错误码。
示例:
hwtimer_sample.c, sd_sample.c , 以及 uart_sample.c.
rt_err_t rt_device_close ( rt_device_t  dev)

关闭设备

该函数将关闭指定的设备。

参数
dev设备句柄
返回
成功返回RT_EOK；失败则返回错误码。
rt_size_t rt_device_read ( rt_device_t  dev,
rt_off_t  pos,
void *  buffer,
rt_size_t  size 
)

读取设备

该函数将从设备读取数据。

参数
dev设备句柄
pos读取的偏移量
buffer用于保存读取数据的数据缓冲区
size缓冲区的大小
返回
成功返回实际读取的大小，如果是字符设备，返回大小以字节为单位，如果是块设备，返回的大小以块为单位；失败则返回0。
示例:
hwtimer_sample.c, sd_sample.c , 以及 uart_sample.c.
rt_size_t rt_device_write ( rt_device_t  dev,
rt_off_t  pos,
const void *  buffer,
rt_size_t  size 
)

写设备

该函数将向设备写入数据。

参数
dev设备句柄
pos写入的偏移量
buffer要写入设备的数据缓冲区
size写入数据的大小
返回
成功返回实际写入数据的大小，如果是字符设备，返回大小以字节为单位；如果是块设备，返回的大小以块为单位；失败则返回0。
注解
从0.4.0开始，size / pos代表的是块设备的块。
示例:
hwtimer_sample.c, sd_sample.c , 以及 uart_sample.c.
rt_err_t rt_device_control ( rt_device_t  dev,
int  cmd,
void *  arg 
)

控制设备

该函数将在设备上执行各种控制功能。

参数
dev设备句柄
cmd命令控制字，这个参数通常与设备驱动程序相关。
arg控制命令相关的参数
返回
成功返回RT_EOK；失败则返回错误码。
示例:
hwtimer_sample.c, iwdg_sample.c , 以及 sd_sample.c.
rt_err_t rt_device_set_rx_indicate ( rt_device_t  dev,
rt_err_t(*)(rt_device_t dev, rt_size_t size)  rx_ind 
)

设置设备接收回调函数

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

参数
dev设备句柄
rx_ind回调函数
返回
RT_EOK
示例:
hwtimer_sample.c , 以及 uart_sample.c.
rt_err_t rt_device_set_tx_complete ( rt_device_t  dev,
rt_err_t(*)(rt_device_t dev, void *buffer)  tx_done 
)

设置设备发送完成回调函数

此函数将设置发送完成回调函数。调用这个函数时，回调函数由调用者提供，当硬件设备发送完数据时， 由驱动程序回调这个函数并把发送完成的数据块地址buffer作为参数传递给上层应用。 上层应用（线程）在收到指示时会根据发送buffer的情况，释放buffer内存块或将其作为下一个写数据的缓存。

参数
dev设备句柄
tx_done指示回调函数
返回
RT_EOK