CHAPTER 6 Advanced Char Driver

Quick Reference
This chapter introduced the following symbols and header files:
#include
    Declares all the macros used to define ioctl commands. It is currently included
    by
_IOC_NRBITS
_IOC_TYPEBITS
_IOC_SIZEBITS
_IOC_DIRBITS
    The number of bits available for the different bitfields of ioctl commands. There
    are also four macros that specify the MASKs and four that specify the SHIFTs, but
    they’re mainly for internal use. _IOC_SIZEBITS is an important value to check,
    because it changes across architectures.
_IOC_NONE
_IOC_READ
_IOC_WRITE
    The possible values for the “direction” bitfield. “Read” and “write” are different
    bits and can be ORed to specify read/write. The values are 0-based.
_IOC(dir,type,nr,size)
_IO(type,nr)
_IOR(type,nr,size)
_IOW(type,nr,size)
_IOWR(type,nr,size)
    Macros used to create an ioctl command.
_IOC_DIR(nr)
_IOC_TYPE(nr)
_IOC_NR(nr)
_IOC_SIZE(nr)
    Macros used to decode a command. In particular, _IOC_TYPE(nr) is an OR com-
    bination of _IOC_READ and _IOC_WRITE.
#include
int access_ok(int type, const void *addr, unsigned long size);
    Checks that a pointer to user space is actually usable. access_ok returns a non-
    zero value if the access should be allowed.
VERIFY_READ
VERIFY_WRITE
    The possible values for the type argument in access_ok. VERIFY_WRITE is a super-
    set of VERIFY_READ.
#include
int put_user(datum,ptr);
int get_user(local,ptr);
int __put_user(datum,ptr);
int __get_user(local,ptr);
    Macros used to store or retrieve a datum to or from user space. The number of
    bytes being transferred depends on sizeof(*ptr). The regular versions call
    access_ok first, while the qualified versions (__put_user and __get_user) assume
    that access_ok has already been called.
#include
    Defines the various CAP_ symbols describing the capabilities a user-space process
    may have.
int capable(int capability);
    Returns nonzero if the process has the given capability.
#include
typedef struct { /* ... */ } wait_queue_head_t;
void init_waitqueue_head(wait_queue_head_t *queue);
DECLARE_WAIT_QUEUE_HEAD(queue);
    The defined type for Linux wait queues. A wait_queue_head_t must be explicitly
    initialized with either init_waitqueue_head at runtime or DECLARE_WAIT_
    QUEUE_HEAD at compile time.
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);
    Cause the process to sleep on the given queue until the given condition evalu-
    ates to a true value.
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);
    Wake processes that are sleeping on the queue q. The _interruptible form wakes
    only interruptible processes. Normally, only one exclusive waiter is awakened,
    but that behavior can be changed with the _nr or _all forms. The _sync version
    does not reschedule the CPU before returning.
#include
set_current_state(int state);
    Sets the execution state of the current process. TASK_RUNNING means it is ready to
    run, while the sleep states are TASK_INTERRUPTIBLE and TASK_UNINTERRUPTIBLE.
void schedule(void);
    Selects a runnable process from the run queue. The chosen process can be
    current or a different one.
typedef struct { /* ... */ } wait_queue_t;
init_waitqueue_entry(wait_queue_t *entry, struct task_struct *task);
    The wait_queue_t type is used to place a process onto a wait queue.
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);
    Helper functions that can be used to code a manual sleep.
void sleep_on(wiat_queue_head_t *queue);
void interruptible_sleep_on(wiat_queue_head_t *queue);
    Obsolete and deprecated functions that unconditionally put the current process
    to sleep.
#include
void poll_wait(struct file *filp, wait_queue_head_t *q, poll_table *p)
    Places the current process into a wait queue without scheduling immediately. It
    is designed to be used by the poll method of device drivers.
int fasync_helper(struct inode *inode, struct file *filp, int mode, struct
  fasync_struct **fa);
    A “helper” for implementing the fasync device method. The mode argument is the
    same value that is passed to the method, while fa points to a device-specific
    fasync_struct *.
void kill_fasync(struct fasync_struct *fa, int sig, int band);
    If the driver supports asynchronous notification, this function can be used to
    send a signal to processes registered in fa.
int nonseekable_open(struct inode *inode, struct file *filp);
loff_t no_llseek(struct file *file, loff_t offset, int whence);
    nonseekable_open should be called in the open method of any device that does
    not support seeking. Such devices should also use no_llseek as their llseek
    method.