Linux设备驱动程序第三版学习（5）- 高级字符驱动程序操作 - ioctl .

第六章：高级字符驱动程序操作
这章有以下几个部分主要内容：
1） 学习实现ioctl系统调用，它是用于设备控制的公共接口
2） 掌握如何使进程休眠（并唤醒）
3） poll/select
4） 异步通知
5） 定位设备
6） 设备文件的访问控制

以下为第1部分， ioctl的学习。
定义（摘自百度百科）：
    ioctl是设备驱动程序中对设备的I/O通道进行管理的函数。所谓对I/O通道进行管理，就
　　是对设备的一些特性进行控制，例如串口的传输波特率、马达的转速等等。他的调用个数
　　如下：
　　int ioctl(int fd, int cmd, …)；
　　其中fd就是用户程式打开设备时使用open函数返回的文件标示符，cmd就是用户程式对设
　　备的控制命令，至于后面的省略号，那是一些补充参数，一般最多一个，有或没有是和
　　cmd的意义相关的。
　　ioctl函数是文件结构中的一个属性分量（就是在file_operations结构中），就是说如果你的驱动程式提供了对ioctl的支
　　持，用户就能在用户程式中使用ioctl函数控制设备的I/O通道。
实现操作(部分摘自百度百科）：
    在驱动程式中实现的ioctl函数体内，实际上是有一个switch{case}结构，每一个case对
　　应一个命令码，做出一些相应的操作。怎么实现这些操作，这是每一个程式员自己的事
　　情，因为设备都是特定的，这里也没法说。关键在于怎么样组织命令码，因为在ioctl中
　　命令码是唯一联系用户程式命令和驱动程式支持的途径。
　　命令码的组织是有一些讲究的，因为我们一定要做到命令和设备是一一对应的，这样才不
　　会将正确的命令发给错误的设备，或是把错误的命令发给正确的设备，或是把错误的
　　命令发给错误的设备。这些错误都会导致不可预料的事情发生，而当程式员发现了这些奇
　　怪的事情的时候，再来调试程式查找错误，那将是非常困难的事情。
　　所以在Linux核心中是这样定义一个命令码的：
　　____________________________________
　　| 设备类型 | 序列号 | 方向 |数据尺寸|
　　|----------|--------|------|--------|
　　| 8 bit | 8 bit |2 bit |8~14 bit|
　　|----------|--------|------|--------|
　　这样一来，一个命令就变成了一个整数形式的命令码。不过命令码非常的不直观，所以
　　Linux Kernel中提供了一些宏，这些宏可根据便于理解的字符串生成命令码，或是从
　　命令码得到一些用户能理解的字符串以标明这个命令对应的设备类型、设备序列号、数
　　据传送方向和数据传输尺寸。
   我们就来看看这些宏吧：定义在include/asm-generic/ioctl.h中（我用的是2.6.32内核）

#ifndef _IOC_SIZEBITS
# define _IOC_SIZEBITS    14 
#endif

#ifndef _IOC_DIRBITS
# define _IOC_DIRBITS    2   
#endif

#define _IOC_NRMASK    ((1 << _IOC_NRBITS)-1)
#define _IOC_TYPEMASK    ((1 << _IOC_TYPEBITS)-1)
#define _IOC_SIZEMASK    ((1 << _IOC_SIZEBITS)-1)
#define _IOC_DIRMASK    ((1 << _IOC_DIRBITS)-1)

#define _IOC_NRSHIFT    0
#define _IOC_TYPESHIFT    (_IOC_NRSHIFT+_IOC_NRBITS)
#define _IOC_SIZESHIFT    (_IOC_TYPESHIFT+_IOC_TYPEBITS)
#define _IOC_DIRSHIFT    (_IOC_SIZESHIFT+_IOC_SIZEBITS)

/*
 * Direction bits, which any architecture can choose to override
 * before including this file.
 */

#ifndef _IOC_NONE
# define _IOC_NONE    0U
#endif

#ifndef _IOC_WRITE
# define _IOC_WRITE    1U
#endif

#ifndef _IOC_READ
# define _IOC_READ    2U
#endif

#define _IOC(dir,type,nr,size) /
    (((dir)  << _IOC_DIRSHIFT) | /
     ((type) << _IOC_TYPESHIFT) | /
     ((nr)   << _IOC_NRSHIFT) | /
     ((size) << _IOC_SIZESHIFT))

#define _IOC_TYPECHECK(t) (sizeof(t))

/* used to create numbers */
#define _IO(type,nr)        _IOC(_IOC_NONE,(type),(nr),0)
#define _IOR(type,nr,size)    _IOC(_IOC_READ,(type),(nr),(_IOC_TYPECHECK(size)))
#define _IOW(type,nr,size)    _IOC(_IOC_WRITE,(type),(nr),(_IOC_TYPECHECK(size)))
#define _IOWR(type,nr,size)    _IOC(_IOC_READ|_IOC_WRITE,(type),(nr),(_IOC_TYPECHECK(size)))
#define _IOR_BAD(type,nr,size)    _IOC(_IOC_READ,(type),(nr),sizeof(size))
#define _IOW_BAD(type,nr,size)    _IOC(_IOC_WRITE,(type),(nr),sizeof(size))
#define _IOWR_BAD(type,nr,size)    _IOC(_IOC_READ|_IOC_WRITE,(type),(nr),sizeof(size))

/* used to decode ioctl numbers.. */
#define _IOC_DIR(nr)        (((nr) >> _IOC_DIRSHIFT) & _IOC_DIRMASK)
#define _IOC_TYPE(nr)        (((nr) >> _IOC_TYPESHIFT) & _IOC_TYPEMASK)
#define _IOC_NR(nr)        (((nr) >> _IOC_NRSHIFT) & _IOC_NRMASK)
#define _IOC_SIZE(nr)        (((nr) >> _IOC_SIZESHIFT) & _IOC_SIZEMASK)

/* ...and for the drivers/sound files... */

#define IOC_IN        (_IOC_WRITE << _IOC_DIRSHIFT)
#define IOC_OUT        (_IOC_READ << _IOC_DIRSHIFT)
#define IOC_INOUT    ((_IOC_WRITE|_IOC_READ) << _IOC_DIRSHIFT)
#define IOCSIZE_MASK    (_IOC_SIZEMASK << _IOC_SIZESHIFT)
#define IOCSIZE_SHIFT    (_IOC_SIZESHIFT)

================================end of ioctl.h===============================

　　ioctl其实没有什么非常难的东西需要理解，关键是理解cmd命令码是怎么在用户程式里生成
　　并在驱动程式里解析的，程式员最主要的工作量在switch{case}结构中，因为对设备的
　　I/O控制都是通过这一部分的代码实现的。

先来看看scull.h中关于ioctl的definition

01./* 
02. * Ioctl definitions 
03. */  
04.  
05./* Use 'k' as magic number */  
06.#define SCULL_IOC_MAGIC  'k'   
07./* Please use a different 8-bit number in your code */  
08.  
09.#define SCULL_IOCRESET    _IO(SCULL_IOC_MAGIC, 0)   
10.  
11./* 
12. * S means "Set" through a ptr, 
13. * T means "Tell" directly with the argument value 
14. * G means "Get": reply by setting through a pointer 
15. * Q means "Query": response is on the return value 
16. * X means "eXchange": switch G and S atomically 
17. * H means "sHift": switch T and Q atomically 
18. */  
19.#define SCULL_IOCSQUANTUM _IOW(SCULL_IOC_MAGIC,  1, int)   
20.#define SCULL_IOCSQSET    _IOW(SCULL_IOC_MAGIC,  2, int)   
21.#define SCULL_IOCTQUANTUM _IO(SCULL_IOC_MAGIC,   3)   
22.#define SCULL_IOCTQSET    _IO(SCULL_IOC_MAGIC,   4)   
23.#define SCULL_IOCGQUANTUM _IOR(SCULL_IOC_MAGIC,  5, int)   
24.#define SCULL_IOCGQSET    _IOR(SCULL_IOC_MAGIC,  6, int)   
25.#define SCULL_IOCQQUANTUM _IO(SCULL_IOC_MAGIC,   7)   
26.#define SCULL_IOCQQSET    _IO(SCULL_IOC_MAGIC,   8)   
27.#define SCULL_IOCXQUANTUM _IOWR(SCULL_IOC_MAGIC, 9, int)   
28.#define SCULL_IOCXQSET    _IOWR(SCULL_IOC_MAGIC,10, int)   
29.#define SCULL_IOCHQUANTUM _IO(SCULL_IOC_MAGIC,  11)   
30.#define SCULL_IOCHQSET    _IO(SCULL_IOC_MAGIC,  12)   
31.  
32./* 
33. * The other entities only have "Tell" and "Query", because they're 
34. * not printed in the book, and there's no need to have all six. 
35. * (The previous stuff was only there to show different ways to do it. 
36. */  
37.#define SCULL_P_IOCTSIZE _IO(SCULL_IOC_MAGIC,   13)   
38.#define SCULL_P_IOCQSIZE _IO(SCULL_IOC_MAGIC,   14)   
39./* ... more to come */  
40.  
41.#define SCULL_IOC_MAXNR 14   
42.  
43./* 
44. * The ioctl() implementation 
45. */  
46.  
47.int scull_ioctl(struct inode *inode, struct file *filp,  
48.                 unsigned int cmd, unsigned long arg)  
49.{  
50.  
51.    int err = 0, tmp;  
52.    int retval = 0;  
53.      
54.    /* 
55.     * extract the type and number bitfields, and don't decode 
56.     * wrong cmds: return ENOTTY (inappropriate ioctl) before access_ok() 
57.     */  
58.    if (_IOC_TYPE(cmd) != SCULL_IOC_MAGIC) return -ENOTTY;  
59.    if (_IOC_NR(cmd) > SCULL_IOC_MAXNR) return -ENOTTY;  
60.  
61.    /* 
62.     * the direction is a bitmask, and VERIFY_WRITE catches R/W 
63.     * transfers. `Type' is user-oriented, while 
64.     * access_ok is kernel-oriented, so the concept of "read" and 
65.     * "write" is reversed 
66.     */  
67.    if (_IOC_DIR(cmd) & _IOC_READ)  
68.        err = !access_ok(VERIFY_WRITE, (void __user *)arg, _IOC_SIZE(cmd));  
69.    else if (_IOC_DIR(cmd) & _IOC_WRITE)  
70.        err =  !access_ok(VERIFY_READ, (void __user *)arg, _IOC_SIZE(cmd));  
71.    if (err) return -EFAULT;  
72.  
73.    switch(cmd) { /*我们写驱动时的重点就在下边，根据实际的硬件特性对于我们定义的ioctl命令进行操作。以下只是针对SCULL所写的，不解释。*/  
74.  
75.      case SCULL_IOCRESET:  
76.        scull_quantum = SCULL_QUANTUM;  
77.        scull_qset = SCULL_QSET;  
78.        break;  
79.          
80.      case SCULL_IOCSQUANTUM: /* Set: arg points to the value */  
81.        if (! capable (CAP_SYS_ADMIN))  
82.            return -EPERM;  
83.        retval = __get_user(scull_quantum, (int __user *)arg);  
84.        break;  
85.  
86.      case SCULL_IOCTQUANTUM: /* Tell: arg is the value */  
87.        if (! capable (CAP_SYS_ADMIN))  
88.            return -EPERM;  
89.        scull_quantum = arg;  
90.        break;  
91.  
92.      case SCULL_IOCGQUANTUM: /* Get: arg is pointer to result */  
93.        retval = __put_user(scull_quantum, (int __user *)arg);  
94.        break;  
95.  
96.      case SCULL_IOCQQUANTUM: /* Query: return it (it's positive) */  
97.        return scull_quantum;  
98.  
99.      case SCULL_IOCXQUANTUM: /* eXchange: use arg as pointer */  
100.        if (! capable (CAP_SYS_ADMIN))  
101.            return -EPERM;  
102.        tmp = scull_quantum;  
103.        retval = __get_user(scull_quantum, (int __user *)arg);  
104.        if (retval == 0)  
105.            retval = __put_user(tmp, (int __user *)arg);  
106.        break;  
107.  
108.      case SCULL_IOCHQUANTUM: /* sHift: like Tell + Query */  
109.        if (! capable (CAP_SYS_ADMIN))  
110.            return -EPERM;  
111.        tmp = scull_quantum;  
112.        scull_quantum = arg;  
113.        return tmp;  
114.          
115.      case SCULL_IOCSQSET:  
116.        if (! capable (CAP_SYS_ADMIN))  
117.            return -EPERM;  
118.        retval = __get_user(scull_qset, (int __user *)arg);  
119.        break;  
120.  
121.      case SCULL_IOCTQSET:  
122.        if (! capable (CAP_SYS_ADMIN))  
123.            return -EPERM;  
124.        scull_qset = arg;  
125.        break;  
126.  
127.      case SCULL_IOCGQSET:  
128.        retval = __put_user(scull_qset, (int __user *)arg);  
129.        break;  
130.  
131.      case SCULL_IOCQQSET:  
132.        return scull_qset;  
133.  
134.      case SCULL_IOCXQSET:  
135.        if (! capable (CAP_SYS_ADMIN))  
136.            return -EPERM;  
137.        tmp = scull_qset;  
138.        retval = __get_user(scull_qset, (int __user *)arg);  
139.        if (retval == 0)  
140.            retval = put_user(tmp, (int __user *)arg);  
141.        break;  
142.  
143.      case SCULL_IOCHQSET:  
144.        if (! capable (CAP_SYS_ADMIN))  
145.            return -EPERM;  
146.        tmp = scull_qset;  
147.        scull_qset = arg;  
148.        return tmp;  
149.  
150.        /* 
151.         * The following two change the buffer size for scullpipe. 
152.         * The scullpipe device uses this same ioctl method, just to 
153.         * write less code. Actually, it's the same driver, isn't it? 
154.         */  
155.  
156.      case SCULL_P_IOCTSIZE:  
157.        scull_p_buffer = arg;  
158.        break;  
159.  
160.      case SCULL_P_IOCQSIZE:  
161.        return scull_p_buffer;  
162.  
163.  
164.      default:  /* redundant, as cmd was checked against MAXNR */  
165.        return -ENOTTY;  
166.    }  
167.    return retval;  
168.  
169.}