本附录提供IOM(I/O迷你驱动)接口的详细描述。
F.1 迷你驱动接口概览
迷你驱动接口指定了如何实现一个迷你驱动。
功能
一个迷你驱动应当实现以下功能:
- mdBindDev:将设备绑定至迷你驱动。
- mdControlChan:执行信号控制命令。
- mdCreateChan:创建设备信道。
- mdDeleteChan:删除一个信道。
- mdSubmitChan:提交数据包至信道处理。
- mdUnBindDev:将设备从迷你驱动解绑。
描述
迷你驱动包含指定设备驱动的一部分。一旦为迷你驱动创建指定的函数,应用集成商可以很容易地通过GIO信道使用你的迷你驱动。
以下小节详细描述如何实现迷你驱动函数。一旦实现,这些函数通过一个IOM_Fxns类型接口表引用,应用程序将参考整合迷你驱动。例如:
IOM_Fxns UART_FXNS =
{ mdBindDev, IOM_UNBINDDEVNOTIMPL, mdControlChan, mdCreateChan, mdDeleteChan, mdSubmitChan }; |
注意:任意你选择不实现的迷你函数都应该以IOM_xxxNOTIMPL为名称加入迷你函数表,xxx对应函数名称。另外,你也可以实现一个返回IOM_ENOTIMPL状态的函数。
常量、类型和结构
以下代码可在 <bios_install_dir>/packages/ti/sysbios/io/IOM.h .中找到:
/* Modes for mdCreateChan */
#define IOM_INPUT 0x0001 #define IOM_OUTPUT 0x0002 #define IOM_INOUT (IOM_INPUT | IOM_OUTPUT) /* IOM Status Codes */ #define IOM_COMPLETED 0 /* I/O successful */ #define IOM_PENDING 1 /* I/O queued and pending */ #define IOM_FLUSHED 2 /* I/O request flushed */ #define IOM_ABORTED 3 /* I/O aborted */ /* IOM Error Codes */ #define IOM_EBADIO - 1 /* generic failure */ #define IOM_ETIMEOUT - 2 /* timeout occurred */ #define IOM_ENOPACKETS - 3 /* no packets available */ #define IOM_EFREE - 4 /* unable to free resources */ #define IOM_EALLOC - 5 /* unable to alloc resource */ #define IOM_EABORT - 6 /* I/O aborted uncompleted*/ #define IOM_EBADMODE - 7 /* illegal device mode */ #define IOM_EOF - 8 /* end-of-file encountered */ #define IOM_ENOTIMPL - 9 /* operation not supported */ #define IOM_EBADARGS - 10 /* illegal arguments used */ #define IOM_ETIMEOUTUNREC - 11 /* unrecoverable timeout */ #define IOM_EINUSE - 12 /* device already in use */ /* Command codes for IOM_Packet */ #define IOM_READ 0 #define IOM_WRITE 1 #define IOM_ABORT 2 #define IOM_FLUSH 3 #define IOM_USER 128 /* 0-127 reserved for system */ /* Command codes for GIO_control and mdControlChan */ #define IOM_CHAN_RESET 0 /* reset channel only */ #define IOM_CHAN_TIMEDOUT 1 /* channel timeout occurred */ #define IOM_DEVICE_RESET 2 /* reset entire device */ typedef struct IOM_Fxns { IOM_TmdBindDev mdBindDev; IOM_TmdUnBindDev mdUnBindDev; IOM_TmdControlChan mdControlChan; IOM_TmdCreateChan mdCreateChan; IOM_TmdDeleteChan mdDeleteChan; IOM_TmdSubmitChan mdSubmitChan; } IOM_Fxns; #define IOM_BINDDEVNOTIMPL (IOM_TmdBindDev)IOM_mdNotImpl #define IOM_UNBINDDEVNOTIMPL (IOM_TmdUnBindDev)IOM_mdNotImpl #define IOM_CONTROLCHANNOTIMPL (IOM_TmdControlChan)IOM_mdNotImpl #define IOM_CREATECHANNOTIMPL (IOM_TmdCreateChan)IOM_mdNotImpl #define IOM_DELETECHANNOTIMPL (IOM_TmdDeleteChan)IOM_mdNotImpl #define IOM_SUBMITCHANNOTIMPL (IOM_TmdSubmitChan)IOM_mdNotImpl typedef struct IOM_Packet /* frame object */ { Queue_Elem link; /* queue link */ Ptr addr; /* buffer address */ SizeT size; /* buffer size */ UArg arg; /* user argument */ UInt cmd; /* mini-driver command */ Int status; /* status of command */ UArg misc; /* reserved for driver */ } IOM_Packet; /* Mini-driver's callback function. */ Void (*IOM_TiomCallback)(Ptr arg, IOM_Packet *packet); |
mdBindDev
将设备绑定至迷你驱动
C 接口
语法
status = mdBindDev(*devp, devid, devParams);
参数
Ptr *devp; /*address for global device data pointer*/Int devid; /* device id */Ptr devParams; /* pointer to config parameters */
返回值
Int status; /* success or failure code */
描述
mdBindDev函数由SYS/BIOS在设备初始化期间调用。每个配置设备调用它一次,并且是在迷你驱动初始化函数之后调用。
此函数通常使用指定设备全局数据,如中断IDs和全局数据结构(ROM-ability的)。另外系统资源可通过迷你驱动在运行时分配。
devp参数是指向函数存放全局设备数据指针的地址。
devid参数用于确定具有特定类型的多个设备的系统中的具体设备。例如,几个McBSP迷你驱动程序使用devid参数指定分配和配置的McBSP端口。
devParams参数是用于配置设备的配置参数的指针。
此函数成功执行将返回IOM_COMPLETED。如果失败,它将返回F.1节
迷你驱动接口概览所罗列的负数的错误编号。如果此函数返回一个错误编号,SYS/BIOS初始化失败,调用System_abort()。
mdControlChan
执行信道控制命令
C接口
语法
status = mdControlChan (chanp, cmd, arg);
参数
Ptr chanp; /* channel handle */UInt cmd; /* control functionality to perform */Ptr arg; /* optional device-defined data structure */
返回值
Int status; /* success or failure code */
描述
一个类驱动调用此函数会使得迷你驱动执行某种类型的控制功能。例如,它可使迷你驱动重启设备或获取设备状态。调用GIO_control导致相应迷你驱动的mdControlChan函数执行。
chanp参数指示标识设备实例的信道句柄。
cmd参数指示实施哪个控制功能。
/* Command codes for GIO_control and mdControlChan */
#define IOM_CHAN_RESET 0 /* reset channel only */ #define IOM_CHAN_TIMEDOUT 1 /* channel timeout occurred */ #define IOM_DEVICE_RESET 2 /* reset entire device */ |
arg参数是可选参数,是用于在设备和应用间传递控制信息的设备定义数据结构。
如果成功,此函数返回IOM_COMPLETED。如果不支持提供cmd值,此函数将返回一个IOM_EMOTIMPL状态。
mdCreateChan
创建一个设备信道
C接口
语法
status = mdCreateChan (*chanp, devp, name, mode, chanParams, cbFxn, cbArg);
参数
Ptr *chanp; /* channel handle */Ptr devp; /* device global data structure */String name /* name of device instance */Int mode /* input or output mode */Ptr chanParams /*pointer to channel parameters */IOM_TiomCallback cbFxn /* pointer to callback function */Ptr cbArg /* callback function argument */
返回值
Int status; /* success or failure code */
描述
类驱动调用此函数来创建一个信道实例。调用GIO_create导致相应迷你驱动的mdCreateChan函数执行。
chanp参数提供
chanp参数指向此函数存储标识设备实例信道句柄的地址。信道句柄是指定设备数据结构指针。见243页的“mdBindDev”查看实例。
devp参数是指向设备全局数据结构的指针。它是由迷你驱动调用mdBindDev所返回的值。
name参数是设备实例名称。这是从SYS/BIOS设备驱动表获取一个完整匹配后剩余的设备名称。例如,它可能包含信道参数。
mdoe参数指示设备是以输入还是输出模式打开,或两者皆有。模式值可为IOM_INPUT、IOM_OUTPUT或IOM_INOUT。如果你的设备不支持一个或多个模式,此函数将返回IOM_EBADMODE以表示不支持模式。
chanParams参数用于向迷你驱动传递设备或域特定参数。
cbFxn参数是指向回调函数的函数指针,当完成一个请求时,迷你驱动调用此函数。
cbArg参数在迷你驱动调用回调函数时传递参数用。
通常,mdCreateChan函数将回调函数及它的参数放置在设备特定数据结构,如:
chan->cbFxn = cbFxn;
chan->cbArg = cbArg; |
如果成功,此函数将返回IOM_COMPLETED。如果失败此函数返回一个负数错误编码列表里的值。
mdDeleteChan
删除一个信道
C接口
语法
status = mdDeleteChan (chanp)
参数
Ptr chanp; /* channel handle */
返回值
Int status; /* success or failure code */
描述
类驱动调用此函数删除指定信道实例。调用GIO_delete导致相应迷你驱动的mdDeleteChan函数执行。
chanp参数提供标识设备实例的信道句柄。信道句柄是指向设备特定数据结构指针。参考mdBindDev话题里的实例。
如果成功,此函数返回IOM_COMPLETED。如果不成功,此函数将返回一个F.1节所罗列的负数错误编码。
mdSubmitChan
提交数据包给信道处理
C接口
语法
status = mdSubmitChan (chanp, *packet);
参数
Ptr chanp; /* channel handle */IOM_Packet *packet; /* pointer to IOM_Packet */
返回值
Int status; /* success or failure code */
描述
类驱动调用此函数以使迷你驱动处理IOM_Packet。调用 GIO_submit、GIO_read、GIO_write、GIO_abort和GIO_flush使得迷你驱动的mdSubmitChan函数执行。
注意:迷你驱动函数mdSubmitChan必须书写为可重入的,这样就可以从多个线程上下文调用。
chanp参数提供标识设备实例的信道句柄。信道句柄是一个设备特定数据结构指针。见mdBindDev话题里的实例。
packet参数指向一个IOM_Packet类型结构体。此结构体定义如下:
typedef
struct IOM_Packet
/* frame object */
{ Queue_Elem link; /* queue link */ Ptr addr; /* buffer address */ SizeT size; /* buffer size */ UArg arg; /* user argument */ UInt cmd; /* mini-driver command */ Int status; /* status of command */ UArg misc; /* reserved for driver */ } IOM_Packet; |
cmd值为下列之一:
#define IOM_READ
0
#define IOM_WRITE 1 #define IOM_ABORT 2 #define IOM_FLUSH 3 |
附加的cmd编码可被添加至域特定命令。这样的编码应为大于127的常量。见iom.h文件查阅这些cmd编码。
如果cmd编码是IOM_READ或IOM_WRITE,这些函数将把数据包压入悬停列表队列。如果cmd编码是IOM_ABORT,此函数将中止读和写数据包。如果cmd编码是IOM_FLUSH,此函数将完全排队写,但中止排队读。
如果此函数成功完成一个读或写IOM_Packet请求,它将返回IOM_COMPLETED。如果此函数压队一个读或写请求,它将返回IOM_PENDING。如果此函数成功中止或清除一个数据包,它将返回IOM_COMPLETED。如果不成功,此函数将返回负数错误编码表中的值。
mdUnBindDev
从迷你驱动解绑设备
C接口
语法
status = mdUnBindDev(devp);
参数
Ptr devp; /* global device data pointer */
返回值
Int status; /* success or failure code */
描述
此函数将释放由mdBindDev函数分配的资源。
目前,此函数不作为任何GIO函数结果调用。它可在未来支持动态设备驱动载入或卸载使用。
devp参数是设备的全局数据结构指针。它是迷你驱动的mdBindDev调用返回值。
如果成功,此函数将返回IOM_COMPLETED。如果不成功,此函数将返回一个负数错误编码。