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

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**",
                "/usr/src/linux-headers-4.15.0-142/include/",
                "/usr/src/linux-headers-4.15.0-142/arch/x86/include",
                "/usr/src/linux-headers-4.15.0-142/"
            ],
            "defines": [],
            "compilerPath": "/usr/bin/gcc",
            "cStandard": "c11",
            "cppStandard": "c++17",
            "intelliSenseMode": "linux-gcc-x64"
        }
    ],
    "version": 4
}

/lib/modules/`uname -r`/
# 其值为： /usr/src/linux-headers-4.15.0-142/

// hello.c
#include <linux/init.h>
#include <linux/module.h>

MODULE_LICENSE("Dual BSD/GPL");

static int hello_init(void) {
    printk(KERN_DEBUG "Hello, world\n");
    return 0;
}

static void hello_exit(void) {
    printk(KERN_DEBUG "Goodbye, cruel world\n");
}

module_init(hello_init);
module_exit(hello_exit);

static char *whom = "world";
static int howmany = 1;
module_param(howmany, int, S_IRUGO);
module_param(whom, charp, S_IRUGO);

module_param_array(name,type,num, perm);

ls /sys/module/hello/ -l
total 0
-r--r--r-- 1 root root 4096 5月   8 14:48 coresize
drwxr-xr-x 2 root root    0 5月   8 14:48 holders
-r--r--r-- 1 root root 4096 5月   8 14:48 initsize
-r--r--r-- 1 root root 4096 5月   8 14:48 initstate
drwxr-xr-x 2 root root    0 5月   8 14:48 notes
-r--r--r-- 1 root root 4096 5月   8 14:48 refcnt
drwxr-xr-x 2 root root    0 5月   8 14:48 sections
-r--r--r-- 1 root root 4096 5月   8 14:48 srcversion
-r--r--r-- 1 root root 4096 5月   8 14:48 taint
--w------- 1 root root 4096 5月   8 14:48 uevent

#include<linux/init.h>
module_init(init_function);
module_exit(cleanup_function);

// 用于指定模块的初始化和清除函数的宏。

#include <linux/sched.h>

// 最重要的头文件之一。该文件包含驱动程序使用的大部分内核API的定义，包括睡眠函数以及各种变量声明。

int register_chrdev_region(dev_t first, unsigned count, const char *name)

void unregister_chrdev_region(dev_t first, unsigned int count);

#!/bin/sh
module="scull"
device="scull"
mode="664"

# 使用传入到该脚本的所有参数调用insmod,同时使用路径名来指定模块位置,
# 这是因为新的modutils默认不会在当前目录中查找模块。
/sbin/insmod ./$module.ko $* || exit 1

# 删除原有节点
rm -f /dev/${device}[0-3]

major=$(awk "\$2= =\"$module\"{print \$1}" /proc/devices)
mknod /dev/${device}0 c $major 0
mknod /dev/${device}1 c $major 1
mknod /dev/${device}2 c $major 2
mknod /dev/${device}3 c $major 3

# 给定适当的组属性及许可,并修改属组。
# 并非所有的发行版都具有 staff 组, 有些有 wheel 组。
group="staff"
grep -q '^staff:' /etc/group || group="wheel"

chgrp $group /dev/${device}[0-3]
chmod $mode /dev/${device}[0-3]

// include/linux/fs.h
/*
 * NOTE:
 * read, write, poll, fsync, readv, writev, unlocked_ioctl and compat_ioctl
 * can be called without the big kernel lock held in all filesystems.
 */
struct file_operations {
  /* 
   * 第一个 file_operations 字段并不是一个操作;相反，它是指向"拥有"该结
   * 构的模块的指针。内核使用这个字段以避免在模块的操作正在被使用时卸载该模
   * 块。几乎在所有的情况下，该成员都会被初始化为 THIS_MODULE，它是定义在
   * <linux/module.h> 中的一个宏。
  */
  struct module *owner;
  /* 
   * 方法 llseek 用来修改文件的当前读写位置，并将新位置作为(正的)返回值返回。
   * 参数 loff_t 一个"长偏移量"，即使在 32 位平台上也至少占用 64 位的数据宽度。
   * 出错时返回一个负的返回值。如果这个函数指针是NULL，对seek的调用将会以某
   * 种不可预期的方式修改 file结构(在"file 结构"一节中有描述)中的位置计数器.
  */
  loff_t (*llseek) (struct file *, loff_t, int);
  /* 
   * 用来从设备中读取数据。该函数指针被赋为NULL值时，将导致read 系统调用出错
   * 并返回 -EINVAL("Invalid argument，非法参数")。函数返回非负值表示成功读
   * 取的字节数(返回值为"signed size"数据类型，通常就是目标平台上的固有整数
   * 类型)。
  */
  ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
  /* 
   * 向设备发送数据。如果没有这个函数，write系统调用会向程序返回一个-EINVAL。
   * 如果返回值非负，则表示成功写入的字节数。
  */
  ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
  /* 
   * 初始化一个异步的读取操作--- 即在函数返回之前可能不会完成的读取操作。如
   * 果该方法为 NULL，所有的操作将通过 read(同步)处理。
  */
  ssize_t (*aio_read) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
  /* 
   * 初始化设备上的异步写入操作。
  */
  ssize_t (*aio_write) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
  /* 
   * 对于设备文件来说，这个字段应该为NULL。它仅用干读取目录，只对文件系统有用。
  */
  int (*readdir) (struct file *, void *, filldir_t);
  /* 
   * poll方法是 poll、epoll和 select 这三个系统调用的后端实现。这三个系统调用可用
   * 来查询某个或多个文件描述符上的读取或写入是否会被阻塞。poll方法应该返回一
   * 个位掩码，用来指出非阻塞的读取或写入是否可能，并且也会向内核提供将调用进
   * 程置于休眠状态直到 I/O 变为可能时的信息。如果驱动程序将 poll 方法定义为
   * NULL，则设备会被认为既可读也可写，并且不会被阻塞。
  */
  unsigned int (*poll) (struct file *, struct poll_table_struct *);
  /* 
   * 系统调用ioctl提供了一种执行设备特定命令的方法(如格式化软盘的某个磁道，这
   * 既不是读操作也不是写操作)。另外，内核还能识别一部分ioctl命令，而不必调用
   * fops表中的ioctl。如果设备不提供ioctl入口点，则对于任何内核未预先定义的请
   * 求，ioctl系统调用将返回错误(-ENOTTY，"No such ioctl for device，该设备无
   * 此 ioctl 命令")。
  */
  int (*ioctl) (struct inode *, struct file *, unsigned int, unsigned long);
  /* 
   * 
  */
  long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
  /* 
   * 
  */
  long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
  /* 
   * mmap用于请求将设备内存映射到进程地址空间。如果设备没有实现这个方法，那
   * 么mmap系统调用将返回 -ENODEV。
  */
  int (*mmap) (struct file *, struct vm_area_struct *);
  /* 
   * 尽管这始终是对设备文件执行的第一个操作，然而却并不要求驱动程序一定要声明
   * 一个相应的方法。如果这个入口为NULL，设备的打开操作永远成功，但系统不会
   * 通知驱动程序。
  */
  int (*open) (struct inode *, struct file *);
  /* 
   * 对 flush 操作的调用发生在进程关闭设备文件描述符副本的时候，它应该执行(并
   * 等待)设备上尚未完结的操作。请不要将它同用户程序使用的 fsync 操作相混淆。
   * 目前，flush 仅仅用于少数几个驱动程序，比如，SCSI 磁带驱动程序用它来确保设
   * 备被关闭之前所有的数据都被写入到磁带中。如果 flush 被置为 NULL，内核将简单
   * 地忽略用户应用程序的请求。
  */
  int (*flush) (struct file *, fl_owner_t id);
  /* 
   * 当 file 结构被释放时，将调用这个操作。与 open相仿，也可以将 release 设置为
   * NULL(注 5)。
   *  
   * 注 5: 注意，release 并不是在进程每次调用 close 时都会被调用。只要 file 结构被共享(如
   * 在fork 或dup调用之后)，release 就会等到所有的副本都关闭之后才会得到调用。如果
   * 需要在关闭任意一个副本时刷新那些特处理的数据，则应实现flush 方法。
  */
  int (*release) (struct inode *, struct file *);
  /* 
   * 该方法是fsync 系统调用的后端实现，用户调用它来刷新待处理的数据。如果驱动
   * 程序没有实现这一方法，fsync 系统调用返回 -EINVAL。
  */
  int (*fsync) (struct file *, struct dentry *, int datasync);
  /* 
   * 这是 fsync 方法的异步版本。
  */
  int (*aio_fsync) (struct kiocb *, int datasync);
  /* 
   * 这个操作用来通知设备其FASYNC 标志发生了变化。异步通知是比较高级的话题，
   * 将在第六章介绍。如果设备不支持异步通知，该字段可以是 NULL。
  */
  int (*fasync) (int, struct file *, int);
  /* 
   * lock方法用于实现文件锁定，锁定是常规文件不可缺少的特性、但设备驱动程序几
   * 乎从来不会实现这个方法。
  */
  int (*lock) (struct file *, int, struct file_lock *);
  /* 
   * sendpage是sendfile系统调用的另外一半，它由内核调用以将数据发送到对应的文
   * 件，每次一个数据页。设备驱动程序通常也不需要实现 sendpage。
  */
  ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int);
  /* 
   * 该方法的目的是在进程的地址空间中找到一个合适的位置，以便将底层设备中的内
   * 存段映射到该位置。该任务通常由内存管理代码完成，但该方法的存在可允许驱动
   * 程序强制满足特定设备需要的任何对齐需求。大部分驱动程序可设置该方法为 NULL。
  */
  unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long);
  /* 
   * 该方法允许模块检查传递给 fcntl(F_SETFL...)调用的标志。
  */
  int (*check_flags)(int);
  /* 
   * 
  */
  int (*flock) (struct file *, int, struct file_lock *);
  /* 
   * 
  */
  ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *, size_t, unsigned int);
  /* 
   * 
  */
  ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, size_t, unsigned int);
  /* 
   * 
  */
  int (*setlease)(struct file *, long, struct file_lock **);
};

  /* 
   * 这些方法用来实现分散/聚集型的读写操作。应用程序有时需要进行涉及多个内存
   * 区域的单次读或写操作，利用上面这些系统调用可完成这类工作，而不必强加额外
   * 的数据拷贝操作。如果这些函数指针被设置为 NULL，就会调用 read 和 write 方法
   * (可能是多次)。
  */
  ssize_t (*readv) (struct file *, const struct iovec *, unsigned long, loff_t *);
  ssize_t (*writev) (struct file *,const struct iovec *, unsigned lang, loff_t *);
  /* 
   * 这个方法实现 sendfile 系统调用的读取部分。sendfile 系统调用以最小的复制操作
   * 将数据从一个文件描述符移动到另一个。例如，Web服务器可以利用这个方法将某
   * 个文件的内容发送到网络连接。设备驱动程序通常将 sendfile 设置为 NULL。
  */
  ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t, void *);
  /* 
   * 当应用程序使用fcntl来请求目录改变通知时，该方法将被调用。该方法仅对文件
   * 系统有用、驱动程序不必实现 dir_notify。
  */
  int (*dir_notify)(struct file *, unsigned long);

  /*
   * 文件对应的目录项（dentry）结构。除了用filp->f_dentry->d_inode的方式来
   * 访问索引节点结构之外，设备驱动程序的开发者们一般无需关心 dentry 结构。
   * 实际的结构里还有其他一些字段，但它们对于设备驱动程序并没有多大用处。由于驱动
   * 程序从不自己填写file 结构、而只是对别处创建的 file 结构进行访问、所以忽略这
   * 些字段是安全的。
  */
  struct dentry *f_dentry:

struct inode {
  // ...
  
  /* 对表示设备文件的 inode 结构，该字段包含了真正的设备编号。 */
  dev_t     i_rdev;
  union {
    struct pipe_inode_info  *i_pipe;
    struct block_device *i_bdev;
    /*
     * struct cdev 是表示字符设备的内核的内部结构。当 inode 指向一个字符设备文
     * 件时，该字段包含了指向 struct cdev 结构的指针。
    */
    struct cdev   *i_cdev;
  };  
  
  // ...  
}

  unsigned int iminor(struct inode *inode);
  unsigned int imajor(struct inode *inode);

// include/linux/cdev.h
struct cdev {
  struct kobject kobj;
  struct module *owner;
  const struct file_operations *ops;
  struct list_head list;
  dev_t dev;
  unsigned int count;
};

  struct cdev *my_cdev = cdev_alloc();
  my_cdev->ops = &my_fops;

// fs/char_dev.c
void cdev_init(struct cdev *cdev, const struct file_operations *fops)
{
  memset(cdev, 0, sizeof *cdev);
  INIT_LIST_HEAD(&cdev->list);
  kobject_init(&cdev->kobj, &ktype_cdev_default);
  cdev->ops = fops;
}

int cdev_add(struct cdev *p, dev_t dev, unsigned count)
{
  p->dev = dev;
  p->count = count;
  return kobj_map(cdev_map, dev, count, NULL, exact_match, exact_lock, p);
}

void cdev_del(struct cdev *p)
{
  cdev_unmap(p->dev, p->count);
  kobject_put(&p->kobj);
}

/* 定义信号量及其操作的包含文件。 */
#include <asm/semaphore.h>

/* 用于声明和初始化用在互斥模式中的信号量的两个宏。 */
DECLARE_MUTEX (name);
DECLARE_MUTEX_LOCKED(name);

/* 这两个函数可在运行时初始化信号量。 */
void init_MUTEX(struct semaphore *sem);
void init_MUTEX_LOCKED(struct semaphore *sem);

/*
 * 锁定和解锁信号量。如果必要，down 会将调用进程置于不可中断的休眠状态;相
 * 反，down_interruptible 可被信号中断。down_trylock 不会休眠，并且会在信号量
 * 不可用时立即返回锁定信号量的代码最后必须使用 up 解锁该信号量。
*/
void down(struct semaphore *sem);
int down_interruptible(struct semaphore *sem);
int down_trylock(struct semaphore *sem);
void up(struct semaphore *sem);

/* 信号量的读取者 / 写入者版本以及用来初始化这种信号量的函数。 */
struct rw_semaphore;
init_rwsem(struct rw_semaphore *sem);

/* 获取并释放对读取者 / 写入者信号量的读取访问的函数。 */
void down_read(struct rw_semaphore *sem);
int down_read_trylock(struct rw_semaphore *sem);
void up_read(struct rw_semaphore *sem);

/* 对读取者 / 写入者信号量的写入访问进行管理的函数。 */
void down_write(struct rw_semaphore *sem)
int down_write_trylock(struct rw_semaphore *sem)
void up_write(struct rw_semaphore *sem)
void downgrade_write(struct rw_semaphore *sem)



/*
 * 描述 Linux 的 completion 机制的包含文件，以及用于初始化 completion 的常用方
 * 法。INIT_COMPLETION 只能用于对已使用过的 completion 的重新初始化。
*/
#include <linux/completion.h>
DECLARE_COMPLETION(name);
init_completion(struct completion *c);
INIT_COMPLETION(struct completion c);

/* 等待一个 completion 事件的发生。 */
void wait_for_completion(struct completion *c);

/*
 * 发出completion事件信号。complete最多只能唤醒一个等待的线程，而complete_all
 * 会唤醒所有的等待者。
*/
void complete(struct completion *c);
void complete_all(struct completion *c);

/* 通过调用 complete 并调用当前线程的 exit 函数而发出 completion 事件信号。 */
void complete_and_exit(struct completion *c, long retval);


/* 定义自旋锁接口的包含文件，以及初始化自旋锁的两种方式。 */
#include <linux/spinlock.h>
spinlock_t lock = SPIN_LOCK_UNLOCKED;
spin_lock_init(spinlock_t *lock);

/* 锁定自旋锁的不同方式，某些方法会禁止中断。 */
void spin_lock(spinlock_t *lock);
void spin_lock_irqsave(spinlock_t *lock, unsigned long flags);
void spin_lock_irq(spinlock_t *lock);
void spin_lock_bh(spinlock_t *lock);

/* 上述函数的非自旋版本。这些函数在无法获得自旋锁时返回零，否则返回非零。 */
int spin_trylock(spinlock_t *lock);
int spin_trylock_bh(spinlock_t *lock);

/* 释放自旋锁的相应途径。 */
void spin_unlock(spinlock_t *lock);
void spin_unlock_irqrestore(spinlock_t *lock, unsigned long flags);
void spin_unlock_irq(spinlock_t *lock);
void spin_unlock_bh(spinlock_t *lock);

/* 初始化读取者 / 写入者锁的两种方式。 */
rwlock_t lock = RW_LOCK_UNLOCKED
rwlock_init(rwlock_t *lock);

/* 获取对读取者 / 写入者锁的读取访问的函数。 */
void read_lock(rwlock_t *lock);
void read_lock_irqsave(rwlock_t *lock, unsigned long flags);
void read_lock_irq(rwlock_t *lock);
void read_lock_bh(rwlock_t *lock);

/* 释放对读取者 / 写入者自旋锁的读取访问的函数。 */
void read_unlock(rwlock_t *lock);
void read_unlock_irqrestore(rwlock_t *lock, unsigned long flags);
void read_unlock_irq(rwlock_t *lock);
void read_unlock_bh(rwlock_t *lock);

/* 获取对读取者 / 写入者自旋锁的写入访问的函数。 */
void write_lock(rwlock_t *lock);
void write_lock_irqsave(rwlock_t *lock, unsigned long flags);
void write_lock_irq(rwlock_t *lock);
void write_lock_bh(rwlock_t *lock);

/* 释放对读取者 / 写入者自旋锁的写入访问的函数。 */
void write_unlock(rwlock_t *lock);
void write_unlock_irqrestore(rwlock_t *lock, unsigned long flags);
void write_unlock_irq(rwlock_t *lock);
void write_unlock_bh(rwlock_t *lock);


/* 整数变量的原子访问。对 atomic_t 变量的访问必须仅通过上述函数 */
#include <asm/atomic.h>
atomic_t v = ATOMIC_INIT(value);
void atomic_set(atomic_t *v, int i);
int atomic_read(atomic_t *v);
void atomic_add(int i, atomic_t *v);
void atomic_sub(int i, atomic_t *v);
void atomic_inc(atomic_t *v);
void atomic_dec(atomic_t *v);
int atomic_inc_and_test(atomic_t *v);
int atomic_dec_and_test(atomic_t *v);
int atomic_sub_and_test(int i, atomic_t *v);
int atomic_add_negative(int i, atomic_t *v);
int atomic_add_return(int i, atomic_t *v);
int atomic_sub_return(int i, atomic_t *v);
int atomic_inc_return(atomic_t *v);
int atomic_dec_return(atomic_t *v);


/*
 * 对位置的原子访问，它们可用于标志或锁变量。使用这些函数可避免因为对相应位 
 * 的并发访问而导致的任何竞态
 */
#include <asm/bitops.h>
void set_bit(nr, void *addr);
void clear_bit(nr, void *addr);
void change_bit(nr, void *addr);
test_bit(nr, void *addr);
int test_and_set_bit(nr, void *addr);
int test_and_clear_bit(nr, void *addr);
int test_and_change_bit(nr, void *addr);



/* 定义 seqlock 的包含文件，以及初始化 seqlock 的两种方式 */
#include <linux/seqlock.h>
seqlock_t lock = SEQLOCK_UNLOCKED;
seqlock_init(seqlock_t *lock);

/* 用于获取受 seqlock 保护的资源的读取访问的函数。 */
unsigned int read_seqbegin(seqLock_t *lock);
unsigned int read_seqbegin_irqsave(seqlock_t *lock, unsigned long flags);
int read_seqretry(seqlock_t *lock, unsigned int seq);
int read_seqretry_irqrestore(seqlock_t *lock, unsigned int seq, 
               unsigned long flags);

/* 用于获取受 seqlock 保护资源的写入访问的函数。 */
void write_seqlock(seqlock_t *lock);
void write_seqlock_irqsave(seqlock_t *lock, unsigned long flags);
void write_seqlock_irq(seqlock_t *lock);
void write_seqlock_bh(seqlock_t *lock);
int write_tryseqlock(seqlock_t *lock);

/* 用于释放受 seqlock 保护的资源的写入访问的函数。 */
void write_sequnlock(seqlock_t *lock);
void write_sequnlock_irqrestore(seqlock_t *lock, unsigmed long flags);
void write_sequnlock_irq(seqlock_t *lock);
void write_sequnlock_bh(seqlock_t *lock);

/* 使用读取 - 复制 - 更新(RCU)机制时需要的包含文件。 */
#include <linux/rcupdate.h>

/* 获取对受 RCU 保护的资源的读取访问的宏。 */
void rcu_read_lock;
void rcu_read_unlock;

/* 准备用于安全释放受RCU 保护的资源的回调函数，该函数将在所有的处理器被调度运行。 */
void call_rcu(struct rcu_head *head, void (*func) (void *arg), void *arg);