Linux 设备驱动程序（一）（中）

// 接口
       #include <sys/ioctl.h>

       int ioctl(int fd, unsigned long cmd, ...);

// ==================================================

// 应用示例
uint16 data16;
if ((fd = socket(AF_INET, SOCK_STREAM, 0)) < 0) {
  printf("socket failed\n\r");
}
if (ioctl(fd, SIOCSIFVLAN_PVID_PRI, &data16) < 0) {
  printf("ioctl pvid failed\n\r");
}

// 2.6.34
// 从2.6.36 以后的内核已经废弃了 file_operations 中的 ioctl 函数指针，
// 取而代之的是 unlocked_ioctl， 用户空间对应的系统调用没有发生变化。
int (*ioctl) (struct inode *, struct file *, unsigned int cmd, 
        unsigned long arg);
long (*unlocked_ioctl) (struct file *, unsigned int cmd, unsigned long arg);
long (*compat_ioctl) (struct file *, unsigned int cmd, unsigned long arg);        

wait_event(queue, condition)
wait_event_interruptible(queue, condition)
wait_event_timeout(queue, condition, timeout)
wait_event_interruptible_timeout(queue, condition, timeout)

#include <linux/ioctl.h>
// 这个头文件声明了用于定义 ioctl命令的所有的宏。它现在包含在 <linux/fs.h> 中。

#include <asm/uaccess.h>
int put_user(datum,ptr);
int get_user(local,ptr);
int __put_user(datum,ptr);
int __get_user(local,ptr);
/*
 * 用于向(或从)用户空间保存(或获取)单个数据项的宏。传送的字节数目由
 * sizeof(*ptr) 决定。前两个要先调用 access_ok，后两个(__put_user 和
 * __get_user)则假设 access_ok 已经被调用过了。
*/


#include <linux/capability.h>
// 定义有各种 CAP_符号，用于描述用户空间进程可能拥有的权能操作。
int capable(int capability);
// 如果进程具有指定的权能，返回非零值。


#include <linux/wait.h>
typedef struct { /* */ } wait_queue_head_t;
void init_waitqueue_head(wait_queue_head_t *queue);
DECLARE_WAIT_QUEUE_HEAD(queue);
/*
 * 预先定义的 Linux 等待队列类型。wait_queue_head_t 类型必须显式地初始化，
 * 初始化方法可在运行时用 init_waitqueue_head，或在编译时用 DECLARE_WAIT_QUEUE_HEAD
*/

void wait_event(wait_queue_head_t q, int condition);
int wait_event_interruptible(wait_queue_head_t q, int condition);
int wait_event_timeout(wait_queue_head_t q, int condition, int time);
int wait_event_interruptible_timeout(wait_queue_head_t q, int condition,
                  int time);
// 使进程在指定的队列上休眠，直到给定的 condition值为真。

void wake_up(struct wait_queue **q);
void wake_up_interruptible(struct wait_queue **q);
void wake_up_nr(struct wait_queue **q, int nr);
void wake_up_interruptible_nr(struct wait_queue **q, int nr);
void wake_up_all(struct wait_queue **q);
void wake_up_interruptible_all(struct wait_queue **q);
void wake_up_interruptible_sync(struct wait_queue **q);
/*
 * 这些函数唤醒休眠在队列 q 上的进程。_interruptible形式的函数只能唤醒可中断的
 * 进程。通常，只会唤醒一个独占等待进程，但其行为可通过 _nr 或_all 形式改变。
 * _sync 版本的唤醒函数在返回前不会重新调度 CPU。
*/


#include <linux/sched.h>
set_current_state(int state);
// 设置当前进程的执行状态。TASK_RUNNING 表示准备运行，而休眠状态是
// TASK_INTERRUPTIBLE 和 TASK_UNINTERRUPTIBLE。
void schedule(void);
// 从运行队列中选择一个可运行进程。选定的进程可以是 current 或另一个不同的进程。


typedef struct { /* */ } wait_queue_t;
init_waitqueue_entry(wait_queue_t *entry, struct task_struct *task);
// wait_queue_t 类型用来将某个进程放置到一个等待队列上。

void prepare_to_wait(wait_queue_head_t *queue, wait_queue_t *wait, int state);
void prepare_to_wait_exclusive(wait_queue_head_t *queue, wait_queue_t *wait,
                int state);
void finish_wait(wait_queue_head_t *queue, wait_queue_t *wait);
// 可用于手工休眠代码的辅助函数。

void sleep_on(wiat_queue_head_t *queue);
void interruptible_sleep_on(wiat_queue_head_t *queue);
// 已废弃的两个函数，它们将当前进程无条件地置于休眠状态。


#include <linux/poll.h>
void poll_wait(struct file *filp, wait_queue_head_t *q, poll_table *p)
// 将当前进程置于某个等待队列但并不立即调度。该函数主要用于设备驱动程序的 poll 方法。

int fasync_helper(struct inode *inode, struct file *filp, int mode, 
          struct fasync_struct **fa);
// 用来实现 fasync 设备方法的辅助函数。mode 参数取传入该方法的同一值，而 fa
// 指向设备专有的 fasync_struct*。

void kill_fasync(struct fasync_struct *fa, int sig, int band);
// 如果驱动程序支持异步通知，则这个函数可以用来发送一个信号给注册在 fa 中的进程。

int nonseekable_open(struct inode *inode, struct file *filp);
loff_t no_llseek(struct file *file, loff_t offset, int whence);
// 任何不支持定位的设备都应该在其 open方法中调用 nonseekable_open。这类设备
// 还应该在其 llseek 方法中使用 no_llseek。

#include <linux/jiffies.h>
int time_after(unsigned long a, unsigned long b);
int time_before(unsigned long a, unsigned long b);
int time_after_eq(unsigned long a, unsigned long b);
int time_before_eq(unsigned long a, unsigned long b);

diff = (long)t2 - (long)t1;

msec = diff * 1000 / HZ;

#include <linux/time.h>
unsigned long timespec_to_jiffies(struct timespec *value);
void jiffies_to_timespec(unsigned long jiffies, struct timespec *value);
unsigned long timeval_to_jiffies(struct timeval *value);
void jiffies_to_timeval(unsigned long jiffies, struct timeval *value);

#include <linux/jiffies.h>
u64 get_jiffies_64(void);

/* Converts Gregorian date to seconds since 1970-01-01 00:00:00.
 * Assumes input in normal date format, i.e. 1980-12-31 23:59:59
 * => year=1980, mon=12, day=31, hour=23, min=59, sec=59.
 *
 * [For the Julian calendar (which was used in Russia before 1917,
 * Britain & colonies before 1752, anywhere else before 1582,
 * and is still in use by some communities) leave out the
 * -year/100+year/400 terms, and add 10.]
 *
 * This algorithm was first published by Gauss (I think).
 *
 * WARNING: this function will overflow on 2106-02-07 06:28:16 on
 * machines where long is 32-bit! (However, as time_t is signed, we
 * will already get problems at other places on 2038-01-19 03:14:08)
 */
unsigned long
mktime(const unsigned int year0, const unsigned int mon0,
       const unsigned int day, const unsigned int hour,
       const unsigned int min, const unsigned int sec)
{
  unsigned int mon = mon0, year = year0;

  /* 1..12 -> 11,12,1..10 */
  if (0 >= (int) (mon -= 2)) {
    mon += 12;  /* Puts Feb last since it has leap day */
    year -= 1;
  }

  return ((((unsigned long)
      (year/4 - year/100 + year/400 + 367*mon/12 + day) +
      year*365 - 719499
      )*24 + hour /* now have hours */
    )*60 + min /* now have minutes */
  )*60 + sec; /* finally seconds */
}

EXPORT_SYMBOL(mktime);

/**
 * do_gettimeofday - Returns the time of day in a timeval
 * @tv:   pointer to the timeval to be set
 *
 * NOTE: Users should be converted to using getnstimeofday()
 */
void do_gettimeofday(struct timeval *tv)
{
  struct timespec now;

  getnstimeofday(&now);
  tv->tv_sec = now.tv_sec;
  tv->tv_usec = now.tv_nsec/1000;
}

EXPORT_SYMBOL(do_gettimeofday);

while (time_before(jiffies, j1))
  cpu_relax();

while (time_before(jiffies, j1))
  schedule();

// include/linux/wait.h
#define wait_event_timeout(wq, condition, timeout)      \
({                  \
  long __ret = timeout;           \
  if (!(condition))             \
    __wait_event_timeout(wq, condition, __ret);   \
  __ret;                \
})

#define __wait_event_interruptible(wq, condition, ret)      \
do {                  \
  DEFINE_WAIT(__wait);            \
                  \
  for (;;) {              \
    prepare_to_wait(&wq, &__wait, TASK_INTERRUPTIBLE);  \
    if (condition)            \
      break;            \
    if (!signal_pending(current)) {       \
      schedule();         \
      continue;         \
    }             \
    ret = -ERESTARTSYS;         \
    break;              \
  }               \
  finish_wait(&wq, &__wait);          \
} while (0)

#include <linux/delay.h>
void ndelay(unsigned long nsecs);
void udelay(unsigned long usecs);
void mdelay(unsigned long msecs);

// arch/avr32/lib/delay.c
inline void __const_udelay(unsigned long xloops)
{
  unsigned long long loops;

  asm("mulu.d %0, %1, %2"
      : "=r"(loops)
      : "r"(current_cpu_data.loops_per_jiffy * HZ), "r"(xloops));
  __delay(loops >> 32);
}

void __udelay(unsigned long usecs)
{
  __const_udelay(usecs * 0x000010c7); /* 2**32 / 1000000 (rounded up) */
}

void __ndelay(unsigned long nsecs)
{
  __const_udelay(nsecs * 0x00005); /* 2**32 / 1000000000 (rounded up) */
}

// arch/xtensa/include/asm/delay.h
static inline void __delay(unsigned long loops)
{
  /* 2 cycles per loop. */
  __asm__ __volatile__ ("1: addi %0, %0, -2; bgeui %0, 2, 1b"
      : "=r" (loops) : "0" (loops));
}

// include/linux/timer.h
struct timer_list {
  /* ... */
  unsigned long expires;
  void (*function)(unsigned long);
  unsigned long data;
};

void init_timer(struct timer_list *timer);
struct timer_list TIMER_INITIALIZER(_function, _expires, _data);

void add_timer(struct timer_list *timer);
int del_timer(struct timer_list *timer);

int mod_timer(struct timer_list *timer, unsigned long expires);

int del_timer_sync(struct timer_list *timer);

void tasklet_enable(struct tasklet_struct *t);

void tasklet_schedule(struct tasklet_struct *t);

INIT_WORK(struct work_struct *work, void (*function)(void *), void *data);
PREPARE_WORK(struct work_struct *work, void (*function) (void *), void *data);

int cancel_delayed_work(struct work_struct *work);

#include <linux/param.h>

#include <linux/jiffies.h>
volatile unsigned long jiffies
u64 jiffies_64

u64 get_jiffies_64(void);
// 无竞态地获取 jiffies_64 的值。

#include <linux/time.h>
unsigned long timespec_to_jiffies(struct timespec *value);
void jiffies_to_timespec(unsigned long jiffies, struct timespec *value);
unsigned long timeval_to_jiffies(struct timeval *value);
void jiffies_to_timeval(unsigned long jiffies, struct timeval *value);
// 在 jiffies 表示的时间和其他表示法之间转换。

#include <linux/timex.h>
cycles_t get_cycles(void);
// 以平台无关的方式返回时间戳计数器。如果 CPU 不提供时间戳特性，则返回 0。

#include <linux/time.h>
unsigned long mktime(year, mon, day, h, m, s);
// 根据 6 个无符号的 int 参数返回自 Epoch 以来的秒数。

void do gettimeofday(struct timeval *tv);
// 以自 Epoch 以来的秒数和毫秒数的形式返回当前时间，并且以硬件能提供的最好分
// 辨率返回。在大多数平台上，分辨率是微秒或更好的级别，但某些平台只能提供 jiffies 级
// 的分辨率。

struct timespec current_kernel_time(void);
// 以 jiffies 为分辨率返回当前时间。

#include <linux/wait.h>
long wait_event_interruptible_timeout(wait_queue_head_t *q, condition, signed long timeout);
// 使当前进程休眠在等待队列上，并指定用 jiffies 表达的超时值。如果要进入不可中
// 断休眠，则应使用 schedule_timeout（见下）。

#include <linux/sched.h>
signed long schedule_timeout(signed long timeout);
// 调用调度器，确保当前进程可在给定的超时值之后被唤醒。调用者必须首先调用
// set_current_state 将自己置于可中断或不可中断的休眠状态。

#include <linux/delay.h>
void ndelay(unsigned long nsecs);
void udelay(unsigned long usecs);
void mdelay(unsigned long msecs);
// 引入整数的纳秒、微秒和毫秒级延迟。实际达到的延迟至少是请求的值，但可能更
// 长。传入每个函数的参数不能超过平台相关的限制（通常是几千）。

void msleep(unsigned int millisecs);
unsigned long msleep_interruptible(unsigned int millisecs);
void ssleep(unsigned int seconds);
// 使进程休眠给定的毫秒数（或使用 ssleep 休眠给定的秒数）。

#include <asm/hardirq.h>
int in_interrupt(void);
int in_atomic(void);
// 返回布尔值以告知调用代码是否在中断上下文或者在原子上下文中执行。中断上下
// 文在进程上下文之外，可能正处理硬件或软件中断。原子上下文是指不能进行调度
// 的时间点，比如中断上下文或者拥有自旋锁时的进程上下文。

#include <linux/timer.h>
void init_timer(struct timer_list * timer);
struct timer_list TIMER_INITIALIZER(_function, _expires, _data);
// 上面的函数以及静态声明定时器结构的宏是初始化 timer_list 数据结构的两种方式。

void add_timer(struct timer_list * timer);
// 注册定时器结构，以在当前 CPU 上运行。
int mod_timer(struct timer_list *timer, unsigned long expires);
// 修改一个已经调度的定时器结构的到期时间。它也可以替代 add_timer 函数使用。
int timer_pending(struct timer_list * timer);
// 返回布尔值的宏、用来判断给定的定时器结构是否已经被注册运行。
void del_timer(struct timer_list * timer);
void del_timer_sync(struct timer_list * timer);
// 从活动定时器清单中删除一个定时器。后一个函数确保定时器不会在其他 CPU 上运行。

#include <linux/interrupt.h>
DECLARE_TASKLET(name, func, data);
DECLARE_TASKLET_DISABLED(name, func, data);
void tasklet_init(struct tasklet_struct *t, void (*func) (unsigned long),
          unsigned long data);
// 前面两个宏声明一个 tasklet 结构，而 tasklet_init 函数初始化一个通过分配或者其
// 他途径获得的 tasklet 结构。第二个 DESCLARE 宏禁用给定的 tasklet。

void tasklet_disable(struct tasklet_struct *t);
void tasklet_disable_nosync(struct tasklet_struct *t);
void tasklet_enable(struct tasklet_struct *t);
// 禁用或重新启用某个 tasklet。每次禁止都要匹配一次使能（我们可以禁用一个已经
// 被禁用的 tasklet）。tasklet_disable 函数会在 tasklet 正在其他 CPU 上运行时等待，
// 而 nosync 版本不会完成这个额外的步骤。

void tasklet_schedule(struct tasklet_struct *t);
void tasklet_hi_schedule(struct tasklet_struct *t);
// 调度运行某个 tasklet，可以是"通常"的 tasklet或者一个高优先级的 tasklet。当执
// 行软件中断时，高优先级的 tasklet 会被首先处理，而通常的 tasklet 最后运行。

void tasklet_kill(struct tasklet_struct *t);
// 如果指定的 tasklet 被调度运行，则将其从活动链表中删除。和 tasklet_disable 类
// 似，该函数可在 SMP 系统上阻塞，以便等待正在其他 CPU 上运行的该 tasklet 终止。

#include <linux/workqueue.h>
struct workqueue_struct;
struct work_struct;
// 上述结构分别表示工作队列和工作入口项。

struct workqueue_struct *create_workqueue(const char *name);
struct workqueue_struct *create_singlethread_workqueue(const char *name);
void destroy_workqueue(struct workqueue_struct *queue);
// 用于创建和销毁工作队列的函数。调用 create_workqueue 将创建一个队列，且系统
// 中的每个处理器上都会运行一个工作线程；相反，create_singlethread_workqueue
// 只会创建单个工作进程。

DECLARE_WORK(name, void (*function)(void *), void *data);
INIT_WORK(struct work_struct *work, void (*furction)(void *), void *data);
PREPARE_WORK(struct work_struct *work, vo.d (*function) (void *),void *data);
// 用于声明和初始化工作队列入口项的宏。

int queue_work(struct workqueue_struct *queue, struct work_struct *work);
int queue_delayed_work(struct workqueue_struct *queue, struct
            work_struct *work, unsigned long delay);
// 用来安排工作以便从工作队列中执行的函数。

int cancel_delayed_work(struct work_struct *work);
void flush_workqueue(struct workqueue_struct *queue);
// 使用 cancel_delayed_work 可从工作队列中删除一个入口项； flush_workqueue 确保
// 系统中任何地方都不会运行任何工作队列入口项。

int schedule_work(struct work_struct *work);
int schedule_delayed_work(struct work_struct *work, unsigned long delay);
void flush_scheduled_work(void);
// 使用共享工作队列的函数。