This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA For more details see the file COPYING in the source distribution of Linux. Kernel Hackers Manual November 2007 module_init 9 module_init driver initialization entry point module_init x x function to be run at kernel boot time or module insertion module_init will either be called during do_initcalls (if builtin) or at module insertion time (if a module). There can only be one per module. Kernel Hackers Manual November 2007 module_exit 9 module_exit driver exit entry point module_exit x x function to be run when driver is removed module_exit will wrap the driver clean-up code with cleanup_module when used with rmmod when the driver is a module. If the driver is statically compiled into the kernel, module_exit has no effect. There can only be one per module. Kernel Hackers Manual November 2007 atomic_read 9 atomic_read read atomic variable atomic_read v v pointer of type atomic_t Atomically reads the value of v. Kernel Hackers Manual November 2007 atomic_set 9 atomic_set set atomic variable atomic_set v i v pointer of type atomic_t i required value Atomically sets the value of v to i. Kernel Hackers Manual November 2007 atomic_add 9 atomic_add add integer to atomic variable void atomic_add int i atomic_t * v i integer value to add v pointer of type atomic_t Atomically adds i to v. Kernel Hackers Manual November 2007 atomic_sub 9 atomic_sub subtract the atomic variable void atomic_sub int i atomic_t * v i integer value to subtract v pointer of type atomic_t Atomically subtracts i from v. Kernel Hackers Manual November 2007 atomic_sub_and_test 9 atomic_sub_and_test subtract value from variable and test result int atomic_sub_and_test int i atomic_t * v i integer value to subtract v pointer of type atomic_t Atomically subtracts i from v and returns true if the result is zero, or false for all other cases. Kernel Hackers Manual November 2007 atomic_inc 9 atomic_inc increment atomic variable void atomic_inc atomic_t * v v pointer of type atomic_t Atomically increments v by 1. Kernel Hackers Manual November 2007 atomic_dec 9 atomic_dec decrement atomic variable void atomic_dec atomic_t * v v pointer of type atomic_t Atomically decrements v by 1. Kernel Hackers Manual November 2007 atomic_dec_and_test 9 atomic_dec_and_test decrement and test int atomic_dec_and_test atomic_t * v v pointer of type atomic_t Atomically decrements v by 1 and returns true if the result is 0, or false for all other cases. Kernel Hackers Manual November 2007 atomic_inc_and_test 9 atomic_inc_and_test increment and test int atomic_inc_and_test atomic_t * v v pointer of type atomic_t Atomically increments v by 1 and returns true if the result is zero, or false for all other cases. Kernel Hackers Manual November 2007 atomic_add_negative 9 atomic_add_negative add and test if negative int atomic_add_negative int i atomic_t * v i integer value to add v pointer of type atomic_t Atomically adds i to v and returns true if the result is negative, or false when result is greater than or equal to zero. Kernel Hackers Manual November 2007 atomic_add_return 9 atomic_add_return add and return int atomic_add_return int i atomic_t * v i integer value to add v pointer of type atomic_t Atomically adds i to v and returns i + v Kernel Hackers Manual November 2007 atomic_add_unless 9 atomic_add_unless add unless the number is a given value atomic_add_unless v a u v pointer of type atomic_t a the amount to add to v... u ...unless v is equal to u. Atomically adds a to v, so long as it was not u. Returns non-zero if v was not u, and zero otherwise. Kernel Hackers Manual November 2007 get_unaligned 9 get_unaligned get value from possibly mis-aligned location get_unaligned ptr ptr pointer to value This macro should be used for accessing values larger in size than single bytes at locations that are expected to be improperly aligned, e.g. retrieving a u16 value from a location not u16-aligned. Note that unaligned accesses can be very expensive on some architectures. Kernel Hackers Manual November 2007 put_unaligned 9 put_unaligned put value to a possibly mis-aligned location put_unaligned val ptr val value to place ptr pointer to location This macro should be used for placing values larger in size than single bytes at locations that are expected to be improperly aligned, e.g. writing a u16 value to a location not u16-aligned. Note that unaligned accesses can be very expensive on some architectures. Kernel Hackers Manual November 2007 pid_alive 9 pid_alive check that a task structure is not stale int pid_alive struct task_struct * p p Task structure to be checked. Test if a process is not yet dead (at most zombie state) If pid_alive fails, then pointers within the task structure can be stale and must not be dereferenced. Kernel Hackers Manual November 2007 __wake_up 9 __wake_up wake up threads blocked on a waitqueue. void fastcall __wake_up wait_queue_head_t * q unsigned int mode int nr_exclusive void * key q the waitqueue mode which threads nr_exclusive how many wake-one or wake-many threads to wake up key is directly passed to the wakeup function Kernel Hackers Manual November 2007 __wake_up_sync 9 __wake_up_sync wake up threads blocked on a waitqueue. void fastcall __wake_up_sync wait_queue_head_t * q unsigned int mode int nr_exclusive q the waitqueue mode which threads nr_exclusive how many wake-one or wake-many threads to wake up The sync wakeup differs that the waker knows that it will schedule away soon, so while the target thread will be woken up, it will not be migrated to another CPU - ie. the two threads are 'synchronized' with each other. This can prevent needless bouncing between CPUs. On UP it can prevent extra preemption. Kernel Hackers Manual November 2007 task_nice 9 task_nice return the nice value of a given task. int task_nice const task_t * p p the task in question. Kernel Hackers Manual November 2007 sched_setscheduler 9 sched_setscheduler change the scheduling policy and/or RT priority of int sched_setscheduler struct task_struct * p int policy struct sched_param * param p the task in question. policy new policy. param structure containing the new RT priority. a thread. Kernel Hackers Manual November 2007 yield 9 yield yield the current processor to other threads. void __sched yield void void no arguments this is a shortcut for kernel-space yielding - it marks the thread runnable and calls sys_sched_yield. Kernel Hackers Manual November 2007 schedule_timeout 9 schedule_timeout sleep until timeout signed long __sched schedule_timeout signed long timeout timeout timeout value in jiffies Make the current task sleep until timeout jiffies have elapsed. The routine will return immediately unless the current task state has been set (see set_current_state). You can set the task state as follows - TASK_UNINTERRUPTIBLE - at least timeout jiffies are guaranteed to pass before the routine returns. The routine will return 0 TASK_INTERRUPTIBLE - the routine may return early if a signal is delivered to the current task. In this case the remaining time in jiffies will be returned, or 0 if the timer expired in time The current task state is guaranteed to be TASK_RUNNING when this routine returns. Specifying a timeout value of MAX_SCHEDULE_TIMEOUT will schedule the CPU away without a bound on the timeout. In this case the return value will be MAX_SCHEDULE_TIMEOUT. In all cases the return value is guaranteed to be non-negative. Kernel Hackers Manual November 2007 msleep 9 msleep sleep safely even with waitqueue interruptions void msleep unsigned int msecs msecs Time in milliseconds to sleep for Kernel Hackers Manual November 2007 msleep_interruptible 9 msleep_interruptible sleep waiting for signals unsigned long msleep_interruptible unsigned int msecs msecs Time in milliseconds to sleep for Kernel Hackers Manual November 2007 ktime_set 9 ktime_set Set a ktime_t variable from a seconds/nanoseconds value ktime_t ktime_set const long secs const unsigned long nsecs secs seconds to set nsecs nanoseconds to set Return the ktime_t representation of the value Return the ktime_t representation of the value Kernel Hackers Manual November 2007 ktime_sub 9 ktime_sub subtract two ktime_t variables ktime_t ktime_sub const ktime_t lhs const ktime_t rhs lhs minuend rhs subtrahend Returns the remainder of the substraction Returns the remainder of the substraction Kernel Hackers Manual November 2007 ktime_add 9 ktime_add add two ktime_t variables ktime_t ktime_add const ktime_t add1 const ktime_t add2 add1 addend1 add2 addend2 Returns the sum of addend1 and addend2 Returns the sum of addend1 and addend2 Kernel Hackers Manual November 2007 ktime_add_ns 9 ktime_add_ns Add a scalar nanoseconds value to a ktime_t variable ktime_t ktime_add_ns const ktime_t kt u64 nsec kt addend nsec the scalar nsec value to add Returns the sum of kt and nsec in ktime_t format Returns the sum of kt and nsec in ktime_t format Kernel Hackers Manual November 2007 timespec_to_ktime 9 timespec_to_ktime convert a timespec to ktime_t format ktime_t timespec_to_ktime const struct timespec ts ts the timespec variable to convert Returns a ktime_t variable with the converted timespec value Returns a ktime_t variable with the converted timespec value Kernel Hackers Manual November 2007 timeval_to_ktime 9 timeval_to_ktime convert a timeval to ktime_t format ktime_t timeval_to_ktime const struct timeval tv tv the timeval variable to convert Returns a ktime_t variable with the converted timeval value Returns a ktime_t variable with the converted timeval value Kernel Hackers Manual November 2007 ktime_to_timespec 9 ktime_to_timespec convert a ktime_t variable to timespec format struct timespec ktime_to_timespec const ktime_t kt kt the ktime_t variable to convert Returns the timespec representation of the ktime value Returns the timespec representation of the ktime value Kernel Hackers Manual November 2007 ktime_to_timeval 9 ktime_to_timeval convert a ktime_t variable to timeval format struct timeval ktime_to_timeval const ktime_t kt kt the ktime_t variable to convert Returns the timeval representation of the ktime value Returns the timeval representation of the ktime value Kernel Hackers Manual November 2007 ktime_to_ns 9 ktime_to_ns convert a ktime_t variable to scalar nanoseconds u64 ktime_to_ns const ktime_t kt kt the ktime_t variable to convert Returns the scalar nanoseconds representation of kt Kernel Hackers Manual November 2007 struct hrtimer 9 struct hrtimer the basic hrtimer structure struct hrtimer { struct rb_node node; ktime_t expires; int (* function) (struct hrtimer *); struct hrtimer_base * base; }; node red black tree node for time ordered insertion expires the absolute expiry time in the hrtimers internal representation. The time is related to the clock on which the timer is based. function timer expiry callback function base pointer to the timer base (per cpu and per clock) The hrtimer structure must be initialized by init_hrtimer_#CLOCKTYPE The hrtimer structure must be initialized by init_hrtimer_#CLOCKTYPE Kernel Hackers Manual November 2007 struct hrtimer_sleeper 9 struct hrtimer_sleeper simple sleeper structure struct hrtimer_sleeper { struct hrtimer timer; struct task_struct * task; }; timer embedded timer structure task task to wake up task is set to NULL, when the timer expires. task is set to NULL, when the timer expires. Kernel Hackers Manual November 2007 struct hrtimer_base 9 struct hrtimer_base the timer base for a specific clock struct hrtimer_base { clockid_t index; spinlock_t lock; struct rb_root active; struct rb_node * first; ktime_t resolution; ktime_t (* get_time) (void); ktime_t (* get_softirq_time) (void); struct hrtimer * curr_timer; ktime_t softirq_time; }; index clock type index for per_cpu support when moving a timer to a base on another cpu. lock lock protecting the base and associated timers active red black tree root node for the active timers first pointer to the timer node which expires first resolution the resolution of the clock, in nanoseconds get_time function to retrieve the current time of the clock get_softirq_time function to retrieve the current time from the softirq curr_timer the timer which is executing a callback right now softirq_time the time when running the hrtimer queue in the softirq Kernel Hackers Manual November 2007 ktime_get_real 9 ktime_get_real get the real (wall-) time in ktime_t format ktime_t ktime_get_real void void no arguments returns the time in ktime_t format Kernel Hackers Manual November 2007 ktime_get_ts 9 ktime_get_ts get the monotonic clock in timespec format void ktime_get_ts struct timespec * ts ts pointer to timespec variable The function calculates the monotonic clock from the realtime clock and the wall_to_monotonic offset and stores the result in normalized timespec format in the variable pointed to by ts. The function calculates the monotonic clock from the realtime clock and the wall_to_monotonic offset and stores the result in normalized timespec format in the variable pointed to by ts. Kernel Hackers Manual November 2007 reparent_to_init 9 reparent_to_init Reparent the calling kernel thread to the init task. void reparent_to_init void void no arguments If a kernel thread is launched as a result of a system call, or if it ever exits, it should generally reparent itself to init so that it is correctly cleaned up on exit. The various task state such as scheduling policy and priority may have been inherited from a user process, so we reset them to sane values here. NOTE that reparent_to_init gives the caller full capabilities. Kernel Hackers Manual November 2007 sys_tgkill 9 sys_tgkill send signal to one specific thread long sys_tgkill int tgid int pid int sig tgid the thread group ID of the thread pid the PID of the thread sig signal to be sent This syscall also checks the tgid and returns -ESRCH even if the PID exists but it's not belonging to the target process anymore. This method solves the problem of threads exiting and PIDs getting reused. Kernel Hackers Manual November 2007 kobject_init 9 kobject_init initialize object. void kobject_init struct kobject * kobj kobj object in question. Kernel Hackers Manual November 2007 kobject_add 9 kobject_add add an object to the hierarchy. int kobject_add struct kobject * kobj kobj object. Kernel Hackers Manual November 2007 kobject_register 9 kobject_register initialize and add an object. int kobject_register struct kobject * kobj kobj object in question. Kernel Hackers Manual November 2007 kobject_set_name 9 kobject_set_name Set the name of an object int kobject_set_name struct kobject * kobj const char * fmt ... kobj object. fmt format string used to build the name ... variable arguments If strlen(name) >= KOBJ_NAME_LEN, then use a dynamically allocated string that kobj->k_name points to. Otherwise, use the static kobj->name array. Kernel Hackers Manual November 2007 kobject_del 9 kobject_del unlink kobject from hierarchy. void kobject_del struct kobject * kobj kobj object. Kernel Hackers Manual November 2007 kobject_unregister 9 kobject_unregister remove object from hierarchy and decrement refcount. void kobject_unregister struct kobject * kobj kobj object going away. Kernel Hackers Manual November 2007 kobject_get 9 kobject_get increment refcount for object. struct kobject * kobject_get struct kobject * kobj kobj object. Kernel Hackers Manual November 2007 kobject_put 9 kobject_put decrement refcount for object. void kobject_put struct kobject * kobj kobj object. Decrement the refcount, and if 0, call kobject_cleanup. Kernel Hackers Manual November 2007 kset_register 9 kset_register initialize and add a kset. int kset_register struct kset * k k kset. Kernel Hackers Manual November 2007 kset_unregister 9 kset_unregister remove a kset. void kset_unregister struct kset * k k kset. Kernel Hackers Manual November 2007 subsystem_register 9 subsystem_register register a subsystem. int subsystem_register struct subsystem * s s the subsystem we're registering. Once we register the subsystem, we want to make sure that the kset points back to this subsystem for correct usage of the rwsem. Kernel Hackers Manual November 2007 subsys_create_file 9 subsys_create_file export sysfs attribute file. int subsys_create_file struct subsystem * s struct subsys_attribute * a s subsystem. a subsystem attribute descriptor. Kernel Hackers Manual November 2007 container_of 9 container_of cast a member of a structure out to the containing structure container_of ptr type member ptr the pointer to the member. type the type of the container struct this is embedded in. member the name of the member within the struct. Kernel Hackers Manual November 2007 printk 9 printk print a kernel message int printk const char * fmt ... fmt format string ... variable arguments This is printk. It can be called from any context. We want it to work. We try to grab the console_sem. If we succeed, it's easy - we log the output and call the console drivers. If we fail to get the semaphore we place the output into the log buffer and return. The current holder of the console_sem will notice the new output in release_console_sem and will send it to the consoles before releasing the semaphore. One effect of this deferred printing is that code which calls printk and then changes console_loglevel may break. This is because console_loglevel is inspected when the actual printing occurs. printf(3) Kernel Hackers Manual November 2007 acquire_console_sem 9 acquire_console_sem lock the console system for exclusive use. void acquire_console_sem void void no arguments Acquires a semaphore which guarantees that the caller has exclusive access to the console system and the console_drivers list. Can sleep, returns nothing. Kernel Hackers Manual November 2007 release_console_sem 9 release_console_sem unlock the console system void release_console_sem void void no arguments Releases the semaphore which the caller holds on the console system and the console driver list. While the semaphore was held, console output may have been buffered by printk. If this is the case, release_console_sem emits the output prior to releasing the semaphore. If there is output waiting for klogd, we wake it up. release_console_sem may be called from any context. Kernel Hackers Manual November 2007 console_conditional_schedule 9 console_conditional_schedule yield the CPU if required void __sched console_conditional_schedule void void no arguments If the console code is currently allowed to sleep, and if this CPU should yield the CPU to another task, do so here. Must be called within acquire_console_sem. Kernel Hackers Manual November 2007 panic 9 panic halt the system NORET_TYPE void panic const char * fmt ... fmt The text string to print ... variable arguments Display a message, then perform cleanups. This function never returns. Kernel Hackers Manual November 2007 atomic_notifier_chain_register 9 atomic_notifier_chain_register Add notifier to an atomic notifier chain int atomic_notifier_chain_register struct atomic_notifier_head * nh struct notifier_block * n nh Pointer to head of the atomic notifier chain n New entry in notifier chain Adds a notifier to an atomic notifier chain. Currently always returns zero. Kernel Hackers Manual November 2007 atomic_notifier_chain_unregister 9 atomic_notifier_chain_unregister Remove notifier from an atomic notifier chain int atomic_notifier_chain_unregister struct atomic_notifier_head * nh struct notifier_block * n nh Pointer to head of the atomic notifier chain n Entry to remove from notifier chain Removes a notifier from an atomic notifier chain. Returns zero on success or -ENOENT on failure. Kernel Hackers Manual November 2007 atomic_notifier_call_chain 9 atomic_notifier_call_chain Call functions in an atomic notifier chain int atomic_notifier_call_chain struct atomic_notifier_head * nh unsigned long val void * v nh Pointer to head of the atomic notifier chain val Value passed unmodified to notifier function v Pointer passed unmodified to notifier function Calls each function in a notifier chain in turn. The functions run in an atomic context, so they must not block. This routine uses RCU to synchronize with changes to the chain. If the return value of the notifier can be and'ed with NOTIFY_STOP_MASK then atomic_notifier_call_chain will return immediately, with the return value of the notifier function which halted execution. Otherwise the return value is the return value of the last notifier function called. Kernel Hackers Manual November 2007 blocking_notifier_chain_register 9 blocking_notifier_chain_register Add notifier to a blocking notifier chain int blocking_notifier_chain_register struct blocking_notifier_head * nh struct notifier_block * n nh Pointer to head of the blocking notifier chain n New entry in notifier chain Adds a notifier to a blocking notifier chain. Must be called in process context. Currently always returns zero. Kernel Hackers Manual November 2007 blocking_notifier_chain_unregister 9 blocking_notifier_chain_unregister Remove notifier from a blocking notifier chain int blocking_notifier_chain_unregister struct blocking_notifier_head * nh struct notifier_block * n nh Pointer to head of the blocking notifier chain n Entry to remove from notifier chain Removes a notifier from a blocking notifier chain. Must be called from process context. Returns zero on success or -ENOENT on failure. Kernel Hackers Manual November 2007 blocking_notifier_call_chain 9 blocking_notifier_call_chain Call functions in a blocking notifier chain int blocking_notifier_call_chain struct blocking_notifier_head * nh unsigned long val void * v nh Pointer to head of the blocking notifier chain val Value passed unmodified to notifier function v Pointer passed unmodified to notifier function Calls each function in a notifier chain in turn. The functions run in a process context, so they are allowed to block. If the return value of the notifier can be and'ed with NOTIFY_STOP_MASK then blocking_notifier_call_chain will return immediately, with the return value of the notifier function which halted execution. Otherwise the return value is the return value of the last notifier function called. Kernel Hackers Manual November 2007 raw_notifier_chain_register 9 raw_notifier_chain_register Add notifier to a raw notifier chain int raw_notifier_chain_register struct raw_notifier_head * nh struct notifier_block * n nh Pointer to head of the raw notifier chain n New entry in notifier chain Adds a notifier to a raw notifier chain. All locking must be provided by the caller. Currently always returns zero. Kernel Hackers Manual November 2007 raw_notifier_chain_unregister 9 raw_notifier_chain_unregister Remove notifier from a raw notifier chain int raw_notifier_chain_unregister struct raw_notifier_head * nh struct notifier_block * n nh Pointer to head of the raw notifier chain n Entry to remove from notifier chain Removes a notifier from a raw notifier chain. All locking must be provided by the caller. Returns zero on success or -ENOENT on failure. Kernel Hackers Manual November 2007 raw_notifier_call_chain 9 raw_notifier_call_chain Call functions in a raw notifier chain int raw_notifier_call_chain struct raw_notifier_head * nh unsigned long val void * v nh Pointer to head of the raw notifier chain val Value passed unmodified to notifier function v Pointer passed unmodified to notifier function Calls each function in a notifier chain in turn. The functions run in an undefined context. All locking must be provided by the caller. If the return value of the notifier can be and'ed with NOTIFY_STOP_MASK then raw_notifier_call_chain will return immediately, with the return value of the notifier function which halted execution. Otherwise the return value is the return value of the last notifier function called. Kernel Hackers Manual November 2007 register_reboot_notifier 9 register_reboot_notifier Register function to be called at reboot time int register_reboot_notifier struct notifier_block * nb nb Info about notifier function to be called Registers a function with the list of functions to be called at reboot time. Currently always returns zero, as blocking_notifier_chain_register always returns zero. Kernel Hackers Manual November 2007 unregister_reboot_notifier 9 unregister_reboot_notifier Unregister previously registered reboot notifier int unregister_reboot_notifier struct notifier_block * nb nb Hook to be unregistered Unregisters a previously registered reboot notifier function. Returns zero on success, or -ENOENT on failure. Kernel Hackers Manual November 2007 emergency_restart 9 emergency_restart reboot the system void emergency_restart void void no arguments Without shutting down any hardware or taking any locks reboot the system. This is called when we know we are in trouble so this is our best effort to reboot. This is safe to call in interrupt context. Kernel Hackers Manual November 2007 kernel_restart 9 kernel_restart reboot the system void kernel_restart char * cmd cmd pointer to buffer containing command to execute for restart or NULL Shutdown everything and perform a clean reboot. This is not safe to call in interrupt context. Kernel Hackers Manual November 2007 kernel_kexec 9 kernel_kexec reboot the system void kernel_kexec void void no arguments Move into place and start executing a preloaded standalone executable. If nothing was preloaded return an error. Kernel Hackers Manual November 2007 kernel_halt 9 kernel_halt halt the system void kernel_halt void void no arguments Shutdown everything and perform a clean system halt. Kernel Hackers Manual November 2007 kernel_power_off 9 kernel_power_off power_off the system void kernel_power_off void void no arguments Shutdown everything and perform a clean system power_off. Kernel Hackers Manual November 2007 call_rcu 9 call_rcu Queue an RCU callback for invocation after a grace period. void fastcall call_rcu struct rcu_head * head void (*func) struct rcu_head *rcu head structure to be used for queueing the RCU updates. func actual update function to be invoked after the grace period The update function will be invoked some time after a full grace period elapses, in other words after all currently executing RCU read-side critical sections have completed. RCU read-side critical sections are delimited by rcu_read_lock and rcu_read_unlock, and may be nested. Kernel Hackers Manual November 2007 call_rcu_bh 9 call_rcu_bh Queue an RCU for invocation after a quicker grace period. void fastcall call_rcu_bh struct rcu_head * head void (*func) struct rcu_head *rcu head structure to be used for queueing the RCU updates. func actual update function to be invoked after the grace period The update function will be invoked some time after a full grace period elapses, in other words after all currently executing RCU read-side critical sections have completed. call_rcu_bh assumes that the read-side critical sections end on completion of a softirq handler. This means that read-side critical sections in process context must not be interrupted by softirqs. This interface is to be used when most of the read-side critical sections are in softirq context. RCU read-side critical sections are delimited by rcu_read_lock and rcu_read_unlock, * if in interrupt context or rcu_read_lock_bh and rcu_read_unlock_bh, if in process context. These may be nested. Kernel Hackers Manual November 2007 rcu_barrier 9 rcu_barrier Wait until all the in-flight RCUs are complete. void rcu_barrier void void no arguments Kernel Hackers Manual November 2007 synchronize_rcu 9 synchronize_rcu wait until a grace period has elapsed. void synchronize_rcu void void no arguments Control will return to the caller some time after a full grace period has elapsed, in other words after all currently executing RCU read-side critical sections have completed. RCU read-side critical sections are delimited by rcu_read_lock and rcu_read_unlock, and may be nested. If your read-side code is not protected by rcu_read_lock, do -not- use synchronize_rcu. Kernel Hackers Manual November 2007 list_add 9 list_add add a new entry void list_add struct list_head * new struct list_head * head new new entry to be added head list head to add it after Insert a new entry after the specified head. This is good for implementing stacks. Kernel Hackers Manual November 2007 list_add_tail 9 list_add_tail add a new entry void list_add_tail struct list_head * new struct list_head * head new new entry to be added head list head to add it before Insert a new entry before the specified head. This is useful for implementing queues. Kernel Hackers Manual November 2007 list_add_rcu 9 list_add_rcu add a new entry to rcu-protected list void list_add_rcu struct list_head * new struct list_head * head new new entry to be added head list head to add it after Insert a new entry after the specified head. This is good for implementing stacks. The caller must take whatever precautions are necessary (such as holding appropriate locks) to avoid racing with another list-mutation primitive, such as list_add_rcu or list_del_rcu, running on this same list. However, it is perfectly legal to run concurrently with the _rcu list-traversal primitives, such as list_for_each_entry_rcu. Kernel Hackers Manual November 2007 list_add_tail_rcu 9 list_add_tail_rcu add a new entry to rcu-protected list void list_add_tail_rcu struct list_head * new struct list_head * head new new entry to be added head list head to add it before Insert a new entry before the specified head. This is useful for implementing queues. The caller must take whatever precautions are necessary (such as holding appropriate locks) to avoid racing with another list-mutation primitive, such as list_add_tail_rcu or list_del_rcu, running on this same list. However, it is perfectly legal to run concurrently with the _rcu list-traversal primitives, such as list_for_each_entry_rcu. Kernel Hackers Manual November 2007 list_del 9 list_del deletes entry from list. void list_del struct list_head * entry entry the element to delete from the list. list_empty on entry does not return true after this, the entry is in an undefined state. Kernel Hackers Manual November 2007 list_del_rcu 9 list_del_rcu deletes entry from list without re-initialization void list_del_rcu struct list_head * entry entry the element to delete from the list. list_empty on entry does not return true after this, the entry is in an undefined state. It is useful for RCU based lockfree traversal. In particular, it means that we can not poison the forward pointers that may still be used for walking the list. The caller must take whatever precautions are necessary (such as holding appropriate locks) to avoid racing with another list-mutation primitive, such as list_del_rcu or list_add_rcu, running on this same list. However, it is perfectly legal to run concurrently with the _rcu list-traversal primitives, such as list_for_each_entry_rcu. Note that the caller is not permitted to immediately free the newly deleted entry. Instead, either synchronize_rcu or call_rcu must be used to defer freeing until an RCU grace period has elapsed. Kernel Hackers Manual November 2007 list_del_init 9 list_del_init deletes entry from list and reinitialize it. void list_del_init struct list_head * entry entry the element to delete from the list. Kernel Hackers Manual November 2007 list_move 9 list_move delete from one list and add as another's head void list_move struct list_head * list struct list_head * head list the entry to move head the head that will precede our entry Kernel Hackers Manual November 2007 list_move_tail 9 list_move_tail delete from one list and add as another's tail void list_move_tail struct list_head * list struct list_head * head list the entry to move head the head that will follow our entry Kernel Hackers Manual November 2007 list_empty 9 list_empty tests whether a list is empty int list_empty const struct list_head * head head the list to test. Kernel Hackers Manual November 2007 list_empty_careful 9 list_empty_careful tests whether a list is int list_empty_careful const struct list_head * head head the list to test. empty _and_ checks that no other CPU might be in the process of still modifying either member using list_empty_careful without synchronization can only be safe if the only activity that can happen to the list entry is list_del_init. Eg. it cannot be used if another CPU could re-list_add it. Kernel Hackers Manual November 2007 list_splice 9 list_splice join two lists void list_splice struct list_head * list struct list_head * head list the new list to add. head the place to add it in the first list. Kernel Hackers Manual November 2007 list_splice_init 9 list_splice_init join two lists and reinitialise the emptied list. void list_splice_init struct list_head * list struct list_head * head list the new list to add. head the place to add it in the first list. The list at list is reinitialised Kernel Hackers Manual November 2007 list_entry 9 list_entry get the struct for this entry list_entry ptr type member ptr the &struct list_head pointer. type the type of the struct this is embedded in. member the name of the list_struct within the struct. Kernel Hackers Manual November 2007 list_for_each 9 list_for_each iterate over a list list_for_each pos head pos the &struct list_head to use as a loop counter. head the head for your list. Kernel Hackers Manual November 2007 __list_for_each 9 __list_for_each iterate over a list __list_for_each pos head pos the &struct list_head to use as a loop counter. head the head for your list. This variant differs from list_for_each in that it's the simplest possible list iteration code, no prefetching is done. Use this for code that knows the list to be very short (empty or 1 entry) most of the time. Kernel Hackers Manual November 2007 list_for_each_prev 9 list_for_each_prev iterate over a list backwards list_for_each_prev pos head pos the &struct list_head to use as a loop counter. head the head for your list. Kernel Hackers Manual November 2007 list_for_each_safe 9 list_for_each_safe iterate over a list safe against removal of list entry list_for_each_safe pos n head pos the &struct list_head to use as a loop counter. n another &struct list_head to use as temporary storage head the head for your list. Kernel Hackers Manual November 2007 list_for_each_entry 9 list_for_each_entry iterate over list of given type list_for_each_entry pos head member pos