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 October 2009 module_init 9 2.6.32-rc5 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 October 2009 module_exit 9 2.6.32-rc5 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 October 2009 atomic_read 9 2.6.32-rc5 atomic_read read atomic variable int atomic_read const atomic_t * v v pointer of type atomic_t Atomically reads the value of v. Kernel Hackers Manual October 2009 atomic_set 9 2.6.32-rc5 atomic_set set atomic variable void atomic_set atomic_t * v int i v pointer of type atomic_t i required value Atomically sets the value of v to i. Kernel Hackers Manual October 2009 atomic_add 9 2.6.32-rc5 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 October 2009 atomic_sub 9 2.6.32-rc5 atomic_sub subtract integer from 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 October 2009 atomic_sub_and_test 9 2.6.32-rc5 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 October 2009 atomic_inc 9 2.6.32-rc5 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 October 2009 atomic_dec 9 2.6.32-rc5 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 October 2009 atomic_dec_and_test 9 2.6.32-rc5 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 October 2009 atomic_inc_and_test 9 2.6.32-rc5 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 October 2009 atomic_add_negative 9 2.6.32-rc5 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 October 2009 atomic_add_return 9 2.6.32-rc5 atomic_add_return add integer 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 October 2009 atomic_sub_return 9 2.6.32-rc5 atomic_sub_return subtract integer and return int atomic_sub_return int i atomic_t * v i integer value to subtract v pointer of type atomic_t Atomically subtracts i from v and returns v - i Kernel Hackers Manual October 2009 atomic_add_unless 9 2.6.32-rc5 atomic_add_unless add unless the number is already a given value int atomic_add_unless atomic_t * v int a int 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 v was not already u. Returns non-zero if v was not u, and zero otherwise. Kernel Hackers Manual October 2009 atomic64_xchg 9 2.6.32-rc5 atomic64_xchg xchg atomic64 variable u64 atomic64_xchg atomic64_t * ptr u64 new_val ptr pointer to type atomic64_t new_val value to assign Atomically xchgs the value of ptr to new_val and returns the old value. Kernel Hackers Manual October 2009 atomic64_set 9 2.6.32-rc5 atomic64_set set atomic64 variable void atomic64_set atomic64_t * ptr u64 new_val ptr pointer to type atomic64_t new_val value to assign Atomically sets the value of ptr to new_val. Kernel Hackers Manual October 2009 atomic64_read 9 2.6.32-rc5 atomic64_read read atomic64 variable u64 atomic64_read atomic64_t * ptr ptr pointer to type atomic64_t Atomically reads the value of ptr and returns it. Kernel Hackers Manual October 2009 atomic64_add_return 9 2.6.32-rc5 atomic64_add_return add and return u64 atomic64_add_return u64 delta atomic64_t * ptr delta integer value to add ptr pointer to type atomic64_t Atomically adds delta to ptr and returns delta + *ptr Kernel Hackers Manual October 2009 atomic64_add 9 2.6.32-rc5 atomic64_add add integer to atomic64 variable void atomic64_add u64 delta atomic64_t * ptr delta integer value to add ptr pointer to type atomic64_t Atomically adds delta to ptr. Kernel Hackers Manual October 2009 atomic64_sub 9 2.6.32-rc5 atomic64_sub subtract the atomic64 variable void atomic64_sub u64 delta atomic64_t * ptr delta integer value to subtract ptr pointer to type atomic64_t Atomically subtracts delta from ptr. Kernel Hackers Manual October 2009 atomic64_sub_and_test 9 2.6.32-rc5 atomic64_sub_and_test subtract value from variable and test result int atomic64_sub_and_test u64 delta atomic64_t * ptr delta integer value to subtract ptr pointer to type atomic64_t Atomically subtracts delta from ptr and returns true if the result is zero, or false for all other cases. Kernel Hackers Manual October 2009 atomic64_inc 9 2.6.32-rc5 atomic64_inc increment atomic64 variable void atomic64_inc atomic64_t * ptr ptr pointer to type atomic64_t Atomically increments ptr by 1. Kernel Hackers Manual October 2009 atomic64_dec 9 2.6.32-rc5 atomic64_dec decrement atomic64 variable void atomic64_dec atomic64_t * ptr ptr pointer to type atomic64_t Atomically decrements ptr by 1. Kernel Hackers Manual October 2009 atomic64_dec_and_test 9 2.6.32-rc5 atomic64_dec_and_test decrement and test int atomic64_dec_and_test atomic64_t * ptr ptr pointer to type atomic64_t Atomically decrements ptr by 1 and returns true if the result is 0, or false for all other cases. Kernel Hackers Manual October 2009 atomic64_inc_and_test 9 2.6.32-rc5 atomic64_inc_and_test increment and test int atomic64_inc_and_test atomic64_t * ptr ptr pointer to type atomic64_t Atomically increments ptr by 1 and returns true if the result is zero, or false for all other cases. Kernel Hackers Manual October 2009 atomic64_add_negative 9 2.6.32-rc5 atomic64_add_negative add and test if negative int atomic64_add_negative u64 delta atomic64_t * ptr delta integer value to add ptr pointer to type atomic64_t Atomically adds delta to ptr and returns true if the result is negative, or false when result is greater than or equal to zero. /home/landley/linux/temp//arch/x86/include/asm/unaligned.h Document generation inconsistency The template for this document tried to insert the structured comment from the file /home/landley/linux/temp//arch/x86/include/asm/unaligned.h at this point, but none was found. This dummy section is inserted to allow generation to continue. Kernel Hackers Manual October 2009 struct task_cputime 9 2.6.32-rc5 struct task_cputime collected CPU time counts struct task_cputime { cputime_t utime; cputime_t stime; unsigned long long sum_exec_runtime; }; utime time spent in user mode, in cputime_t units stime time spent in kernel mode, in cputime_t units sum_exec_runtime total time spent on the CPU, in nanoseconds This structure groups together three kinds of CPU time that are tracked for threads and thread groups. Most things considering CPU time want to group these counts together and treat all three of them in parallel. Kernel Hackers Manual October 2009 struct thread_group_cputimer 9 2.6.32-rc5 struct thread_group_cputimer thread group interval timer counts struct thread_group_cputimer { struct task_cputime cputime; int running; spinlock_t lock; }; cputime thread group interval timers. running non-zero when there are timers running and cputime receives updates. lock lock for fields in this struct. This structure contains the version of task_cputime, above, that is used for thread group CPU timer calculations. Kernel Hackers Manual October 2009 pid_alive 9 2.6.32-rc5 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 October 2009 is_global_init 9 2.6.32-rc5 is_global_init check if a task structure is init int is_global_init struct task_struct * tsk tsk Task structure to be checked. Check if a task structure is the first user space task the kernel created. Kernel Hackers Manual October 2009 wake_up_process 9 2.6.32-rc5 wake_up_process Wake up a specific process int wake_up_process struct task_struct * p p The process to be woken up. Attempt to wake up the nominated process and move it to the set of runnable processes. Returns 1 if the process was woken up, 0 if it was already running. It may be assumed that this function implies a write memory barrier before changing the task state if and only if any tasks are woken up. Kernel Hackers Manual October 2009 preempt_notifier_register 9 2.6.32-rc5 preempt_notifier_register tell me when current is being preempted & rescheduled void preempt_notifier_register struct preempt_notifier * notifier notifier notifier struct to register Kernel Hackers Manual October 2009 preempt_notifier_unregister 9 2.6.32-rc5 preempt_notifier_unregister no longer interested in preemption notifications void preempt_notifier_unregister struct preempt_notifier * notifier notifier notifier struct to unregister This is safe to call from within a preemption notifier. Kernel Hackers Manual October 2009 __wake_up 9 2.6.32-rc5 __wake_up wake up threads blocked on a waitqueue. void __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 It may be assumed that this function implies a write memory barrier before changing the task state if and only if any tasks are woken up. Kernel Hackers Manual October 2009 __wake_up_sync_key 9 2.6.32-rc5 __wake_up_sync_key wake up threads blocked on a waitqueue. void __wake_up_sync_key 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 opaque value to be passed to wakeup targets 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. It may be assumed that this function implies a write memory barrier before changing the task state if and only if any tasks are woken up. Kernel Hackers Manual October 2009 complete 9 2.6.32-rc5 complete signals a single thread waiting on this completion void complete struct completion * x x holds the state of this particular completion This will wake up a single thread waiting on this completion. Threads will be awakened in the same order in which they were queued. See also complete_all, wait_for_completion and related routines. It may be assumed that this function implies a write memory barrier before changing the task state if and only if any tasks are woken up. Kernel Hackers Manual October 2009 complete_all 9 2.6.32-rc5 complete_all signals all threads waiting on this completion void complete_all struct completion * x x holds the state of this particular completion This will wake up all threads waiting on this particular completion event. It may be assumed that this function implies a write memory barrier before changing the task state if and only if any tasks are woken up. Kernel Hackers Manual October 2009 wait_for_completion 9 2.6.32-rc5 wait_for_completion waits for completion of a task void __sched wait_for_completion struct completion * x x holds the state of this particular completion This waits to be signaled for completion of a specific task. It is NOT interruptible and there is no timeout. See also similar routines (i.e. wait_for_completion_timeout) with timeout and interrupt capability. Also see complete. Kernel Hackers Manual October 2009 wait_for_completion_timeout 9 2.6.32-rc5 wait_for_completion_timeout waits for completion of a task (w/timeout) unsigned long __sched wait_for_completion_timeout struct completion * x unsigned long timeout x holds the state of this particular completion timeout timeout value in jiffies This waits for either a completion of a specific task to be signaled or for a specified timeout to expire. The timeout is in jiffies. It is not interruptible. Kernel Hackers Manual October 2009 wait_for_completion_interruptible 9 2.6.32-rc5 wait_for_completion_interruptible waits for completion of a task (w/intr) int __sched wait_for_completion_interruptible struct completion * x x holds the state of this particular completion This waits for completion of a specific task to be signaled. It is interruptible. Kernel Hackers Manual October 2009 wait_for_completion_interruptible_timeout 9 2.6.32-rc5 wait_for_completion_interruptible_timeout waits for completion (w/(to,intr)) unsigned long __sched wait_for_completion_interruptible_timeout struct completion * x unsigned long timeout x holds the state of this particular completion timeout timeout value in jiffies This waits for either a completion of a specific task to be signaled or for a specified timeout to expire. It is interruptible. The timeout is in jiffies. Kernel Hackers Manual October 2009 wait_for_completion_killable 9 2.6.32-rc5 wait_for_completion_killable waits for completion of a task (killable) int __sched wait_for_completion_killable struct completion * x x holds the state of this particular completion This waits to be signaled for completion of a specific task. It can be interrupted by a kill signal. Kernel Hackers Manual October 2009 try_wait_for_completion 9 2.6.32-rc5 try_wait_for_completion try to decrement a completion without blocking bool try_wait_for_completion struct completion * x x completion structure 0 if a decrement cannot be done without blocking 1 if a decrement succeeded. If a completion is being used as a counting completion, attempt to decrement the counter without blocking. This enables us to avoid waiting if the resource the completion is protecting is not available. Kernel Hackers Manual October 2009 completion_done 9 2.6.32-rc5 completion_done Test to see if a completion has any waiters bool completion_done struct completion * x x completion structure 0 if there are waiters (wait_for_completion in progress) 1 if there are no waiters. Kernel Hackers Manual October 2009 task_nice 9 2.6.32-rc5 task_nice return the nice value of a given task. int task_nice const struct task_struct * p p the task in question. Kernel Hackers Manual October 2009 sched_setscheduler 9 2.6.32-rc5 sched_setscheduler change the scheduling policy and/or RT priority of a thread. 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. NOTE that the task may be already dead. Kernel Hackers Manual October 2009 yield 9 2.6.32-rc5 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 October 2009 __round_jiffies 9 2.6.32-rc5 __round_jiffies function to round jiffies to a full second unsigned long __round_jiffies unsigned long j int cpu j the time in (absolute) jiffies that should be rounded cpu the processor number on which the timeout will happen __round_jiffies rounds an absolute time in the future (in jiffies) up or down to (approximately) full seconds. This is useful for timers for which the exact time they fire does not matter too much, as long as they fire approximately every X seconds. By rounding these timers to whole seconds, all such timers will fire at the same time, rather than at various times spread out. The goal of this is to have the CPU wake up less, which saves power. The exact rounding is skewed for each processor to avoid all processors firing at the exact same time, which could lead to lock contention or spurious cache line bouncing. The return value is the rounded version of the j parameter. Kernel Hackers Manual October 2009 __round_jiffies_relative 9 2.6.32-rc5 __round_jiffies_relative function to round jiffies to a full second unsigned long __round_jiffies_relative unsigned long j int cpu j the time in (relative) jiffies that should be rounded cpu the processor number on which the timeout will happen __round_jiffies_relative rounds a time delta in the future (in jiffies) up or down to (approximately) full seconds. This is useful for timers for which the exact time they fire does not matter too much, as long as they fire approximately every X seconds. By rounding these timers to whole seconds, all such timers will fire at the same time, rather than at various times spread out. The goal of this is to have the CPU wake up less, which saves power. The exact rounding is skewed for each processor to avoid all processors firing at the exact same time, which could lead to lock contention or spurious cache line bouncing. The return value is the rounded version of the j parameter. Kernel Hackers Manual October 2009 round_jiffies 9 2.6.32-rc5 round_jiffies function to round jiffies to a full second unsigned long round_jiffies unsigned long j j the time in (absolute) jiffies that should be rounded round_jiffies rounds an absolute time in the future (in jiffies) up or down to (approximately) full seconds. This is useful for timers for which the exact time they fire does not matter too much, as long as they fire approximately every X seconds. By rounding these timers to whole seconds, all such timers will fire at the same time, rather than at various times spread out. The goal of this is to have the CPU wake up less, which saves power. The return value is the rounded version of the j parameter. Kernel Hackers Manual October 2009 round_jiffies_relative 9 2.6.32-rc5 round_jiffies_relative function to round jiffies to a full second unsigned long round_jiffies_relative unsigned long j j the time in (relative) jiffies that should be rounded round_jiffies_relative rounds a time delta in the future (in jiffies) up or down to (approximately) full seconds. This is useful for timers for which the exact time they fire does not matter too much, as long as they fire approximately every X seconds. By rounding these timers to whole seconds, all such timers will fire at the same time, rather than at various times spread out. The goal of this is to have the CPU wake up less, which saves power. The return value is the rounded version of the j parameter. Kernel Hackers Manual October 2009 __round_jiffies_up 9 2.6.32-rc5 __round_jiffies_up function to round jiffies up to a full second unsigned long __round_jiffies_up unsigned long j int cpu j the time in (absolute) jiffies that should be rounded cpu the processor number on which the timeout will happen This is the same as __round_jiffies except that it will never round down. This is useful for timeouts for which the exact time of firing does not matter too much, as long as they don't fire too early. Kernel Hackers Manual October 2009 __round_jiffies_up_relative 9 2.6.32-rc5 __round_jiffies_up_relative function to round jiffies up to a full second unsigned long __round_jiffies_up_relative unsigned long j int cpu j the time in (relative) jiffies that should be rounded cpu the processor number on which the timeout will happen This is the same as __round_jiffies_relative except that it will never round down. This is useful for timeouts for which the exact time of firing does not matter too much, as long as they don't fire too early. Kernel Hackers Manual October 2009 round_jiffies_up 9 2.6.32-rc5 round_jiffies_up function to round jiffies up to a full second unsigned long round_jiffies_up unsigned long j j the time in (absolute) jiffies that should be rounded This is the same as round_jiffies except that it will never round down. This is useful for timeouts for which the exact time of firing does not matter too much, as long as they don't fire too early. Kernel Hackers Manual October 2009 round_jiffies_up_relative 9 2.6.32-rc5 round_jiffies_up_relative function to round jiffies up to a full second unsigned long round_jiffies_up_relative unsigned long j j the time in (relative) jiffies that should be rounded This is the same as round_jiffies_relative except that it will never round down. This is useful for timeouts for which the exact time of firing does not matter too much, as long as they don't fire too early. Kernel Hackers Manual October 2009 init_timer_key 9 2.6.32-rc5 init_timer_key initialize a timer void init_timer_key struct timer_list * timer const char * name struct lock_class_key * key timer the timer to be initialized name name of the timer key lockdep class key of the fake lock used for tracking timer sync lock dependencies init_timer_key must be done to a timer prior calling *any* of the other timer functions. Kernel Hackers Manual October 2009 mod_timer_pending 9 2.6.32-rc5 mod_timer_pending modify a pending timer's timeout int mod_timer_pending struct timer_list * timer unsigned long expires timer the pending timer to be modified expires new timeout in jiffies mod_timer_pending is the same for pending timers as mod_timer, but will not re-activate and modify already deleted timers. It is useful for unserialized use of timers. Kernel Hackers Manual October 2009 mod_timer 9 2.6.32-rc5 mod_timer modify a timer's timeout int mod_timer struct timer_list * timer unsigned long expires timer the timer to be modified expires new timeout in jiffies mod_timer is a more efficient way to update the expire field of an active timer (if the timer is inactive it will be activated) mod_timer(timer, expires) is equivalent to: del_timer(timer); timer->expires = expires; add_timer(timer); Note that if there are multiple unserialized concurrent users of the same timer, then mod_timer is the only safe way to modify the timeout, since add_timer cannot modify an already running timer. The function returns whether it has modified a pending timer or not. (ie. mod_timer of an inactive timer returns 0, mod_timer of an active timer returns 1.) Kernel Hackers Manual October 2009 mod_timer_pinned 9 2.6.32-rc5 mod_timer_pinned modify a timer's timeout int mod_timer_pinned struct timer_list * timer unsigned long expires timer the timer to be modified expires new timeout in jiffies mod_timer_pinned is a way to update the expire field of an active timer (if the timer is inactive it will be activated) and not allow the timer to be migrated to a different CPU. mod_timer_pinned(timer, expires) is equivalent to: del_timer(timer); timer->expires = expires; add_timer(timer); Kernel Hackers Manual October 2009 add_timer 9 2.6.32-rc5 add_timer start a timer void add_timer struct timer_list * timer timer the timer to be added The kernel will do a ->function(->data) callback from the timer interrupt at the ->expires point in the future. The current time is 'jiffies'. The timer's ->expires, ->function (and if the handler uses it, ->data) fields must be set prior calling this function. Timers with an ->expires field in the past will be executed in the next timer tick. Kernel Hackers Manual October 2009 add_timer_on 9 2.6.32-rc5 add_timer_on start a timer on a particular CPU void add_timer_on struct timer_list * timer int cpu timer the timer to be added cpu the CPU to start it on This is not very scalable on SMP. Double adds are not possible. Kernel Hackers Manual October 2009 del_timer 9 2.6.32-rc5 del_timer deactive a timer. int del_timer struct timer_list * timer timer the timer to be deactivated del_timer deactivates a timer - this works on both active and inactive timers. The function returns whether it has deactivated a pending timer or not. (ie. del_timer of an inactive timer returns 0, del_timer of an active timer returns 1.) Kernel Hackers Manual October 2009 try_to_del_timer_sync 9 2.6.32-rc5 try_to_del_timer_sync Try to deactivate a timer int try_to_del_timer_sync struct timer_list * timer timer timer do del This function tries to deactivate a timer. Upon successful (ret >= 0) exit the timer is not queued and the handler is not running on any CPU. It must not be called from interrupt contexts. Kernel Hackers Manual October 2009 del_timer_sync 9 2.6.32-rc5 del_timer_sync deactivate a timer and wait for the handler to finish. int del_timer_sync struct timer_list * timer timer the timer to be deactivated This function only differs from del_timer on SMP: besides deactivating the timer it also makes sure the handler has finished executing on other CPUs. Callers must prevent restarting of the timer, otherwise this function is meaningless. It must not be called from interrupt contexts. The caller must not hold locks which would prevent completion of the timer's handler. The timer's handler must not call add_timer_on. Upon exit the timer is not queued and the handler is not running on any CPU. The function returns whether it has deactivated a pending timer or not. Kernel Hackers Manual October 2009 schedule_timeout 9 2.6.32-rc5 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 October 2009 msleep 9 2.6.32-rc5 msleep sleep safely even with waitqueue interruptions void msleep unsigned int msecs msecs Time in milliseconds to sleep for Kernel Hackers Manual October 2009 msleep_interruptible 9 2.6.32-rc5 msleep_interruptible sleep waiting for signals unsigned long msleep_interruptible unsigned int msecs msecs Time in milliseconds to sleep for Kernel Hackers Manual October 2009 ktime_set 9 2.6.32-rc5 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 Kernel Hackers Manual October 2009 ktime_sub 9 2.6.32-rc5 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 Kernel Hackers Manual October 2009 ktime_add 9 2.6.32-rc5 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 add1 and add2. Kernel Hackers Manual October 2009 timespec_to_ktime 9 2.6.32-rc5 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 Kernel Hackers Manual October 2009 timeval_to_ktime 9 2.6.32-rc5 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 Kernel Hackers Manual October 2009 ktime_to_timespec 9 2.6.32-rc5 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 Kernel Hackers Manual October 2009 ktime_to_timeval 9 2.6.32-rc5 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 Kernel Hackers Manual October 2009 ktime_to_ns 9 2.6.32-rc5 ktime_to_ns convert a ktime_t variable to scalar nanoseconds s64 ktime_to_ns const ktime_t kt kt the ktime_t variable to convert Returns the scalar nanoseconds representation of kt Kernel Hackers Manual October 2009 ktime_equal 9 2.6.32-rc5 ktime_equal Compares two ktime_t variables to see if they are equal int ktime_equal const ktime_t cmp1 const ktime_t cmp2 cmp1 comparable1 cmp2 comparable2 Compare two ktime_t variables, returns 1 if equal Kernel Hackers Manual October 2009 struct hrtimer 9 2.6.32-rc5 struct hrtimer the basic hrtimer structure struct hrtimer { struct rb_node node; ktime_t _expires; ktime_t _softexpires; enum hrtimer_restart (* function) (struct hrtimer *); struct hrtimer_clock_base * base; unsigned long state; #ifdef CONFIG_TIMER_STATS int start_pid; void * start_site; char start_comm[16]; #endif }; 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. Is setup by adding slack to the _softexpires value. For non range timers identical to _softexpires. _softexpires the absolute earliest expiry time of the hrtimer. The time which was given as expiry time when the timer was armed. function timer expiry callback function base pointer to the timer base (per cpu and per clock) state state information (See bit values above) start_pid timer statistics field to store the pid of the task which started the timer start_site timer statistics field to store the site where the timer was started start_comm[16] timer statistics field to store the name of the process which started the timer The hrtimer structure must be initialized by hrtimer_init Kernel Hackers Manual October 2009 struct hrtimer_sleeper 9 2.6.32-rc5 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. Kernel Hackers Manual October 2009 struct hrtimer_clock_base 9 2.6.32-rc5 struct hrtimer_clock_base the timer base for a specific clock struct hrtimer_clock_base { struct hrtimer_cpu_base * cpu_base; clockid_t index; struct rb_root active; struct rb_node * first; ktime_t resolution; ktime_t (* get_time) (void); ktime_t softirq_time; #ifdef CONFIG_HIGH_RES_TIMERS ktime_t offset; #endif }; cpu_base per cpu clock base index clock type index for per_cpu support when moving a timer to a base on another cpu. 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 softirq_time the time when running the hrtimer queue in the softirq offset offset of this clock to the monotonic base Kernel Hackers Manual October 2009 ktime_add_ns 9 2.6.32-rc5 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 Kernel Hackers Manual October 2009 ktime_sub_ns 9 2.6.32-rc5 ktime_sub_ns Subtract a scalar nanoseconds value from a ktime_t variable ktime_t ktime_sub_ns const ktime_t kt u64 nsec kt minuend nsec the scalar nsec value to subtract Returns the subtraction of nsec from kt in ktime_t format Kernel Hackers Manual October 2009 hrtimer_forward 9 2.6.32-rc5 hrtimer_forward forward the timer expiry u64 hrtimer_forward struct hrtimer * timer ktime_t now ktime_t interval timer hrtimer to forward now forward past this time interval the interval to forward Forward the timer expiry so it will expire in the future. Returns the number of overruns. Kernel Hackers Manual October 2009 hrtimer_start_range_ns 9 2.6.32-rc5 hrtimer_start_range_ns (re)start an hrtimer on the current CPU int hrtimer_start_range_ns struct hrtimer * timer ktime_t tim unsigned long delta_ns const enum hrtimer_mode mode timer the timer to be added tim expiry time delta_ns "slack" range for the timer mode expiry mode: absolute (HRTIMER_ABS) or relative (HRTIMER_REL) 0 on success 1 when the timer was active Kernel Hackers Manual October 2009 hrtimer_start 9 2.6.32-rc5 hrtimer_start (re)start an hrtimer on the current CPU int hrtimer_start struct hrtimer * timer ktime_t tim const enum hrtimer_mode mode timer the timer to be added tim expiry time mode expiry mode: absolute (HRTIMER_ABS) or relative (HRTIMER_REL) 0 on success 1 when the timer was active Kernel Hackers Manual October 2009 hrtimer_try_to_cancel 9 2.6.32-rc5 hrtimer_try_to_cancel try to deactivate a timer int hrtimer_try_to_cancel struct hrtimer * timer timer hrtimer to stop 0 when the timer was not active 1 when the timer was active -1 when the timer is currently excuting the callback function and cannot be stopped Kernel Hackers Manual October 2009 hrtimer_cancel 9 2.6.32-rc5 hrtimer_cancel cancel a timer and wait for the handler to finish. int hrtimer_cancel struct hrtimer * timer timer the timer to be cancelled 0 when the timer was not active 1 when the timer was active Kernel Hackers Manual October 2009 hrtimer_get_remaining 9 2.6.32-rc5 hrtimer_get_remaining get remaining time for the timer ktime_t hrtimer_get_remaining const struct hrtimer * timer timer the timer to read Kernel Hackers Manual October 2009 hrtimer_init 9 2.6.32-rc5 hrtimer_init initialize a timer to the given clock void hrtimer_init struct hrtimer * timer clockid_t clock_id enum hrtimer_mode mode timer the timer to be initialized clock_id the clock to be used mode timer mode abs/rel Kernel Hackers Manual October 2009 hrtimer_get_res 9 2.6.32-rc5 hrtimer_get_res get the timer resolution for a clock int hrtimer_get_res const clockid_t which_clock struct timespec * tp which_clock which clock to query tp pointer to timespec variable to store the resolution Store the resolution of the clock selected by which_clock in the variable pointed to by tp. Kernel Hackers Manual October 2009 schedule_hrtimeout_range 9 2.6.32-rc5 schedule_hrtimeout_range sleep until timeout int __sched schedule_hrtimeout_range ktime_t * expires unsigned long delta const enum hrtimer_mode mode expires timeout value (ktime_t) delta slack in expires timeout (ktime_t) mode timer mode, HRTIMER_MODE_ABS or HRTIMER_MODE_REL Make the current task sleep until the given expiry time has elapsed. The routine will return immediately unless the current task state has been set (see set_current_state). The delta argument gives the kernel the freedom to schedule the actual wakeup to a time that is both power and performance friendly. The kernel give the normal best effort behavior for expires+delta, but may decide to fire the timer earlier, but no earlier than expires. You can set the task state as follows - TASK_UNINTERRUPTIBLE - at least timeout time is guaranteed to pass before the routine returns. TASK_INTERRUPTIBLE - the routine may return early if a signal is delivered to the current task. The current task state is guaranteed to be TASK_RUNNING when this routine returns. Returns 0 when the timer has expired otherwise -EINTR Kernel Hackers Manual October 2009 schedule_hrtimeout 9 2.6.32-rc5 schedule_hrtimeout sleep until timeout int __sched schedule_hrtimeout ktime_t * expires const enum hrtimer_mode mode expires timeout value (ktime_t) mode timer mode, HRTIMER_MODE_ABS or HRTIMER_MODE_REL Make the current task sleep until the given expiry time has 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 time is guaranteed to pass before the routine returns. TASK_INTERRUPTIBLE - the routine may return early if a signal is delivered to the current task. The current task state is guaranteed to be TASK_RUNNING when this routine returns. Returns 0 when the timer has expired otherwise -EINTR Kernel Hackers Manual October 2009 queue_work 9 2.6.32-rc5 queue_work queue work on a workqueue int queue_work struct workqueue_struct * wq struct work_struct * work wq workqueue to use work work to queue Returns 0 if work was already on a queue, non-zero otherwise. We queue the work to the CPU on which it was submitted, but if the CPU dies it can be processed by another CPU. Kernel Hackers Manual October 2009 queue_work_on 9 2.6.32-rc5 queue_work_on queue work on specific cpu int queue_work_on int cpu struct workqueue_struct * wq struct work_struct * work cpu CPU number to execute work on wq workqueue to use work work to queue Returns 0 if work was already on a queue, non-zero otherwise. We queue the work to a specific CPU, the caller must ensure it can't go away. Kernel Hackers Manual October 2009 queue_delayed_work 9 2.6.32-rc5 queue_delayed_work queue work on a workqueue after delay int queue_delayed_work struct workqueue_struct * wq struct delayed_work * dwork unsigned long delay wq workqueue to use dwork delayable work to queue delay number of jiffies to wait before queueing Returns 0 if work was already on a queue, non-zero otherwise. Kernel Hackers Manual October 2009 queue_delayed_work_on 9 2.6.32-rc5 queue_delayed_work_on queue work on specific CPU after delay int queue_delayed_work_on int cpu struct workqueue_struct * wq struct delayed_work * dwork unsigned long delay cpu CPU number to execute work on wq workqueue to use dwork work to queue delay number of jiffies to wait before queueing Returns 0 if work was already on a queue, non-zero otherwise. Kernel Hackers Manual October 2009 flush_workqueue 9 2.6.32-rc5 flush_workqueue ensure that any scheduled work has run to completion. void flush_workqueue struct workqueue_struct * wq wq workqueue to flush Forces execution of the workqueue and blocks until its completion. This is typically used in driver shutdown handlers. We sleep until all works which were queued on entry have been handled, but we are not livelocked by new incoming ones. This function used to run the workqueues itself. Now we just wait for the helper threads to do it. Kernel Hackers Manual October 2009 flush_work 9 2.6.32-rc5 flush_work block until a work_struct's callback has terminated int flush_work struct work_struct * work work the work which is to be flushed Returns false if work has already terminated. It is expected that, prior to calling flush_work, the caller has arranged for the work to not be requeued, otherwise it doesn't make sense to use this function. Kernel Hackers Manual October 2009 cancel_work_sync 9 2.6.32-rc5 cancel_work_sync block until a work_struct's callback has terminated int cancel_work_sync struct work_struct * work work the work which is to be flushed Returns true if work was pending. cancel_work_sync will cancel the work if it is queued. If the work's callback appears to be running, cancel_work_sync will block until it has completed. It is possible to use this function if the work re-queues itself. It can cancel the work even if it migrates to another workqueue, however in that case it only guarantees that work->func has completed on the last queued workqueue. cancel_work_sync(delayed_work->work) should be used only if ->timer is not pending, otherwise it goes into a busy-wait loop until the timer expires. The caller must ensure that workqueue_struct on which this work was last queued can't be destroyed before this function returns. Kernel Hackers Manual October 2009 cancel_delayed_work_sync 9 2.6.32-rc5 cancel_delayed_work_sync reliably kill off a delayed work. int cancel_delayed_work_sync struct delayed_work * dwork dwork the delayed work struct Returns true if dwork was pending. It is possible to use this function if dwork rearms itself via queue_work or queue_delayed_work. See also the comment for cancel_work_sync. Kernel Hackers Manual October 2009 schedule_work 9 2.6.32-rc5 schedule_work put work task in global workqueue int schedule_work struct work_struct * work work job to be done Returns zero if work was already on the kernel-global workqueue and non-zero otherwise. This puts a job in the kernel-global workqueue if it was not already queued and leaves it in the same position on the kernel-global workqueue otherwise. Kernel Hackers Manual October 2009 schedule_delayed_work 9 2.6.32-rc5 schedule_delayed_work put work task in global workqueue after delay int schedule_delayed_work struct delayed_work * dwork unsigned long delay dwork job to be done delay number of jiffies to wait or 0 for immediate execution After waiting for a given time this puts a job in the kernel-global workqueue. Kernel Hackers Manual October 2009 flush_delayed_work 9 2.6.32-rc5 flush_delayed_work block until a dwork_struct's callback has terminated void flush_delayed_work struct delayed_work * dwork dwork the delayed work which is to be flushed Any timeout is cancelled, and any pending work is run immediately. Kernel Hackers Manual October 2009 schedule_delayed_work_on 9 2.6.32-rc5 schedule_delayed_work_on queue work in global workqueue on CPU after delay int schedule_delayed_work_on int cpu struct delayed_work * dwork unsigned long delay cpu cpu to use dwork job to be done delay number of jiffies to wait After waiting for a given time this puts a job in the kernel-global workqueue on the specified CPU. Kernel Hackers Manual October 2009 execute_in_process_context 9 2.6.32-rc5 execute_in_process_context reliably execute the routine with user context int execute_in_process_context work_func_t fn struct execute_work * ew fn the function to execute ew guaranteed storage for the execute work structure (must be available when the work executes) Executes the function immediately if process context is available, otherwise schedules the function for delayed execution. 0 - function was executed 1 - function was scheduled for execution Kernel Hackers Manual October 2009 destroy_workqueue 9 2.6.32-rc5 destroy_workqueue safely terminate a workqueue void destroy_workqueue struct workqueue_struct * wq wq target workqueue Safely destroy a workqueue. All work currently pending will be done first. Kernel Hackers Manual October 2009 work_on_cpu 9 2.6.32-rc5 work_on_cpu run a function in user context on a particular cpu long work_on_cpu unsigned int cpu long (*fn) void * void * arg cpu the cpu to run on fn the function to run arg the function arg This will return the value fn returns. It is up to the caller to ensure that the cpu doesn't go offline. The caller must not hold any locks which would prevent fn from completing. Kernel Hackers Manual October 2009 reparent_to_kthreadd 9 2.6.32-rc5 reparent_to_kthreadd Reparent the calling kernel thread to kthreadd void reparent_to_kthreadd 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 kthreadd so it isn't in the way of other processes and 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_kthreadd gives the caller full capabilities. Kernel Hackers Manual October 2009 sys_tgkill 9 2.6.32-rc5 sys_tgkill send signal to one specific thread long sys_tgkill pid_t tgid pid_t 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 October 2009 kthread_run 9 2.6.32-rc5 kthread_run create and wake a thread. kthread_run threadfn data namefmt ... threadfn the function to run until signal_pending(current). data data ptr for threadfn. namefmt printf-style name for the thread. ... variable arguments Convenient wrapper for kthread_create followed by wake_up_process. Returns the kthread or ERR_PTR(-ENOMEM). Kernel Hackers Manual October 2009 kthread_should_stop 9 2.6.32-rc5 kthread_should_stop should this kthread return now? int kthread_should_stop void void no arguments When someone calls kthread_stop on your kthread, it will be woken and this will return true. You should then return, and your return value will be passed through to kthread_stop. Kernel Hackers Manual October 2009 kthread_create 9 2.6.32-rc5 kthread_create create a kthread. struct task_struct * kthread_create int (*threadfn) void *data void * data const char namefmt[] ... threadfn the function to run until signal_pending(current). data data ptr for threadfn. namefmt[] printf-style name for the thread. ... variable arguments This helper function creates and names a kernel thread. The thread will be stopped: use wake_up_process to start it. See also kthread_run, kthread_create_on_cpu. When woken, the thread will run threadfn() with data as its argument. threadfn() can either call do_exit directly if it is a standalone thread for which noone will call kthread_stop, or return when 'kthread_should_stop' is true (which means kthread_stop has been called). The return value should be zero or a negative error number; it will be passed to kthread_stop. Returns a task_struct or ERR_PTR(-ENOMEM). Kernel Hackers Manual October 2009 kthread_bind 9 2.6.32-rc5 kthread_bind bind a just-created kthread to a cpu. void kthread_bind struct task_struct * k unsigned int cpu k thread created by kthread_create. cpu cpu (might not be online, must be possible) for k to run on. This function is equivalent to set_cpus_allowed, except that cpu doesn't need to be online, and the thread must be stopped (i.e., just returned from kthread_create). Kernel Hackers Manual October 2009 kthread_stop 9 2.6.32-rc5 kthread_stop stop a thread created by kthread_create. int kthread_stop struct task_struct * k k thread created by kthread_create. Sets kthread_should_stop for k to return true, wakes it, and waits for it to exit. This can also be called after kthread_create instead of calling wake_up_process: the thread will exit without calling threadfn. If threadfn may call do_exit itself, the caller must ensure task_struct can't go away. Returns the result of threadfn, or -EINTR if wake_up_process was never called. Kernel Hackers Manual October 2009 kobject_get_path 9 2.6.32-rc5 kobject_get_path generate and return the path associated with a given kobj and kset pair. char * kobject_get_path struct kobject * kobj gfp_t gfp_mask kobj kobject in question, with which to build the path gfp_mask the allocation type used to allocate the path The result must be freed by the caller with kfree. Kernel Hackers Manual October 2009 kobject_set_name 9 2.6.32-rc5 kobject_set_name Set the name of a kobject int kobject_set_name struct kobject * kobj const char * fmt ... kobj struct kobject to set the name of fmt format string used to build the name ... variable arguments This sets the name of the kobject. If you have already added the kobject to the system, you must call kobject_rename in order to change the name of the kobject. Kernel Hackers Manual October 2009 kobject_init 9 2.6.32-rc5 kobject_init initialize a kobject structure void kobject_init struct kobject * kobj struct kobj_type * ktype kobj pointer to the kobject to initialize ktype pointer to the ktype for this kobject. This function will properly initialize a kobject such that it can then be passed to the kobject_add call. After this function is called, the kobject MUST be cleaned up by a call to kobject_put, not by a call to kfree directly to ensure that all of the memory is cleaned up properly. Kernel Hackers Manual October 2009 kobject_add 9 2.6.32-rc5 kobject_add the main kobject add function int kobject_add struct kobject * kobj struct kobject * parent const char * fmt ... kobj the kobject to add parent pointer to the parent of the kobject. fmt format to name the kobject with. ... variable arguments The kobject name is set and added to the kobject hierarchy in this function. If parent is set, then the parent of the kobj will be set to it. If parent is NULL, then the parent of the kobj will be set to the kobject associted with the kset assigned to this kobject. If no kset is assigned to the kobject, then the kobject will be located in the root of the sysfs tree. If this function returns an error, kobject_put must be called to properly clean up the memory associated with the object. Under no instance should the kobject that is passed to this function be directly freed with a call to kfree, that can leak memory. Note, no add uevent will be created with this call, the caller should set up all of the necessary sysfs files for the object and then call kobject_uevent with the UEVENT_ADD parameter to ensure that userspace is properly notified of this kobject's creation. Kernel Hackers Manual October 2009 kobject_init_and_add 9 2.6.32-rc5 kobject_init_and_add initialize a kobject structure and add it to the kobject hierarchy int kobject_init_and_add struct kobject * kobj struct kobj_type * ktype struct kobject * parent const char * fmt ... kobj pointer to the kobject to initialize ktype pointer to the ktype for this kobject. parent pointer to the parent of this kobject. fmt the name of the kobject. ... variable arguments This function combines the call to kobject_init and kobject_add. The same type of error handling after a call to kobject_add and kobject lifetime rules are the same here. Kernel Hackers Manual October 2009 kobject_rename 9 2.6.32-rc5 kobject_rename change the name of an object int kobject_rename struct kobject * kobj const char * new_name kobj object in question. new_name object's new name It is the responsibility of the caller to provide mutual exclusion between two different calls of kobject_rename on the same kobject and to ensure that new_name is valid and won't conflict with other kobjects. Kernel Hackers Manual October 2009 kobject_del 9 2.6.32-rc5 kobject_del unlink kobject from hierarchy. void kobject_del struct kobject * kobj kobj object. Kernel Hackers Manual October 2009 kobject_get 9 2.6.32-rc5 kobject_get increment refcount for object. struct kobject * kobject_get struct kobject * kobj kobj object. Kernel Hackers Manual October 2009 kobject_put 9 2.6.32-rc5 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 October 2009 kobject_create_and_add 9 2.6.32-rc5 kobject_create_and_add create a struct kobject dynamically and register it with sysfs struct kobject * kobject_create_and_add const char * name struct kobject * parent name the name for the kset parent the parent kobject of this kobject, if any. This function creates a kobject structure dynamically and registers it with sysfs. When you are finished with this structure, call kobject_put and the structure will be dynamically freed when it is no longer being used. If the kobject was not able to be created, NULL will be returned. Kernel Hackers Manual October 2009 kset_register 9 2.6.32-rc5 kset_register initialize and add a kset. int kset_register struct kset * k k kset. Kernel Hackers Manual October 2009 kset_unregister 9 2.6.32-rc5 kset_unregister remove a kset. void kset_unregister struct kset * k k kset. Kernel Hackers Manual October 2009 kset_create_and_add 9 2.6.32-rc5 kset_create_and_add create a struct kset dynamically and add it to sysfs struct kset * kset_create_and_add const char * name struct kset_uevent_ops * uevent_ops struct kobject * parent_kobj name the name for the kset uevent_ops a struct kset_uevent_ops for the kset parent_kobj the parent kobject of this kset, if any. This function creates a kset structure dynamically and registers it with sysfs. When you are finished with this structure, call kset_unregister and the structure will be dynamically freed when it is no longer being used. If the kset was not able to be created, NULL will be returned. Kernel Hackers Manual October 2009 upper_32_bits 9 2.6.32-rc5 upper_32_bits return bits 32-63 of a number upper_32_bits n n the number we're accessing A basic shift-right of a 64- or 32-bit quantity. Use this to suppress the right shift count >= width of type warning when that quantity is 32-bits. Kernel Hackers Manual October 2009 lower_32_bits 9 2.6.32-rc5 lower_32_bits return bits 0-31 of a number lower_32_bits n n the number we're accessing Kernel Hackers Manual October 2009 might_sleep 9 2.6.32-rc5 might_sleep annotation for functions that can sleep might_sleep None this macro will print a stack trace if it is executed in an atomic context (spinlock, irq-handler, ...). This is a useful debugging help to be able to catch problems early and not be bitten later when the calling function happens to sleep when it is not supposed to. Kernel Hackers Manual October 2009 trace_printk 9 2.6.32-rc5 trace_printk printf formatting in the ftrace buffer trace_printk fmt args... fmt the printf format for printing args... variable arguments __trace_printk is an internal function for trace_printk and the ip is passed in via the trace_printk macro. This function allows a kernel developer to debug fast path sections that printk is not appropriate for. By scattering in various printk like tracing in the code, a developer can quickly see where problems are occurring. This is intended as a debugging tool for the developer only. Please refrain from leaving trace_printks scattered around in your code. Kernel Hackers Manual October 2009 clamp 9 2.6.32-rc5 clamp return a value clamped to a given range with strict typechecking clamp val min max val current value min minimum allowable value max maximum allowable value This macro does strict typechecking of min/max to make sure they are of the same type as val. See the unnecessary pointer comparisons. Kernel Hackers Manual October 2009 clamp_t 9 2.6.32-rc5 clamp_t return a value clamped to a given range using a given type clamp_t type val min max type the type of variable to use val current value min minimum allowable value max maximum allowable value This macro does no typechecking and uses temporary variables of type 'type' to make all the comparisons. Kernel Hackers Manual October 2009 clamp_val 9 2.6.32-rc5 clamp_val return a value clamped to a given range using val's type clamp_val val min max val current value min minimum allowable value max maximum allowable value This macro does no typechecking and uses temporary variables of whatever type the input argument 'val' is. This is useful when val is an unsigned type and min and max are literals that will otherwise be assigned a signed integer type. Kernel Hackers Manual October 2009 container_of 9 2.6.32-rc5 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 October 2009 printk 9 2.6.32-rc5 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) See the vsnprintf documentation for format string extensions over C99. Kernel Hackers Manual October 2009 acquire_console_sem 9 2.6.32-rc5 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 October 2009 release_console_sem 9 2.6.32-rc5 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 October 2009 console_conditional_schedule 9 2.6.32-rc5 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 October 2009 printk_timed_ratelimit 9 2.6.32-rc5 printk_timed_ratelimit caller-controlled printk ratelimiting bool printk_timed_ratelimit unsigned long * caller_jiffies unsigned int interval_msecs caller_jiffies pointer to caller's state interval_msecs minimum interval between prints printk_timed_ratelimit returns true if more than interval_msecs milliseconds have elapsed since the last time printk_timed_ratelimit returned true. Kernel Hackers Manual October 2009 panic 9 2.6.32-rc5 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 October 2009 emergency_restart 9 2.6.32-rc5 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 October 2009 kernel_restart 9 2.6.32-rc5 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 October 2009 kernel_halt 9 2.6.32-rc5 kernel_halt halt the system void kernel_halt void void no arguments Shutdown everything and perform a clean system halt. Kernel Hackers Manual October 2009 kernel_power_off 9 2.6.32-rc5 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 October 2009 orderly_poweroff 9 2.6.32-rc5 orderly_poweroff Trigger an orderly system poweroff int orderly_poweroff bool force force force poweroff if command execution fails This may be called from any context to trigger a system shutdown. If the orderly shutdown fails, it will force an immediate shutdown. Kernel Hackers Manual October 2009 synchronize_rcu 9 2.6.32-rc5 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. Kernel Hackers Manual October 2009 synchronize_sched 9 2.6.32-rc5 synchronize_sched wait until an rcu-sched grace period has elapsed. void synchronize_sched void void no arguments Control will return to the caller some time after a full rcu-sched grace period has elapsed, in other words after all currently executing rcu-sched read-side critical sections have completed. These read-side critical sections are delimited by rcu_read_lock_sched and rcu_read_unlock_sched, and may be nested. Note that preempt_disable, local_irq_disable, and so on may be used in place of rcu_read_lock_sched. This means that all preempt_disable code sequences, including NMI and hardware-interrupt handlers, in progress on entry will have completed before this primitive returns. However, this does not guarantee that softirq handlers will have completed, since in some kernels, these handlers can run in process context, and can block. This primitive provides the guarantees made by the (now removed) synchronize_kernel API. In contrast, synchronize_rcu only guarantees that rcu_read_lock sections will have completed. In classic RCU, these two guarantees happen to be one and the same, but can differ in realtime RCU implementations. Kernel Hackers Manual October 2009 synchronize_rcu_bh 9 2.6.32-rc5 synchronize_rcu_bh wait until an rcu_bh grace period has elapsed. void synchronize_rcu_bh void void no arguments Control will return to the caller some time after a full rcu_bh grace period has elapsed, in other words after all currently executing rcu_bh read-side critical sections have completed. RCU read-side critical sections are delimited by rcu_read_lock_bh and rcu_read_unlock_bh, and may be nested. Kernel Hackers Manual October 2009 devres_alloc 9 2.6.32-rc5 devres_alloc Allocate device resource data void * devres_alloc dr_release_t release size_t size gfp_t gfp release Release function devres will be associated with size Allocation size gfp Allocation flags Allocate devres of size bytes. The allocated area is zeroed, then associated with release. The returned pointer can be passed to other devres_*() functions. Pointer to allocated devres on success, NULL on failure. Kernel Hackers Manual October 2009 devres_free 9 2.6.32-rc5 devres_free Free device resource data void devres_free void * res res Pointer to devres data to free Free devres created with devres_alloc. Kernel Hackers Manual October 2009 devres_add 9 2.6.32-rc5 devres_add Register device resource void devres_add struct device * dev void * res dev Device to add resource to res Resource to register Register devres res to dev. res should have been allocated using devres_alloc. On driver detach, the associated release function will be invoked and devres will be freed automatically. Kernel Hackers Manual October 2009 devres_find 9 2.6.32-rc5 devres_find Find device resource void * devres_find struct device * dev dr_release_t release dr_match_t match void * match_data dev Device to lookup resource from release Look for resources associated with this release function match Match function (optional) match_data Data for the match function Find the latest devres of dev which is associated with release and for which match returns 1. If match is NULL, it's considered to match all. Pointer to found devres, NULL if not found. Kernel Hackers Manual October 2009 devres_get 9 2.6.32-rc5 devres_get Find devres, if non-existent, add one atomically void * devres_get struct device * dev void * new_res dr_match_t match void * match_data dev Device to lookup or add devres for new_res Pointer to new initialized devres to add if not found match Match function (optional) match_data Data for the match function Find the latest devres of dev which has the same release function as new_res and for which match return 1. If found, new_res is freed; otherwise, new_res is added atomically. Pointer to found or added devres. Kernel Hackers Manual October 2009 devres_remove 9 2.6.32-rc5 devres_remove Find a device resource and remove it void * devres_remove struct device * dev dr_release_t release dr_match_t match void * match_data dev Device to find resource from release Look for resources associated with this release function match Match function (optional) match_data Data for the match function Find the latest devres of dev associated with release and for which match returns 1. If match is NULL, it's considered to match all. If found, the resource is removed atomically and returned. Pointer to removed devres on success, NULL if not found. Kernel Hackers Manual October 2009 devres_destroy 9 2.6.32-rc5 devres_destroy Find a device resource and destroy it int devres_destroy struct device * dev dr_release_t release dr_match_t match void * match_data dev Device to find resource from release Look for resources associated with this release function match Match function (optional) match_data Data for the match function Find the latest devres of dev associated with release and for which match returns 1. If match is NULL, it's considered to match all. If found, the resource is removed atomically and freed. 0 if devres is found and freed, -ENOENT if not found. Kernel Hackers Manual October 2009 devres_open_group 9 2.6.32-rc5 devres_open_group Open a new devres group void * devres_open_group struct device * dev void * id gfp_t gfp dev Device to open devres group for id Separator ID gfp Allocation flags Open a new devres group for dev with id. For id, using a pointer to an object which won't be used for another group is recommended. If id is NULL, address-wise unique ID is created. ID of the new group, NULL on failure. Kernel Hackers Manual October 2009 devres_close_group 9 2.6.32-rc5 devres_close_group Close a devres group void devres_close_group struct device * dev void * id dev Device to close devres group for id ID of target group, can be NULL Close the group identified by id. If id is NULL, the latest open group is selected. Kernel Hackers Manual October 2009 devres_remove_group 9 2.6.32-rc5 devres_remove_group Remove a devres group void devres_remove_group struct device * dev void * id dev Device to remove group for id ID of target group, can be NULL Remove the group identified by id. If id is NULL, the latest open group is selected. Note that removing a group doesn't affect any other resources. Kernel Hackers Manual October 2009 devres_release_group 9 2.6.32-rc5 devres_release_group Release resources in a devres group int devres_release_group struct device * dev void * id dev Device to release group for id ID of target group, can be NULL Release all resources in the group identified by id. If id is NULL, the latest open group is selected. The selected group and groups properly nested inside the selected group are removed. The number of released non-group resources. Kernel Hackers Manual October 2009 devm_kzalloc 9 2.6.32-rc5 devm_kzalloc Resource-managed kzalloc void * devm_kzalloc struct device * dev size_t size gfp_t gfp dev Device to allocate memory for size Allocation size gfp Allocation gfp flags Managed kzalloc. Memory allocated with this function is automatically freed on driver detach. Like all other devres resources, guaranteed alignment is unsigned long long. Pointer to allocated memory on success, NULL on failure. Kernel Hackers Manual October 2009 devm_kfree 9 2.6.32-rc5 devm_kfree Resource-managed kfree void devm_kfree struct device * dev void * p dev Device this memory belongs to p Memory to free Free memory allocated with dev_kzalloc. Kernel Hackers Manual October 2009 driver_for_each_device 9 2.6.32-rc5 driver_for_each_device Iterator for devices bound to a driver. int driver_for_each_device struct device_driver * drv struct device * start void * data int (*fn) struct device *, void * drv Driver we're iterating. start Device to begin with data Data to pass to the callback. fn Function to call for each device. Iterate over the drv's list of devices calling fn for each one. Kernel Hackers Manual October 2009 driver_find_device 9 2.6.32-rc5 driver_find_device device iterator for locating a particular device. struct device * driver_find_device struct device_driver * drv struct device * start void * data int (*match) struct device *dev, void *data drv The device's driver start Device to begin with data Data to pass to match function match Callback function to check device This is similar to the driver_for_each_device function above, but it returns a reference to a device that is 'found' for later use, as determined by the match callback. The callback should return 0 if the device doesn't match and non-zero if it does. If the callback returns non-zero, this function will return to the caller and not iterate over any more devices. Kernel Hackers Manual October 2009 driver_create_file 9 2.6.32-rc5 driver_create_file create sysfs file for driver. int driver_create_file struct device_driver * drv struct driver_attribute * attr drv driver. attr driver attribute descriptor. Kernel Hackers Manual October 2009 driver_remove_file 9 2.6.32-rc5 driver_remove_file remove sysfs file for driver. void driver_remove_file struct device_driver * drv struct driver_attribute * attr drv driver. attr driver attribute descriptor. Kernel Hackers Manual October 2009 driver_add_kobj 9 2.6.32-rc5 driver_add_kobj add a kobject below the specified driver int driver_add_kobj struct device_driver * drv struct kobject * kobj const char * fmt ... drv requesting device driver kobj kobject to add below this driver fmt format string that names the kobject ... variable arguments You really don't want to do this, this is only here due to one looney iseries driver, go poke those developers if you are annoyed about this... Kernel Hackers Manual October 2009 get_driver 9 2.6.32-rc5 get_driver increment driver reference count. struct device_driver * get_driver struct device_driver * drv drv driver. Kernel Hackers Manual October 2009 put_driver 9 2.6.32-rc5 put_driver decrement driver's refcount. void put_driver struct device_driver * drv drv driver. Kernel Hackers Manual October 2009 driver_register 9 2.6.32-rc5 driver_register register driver with bus int driver_register struct device_driver * drv drv driver to register We pass off most of the work to the bus_add_driver call, since most of the things we have to do deal with the bus structures. Kernel Hackers Manual October 2009 driver_unregister 9 2.6.32-rc5 driver_unregister remove driver from system. void driver_unregister struct device_driver * drv drv driver. Again, we pass off most of the work to the bus-level call. Kernel Hackers Manual October 2009 driver_find 9 2.6.32-rc5 driver_find locate driver on a bus by its name. struct device_driver * driver_find const char * name struct bus_type * bus name name of the driver. bus bus to scan for the driver. Call kset_find_obj to iterate over list of drivers on a bus to find driver by name. Return driver if found. Note that kset_find_obj increments driver's reference count. Kernel Hackers Manual October 2009 dev_driver_string 9 2.6.32-rc5 dev_driver_string Return a device's driver name, if at all possible const char * dev_driver_string const struct device * dev dev struct device to get the name of Will return the device's driver's name if it is bound to a device. If the device is not bound to a device, it will return the name of the bus it is attached to. If it is not attached to a bus either, an empty string will be returned. Kernel Hackers Manual October 2009 device_create_file 9 2.6.32-rc5 device_create_file create sysfs attribute file for device. int device_create_file struct device * dev struct device_attribute * attr dev device. attr device attribute descriptor. Kernel Hackers Manual October 2009 device_remove_file 9 2.6.32-rc5 device_remove_file remove sysfs attribute file. void device_remove_file struct device * dev struct device_attribute * attr dev device. attr device attribute descriptor. Kernel Hackers Manual October 2009 device_create_bin_file 9 2.6.32-rc5 device_create_bin_file create sysfs binary attribute file for device. int device_create_bin_file struct device * dev struct bin_attribute * attr dev device. attr device binary attribute descriptor. Kernel Hackers Manual October 2009 device_remove_bin_file 9 2.6.32-rc5 device_remove_bin_file remove sysfs binary attribute file void device_remove_bin_file struct device * dev struct bin_attribute * attr dev device. attr device binary attribute descriptor. Kernel Hackers Manual October 2009 device_schedule_callback_owner 9 2.6.32-rc5 device_schedule_callback_owner helper to schedule a callback for a device int device_schedule_callback_owner struct device * dev void (*func) struct device * struct module * owner dev device. func callback function to invoke later. owner module owning the callback routine Attribute methods must not unregister themselves or their parent device (which would amount to the same thing). Attempts to do so will deadlock, since unregistration is mutually exclusive with driver callbacks. Instead methods can call this routine, which will attempt to allocate and schedule a workqueue request to call back func with dev as its argument in the workqueue's process context. dev will be pinned until func returns. This routine is usually called via the inline device_schedule_callback, which automatically sets owner to THIS_MODULE. Returns 0 if the request was submitted, -ENOMEM if storage could not be allocated, -ENODEV if a reference to owner isn't available. This routine won't work if CONFIG_SYSFS isn't set! It uses an underlying sysfs routine (since it is intended for use by attribute methods), and if sysfs isn't available you'll get nothing but -ENOSYS. Kernel Hackers Manual October 2009 device_initialize 9 2.6.32-rc5 device_initialize init device structure. void device_initialize struct device * dev dev device. This prepares the device for use by other layers by initializing its fields. It is the first half of device_register, if called by that function, though it can also be called separately, so one may use dev's fields. In particular, get_device/put_device may be used for reference counting of dev after calling this function. Use put_device to give up your reference instead of freeing dev directly once you have called this function. Kernel Hackers Manual October 2009 dev_set_name 9 2.6.32-rc5 dev_set_name set a device name int dev_set_name struct device * dev const char * fmt ... dev device fmt format string for the device's name ... variable arguments Kernel Hackers Manual October 2009 device_add 9 2.6.32-rc5 device_add add device to device hierarchy. int device_add struct device * dev dev device. This is part 2 of device_register, though may be called separately _iff_ device_initialize has been called separately. This adds dev to the kobject hierarchy via kobject_add, adds it to the global and sibling lists for the device, then adds it to the other relevant subsystems of the driver model. _Never_ directly free dev after calling this function, even if it returned an error! Always use put_device to give up your reference instead. Kernel Hackers Manual October 2009 device_register 9 2.6.32-rc5 device_register register a device with the system. int device_register struct device * dev dev pointer to the device structure This happens in two clean steps - initialize the device and add it to the system. The two steps can be called separately, but this is the easiest and most common. I.e. you should only call the two helpers separately if have a clearly defined need to use and refcount the device before it is added to the hierarchy. _Never_ directly free dev after calling this function, even if it returned an error! Always use put_device to give up the reference initialized in this function instead. Kernel Hackers Manual October 2009 get_device 9 2.6.32-rc5 get_device increment reference count for device. struct device * get_device struct device * dev dev device. This simply forwards the call to kobject_get, though we do take care to provide for the case that we get a NULL pointer passed in. Kernel Hackers Manual October 2009 put_device 9 2.6.32-rc5 put_device decrement reference count. void put_device struct device * dev dev device in question. Kernel Hackers Manual October 2009 device_del 9 2.6.32-rc5 device_del delete device from system. void device_del struct device * dev dev device. This is the first part of the device unregistration sequence. This removes the device from the lists we control from here, has it removed from the other driver model subsystems it was added to in device_add, and removes it from the kobject hierarchy. this should be called manually _iff_ device_add was also called manually. Kernel Hackers Manual October 2009 device_unregister 9 2.6.32-rc5 device_unregister unregister device from system. void device_unregister struct device * dev dev device going away. We do this in two parts, like we do device_register. First, we remove it from all the subsystems with device_del, then we decrement the reference count via put_device. If that is the final reference count, the device will be cleaned up via device_release above. Otherwise, the structure will stick around until the final reference to the device is dropped. Kernel Hackers Manual October 2009 device_for_each_child 9 2.6.32-rc5 device_for_each_child device child iterator. int device_for_each_child struct device * parent void * data int (*fn) struct device *dev, void *data parent parent struct device. data data for the callback. fn function to be called for each device. Iterate over parent's child devices, and call fn for each, passing it data. We check the return of fn each time. If it returns anything other than 0, we break out and return that value. Kernel Hackers Manual October 2009 device_find_child 9 2.6.32-rc5 device_find_child device iterator for locating a particular device. struct device * device_find_child struct device * parent void * data int (*match) struct device *dev, void *data parent parent struct device data Data to pass to match function match Callback function to check device This is similar to the device_for_each_child function above, but it returns a reference to a device that is 'found' for later use, as determined by the match callback. The callback should return 0 if the device doesn't match and non-zero if it does. If the callback returns non-zero and a reference to the current device can be obtained, this function will return to the caller and not iterate over any more devices. Kernel Hackers Manual October 2009 __root_device_register 9 2.6.32-rc5 __root_device_register allocate and register a root device struct device * __root_device_register const char * name struct module * owner name root device name owner owner module of the root device, usually THIS_MODULE This function allocates a root device and registers it using device_register. In order to free the returned device, use root_device_unregister. Root devices are dummy devices which allow other devices to be grouped under /sys/devices. Use this function to allocate a root device and then use it as the parent of any device which should appear under /sys/devices/{name} The /sys/devices/{name} directory will also contain a 'module' symlink which points to the owner directory in sysfs. You probably want to use root_device_register. Kernel Hackers Manual October 2009 root_device_unregister 9 2.6.32-rc5 root_device_unregister unregister and free a root device void root_device_unregister struct device * dev dev device going away This function unregisters and cleans up a device that was created by root_device_register. Kernel Hackers Manual October 2009 device_create_vargs 9 2.6.32-rc5 device_create_vargs creates a device and registers it with sysfs struct device * device_create_vargs struct class * class struct device * parent dev_t devt void * drvdata const char * fmt va_list args class pointer to the struct class that this device should be registered to parent pointer to the parent struct device of this new device, if any devt the dev_t for the char device to be added drvdata the data to be added to the device for callbacks fmt string for the device's name args va_list for the device's name This function can be used by char device classes. A struct device will be created in sysfs, registered to the specified class. A dev file will be created, showing the dev_t for the device, if the dev_t is not 0,0. If a pointer to a parent struct device is passed in, the newly created struct device will be a child of that device in sysfs. The pointer to the struct device will be returned from the call. Any further sysfs files that might be required can be created using this pointer. the struct class passed to this function must have previously been created with a call to class_create. Kernel Hackers Manual October 2009 device_create 9 2.6.32-rc5 device_create creates a device and registers it with sysfs struct device * device_create struct class * class struct device * parent dev_t devt void * drvdata const char * fmt ... class pointer to the struct class that this device should be registered to parent pointer to the parent struct device of this new device, if any devt the dev_t for the char device to be added drvdata the data to be added to the device for callbacks fmt string for the device's name ... variable arguments This function can be used by char device classes. A struct device will be created in sysfs, registered to the specified class. A dev file will be created, showing the dev_t for the device, if the dev_t is not 0,0. If a pointer to a parent struct device is passed in, the newly created struct device will be a child of that device in sysfs. The pointer to the struct device will be returned from the call. Any further sysfs files that might be required can be created using this pointer. the struct class passed to this function must have previously been created with a call to class_create. Kernel Hackers Manual October 2009 device_destroy 9 2.6.32-rc5 device_destroy removes a device that was created with device_create void device_destroy struct class * class dev_t devt class pointer to the struct class that this device was registered with devt the dev_t of the device that was previously registered This call unregisters and cleans up a device that was created with a call to device_create. Kernel Hackers Manual October 2009 device_rename 9 2.6.32-rc5 device_rename renames a device int device_rename struct device * dev char * new_name dev the pointer to the struct device to be renamed new_name the new name of the device It is the responsibility of the caller to provide mutual exclusion between two different calls of device_rename on the same device to ensure that new_name is valid and won't conflict with other devices. Kernel Hackers Manual October 2009 device_move 9 2.6.32-rc5 device_move moves a device to a new parent int device_move struct device * dev struct device * new_parent enum dpm_order dpm_order dev the pointer to the struct device to be moved new_parent the new parent of the device (can by NULL) dpm_order how to reorder the dpm_list Kernel Hackers Manual October 2009 __class_create 9 2.6.32-rc5 __class_create create a struct class structure struct class * __class_create struct module * owner const char * name struct lock_class_key * key owner pointer to the module that is to own this struct class name pointer to a string for the name of this class. key the lock_class_key for this class; used by mutex lock debugging This is used to create a struct class pointer that can then be used in calls to device_create. Note, the pointer created here is to be destroyed when finished by making a call to class_destroy. Kernel Hackers Manual October 2009 class_destroy 9 2.6.32-rc5 class_destroy destroys a struct class structure void class_destroy struct class * cls cls pointer to the struct class that is to be destroyed Note, the pointer to be destroyed must have been created with a call to class_create. Kernel Hackers Manual October 2009 class_dev_iter_init 9 2.6.32-rc5 class_dev_iter_init initialize class device iterator void class_dev_iter_init struct class_dev_iter * iter struct class * class struct device * start const struct device_type * type iter class iterator to initialize class the class we wanna iterate over start the device to start iterating from, if any type device_type of the devices to iterate over, NULL for all Initialize class iterator iter such that it iterates over devices of class. If start is set, the list iteration will start there, otherwise if it is NULL, the iteration starts at the beginning of the list. Kernel Hackers Manual October 2009 class_dev_iter_next 9 2.6.32-rc5 class_dev_iter_next iterate to the next device struct device * class_dev_iter_next struct class_dev_iter * iter iter class iterator to proceed Proceed iter to the next device and return it. Returns NULL if iteration is complete. The returned device is referenced and won't be released till iterator is proceed to the next device or exited. The caller is free to do whatever it wants to do with the device including calling back into class code. Kernel Hackers Manual October 2009 class_dev_iter_exit 9 2.6.32-rc5 class_dev_iter_exit finish iteration void class_dev_iter_exit struct class_dev_iter * iter iter class iterator to finish Finish an iteration. Always call this function after iteration is complete whether the iteration ran till the end or not. Kernel Hackers Manual October 2009 class_for_each_device 9 2.6.32-rc5 class_for_each_device device iterator int class_for_each_device struct class * class struct device * start void * data int (*fn) struct device *, void * class the class we're iterating start the device to start with in the list, if any. data data for the callback fn function to be called for each device Iterate over class's list of devices, and call fn for each, passing it data. If start is set, the list iteration will start there, otherwise if it is NULL, the iteration starts at the beginning of the list. We check the return of fn each time. If it returns anything other than 0, we break out and return that value. fn is allowed to do anything including calling back into class code. There's no locking restriction. Kernel Hackers Manual October 2009 class_find_device 9 2.6.32-rc5 class_find_device device iterator for locating a particular device struct device * class_find_device struct class * class struct device * start void * data int (*match) struct device *, void * class the class we're iterating start Device to begin with data data for the match function match function to check device This is similar to the class_for_each_dev function above, but it returns a reference to a device that is 'found' for later use, as determined by the match callback. The callback should return 0 if the device doesn't match and non-zero if it does. If the callback returns non-zero, this function will return to the caller and not iterate over any more devices. Note, you will need to drop the reference with put_device after use. fn is allowed to do anything including calling back into class code. There's no locking restriction. Kernel Hackers Manual October 2009 class_compat_register 9 2.6.32-rc5 class_compat_register register a compatibility class struct class_compat * class_compat_register const char * name name the name of the class Compatibility class are meant as a temporary user-space compatibility workaround when converting a family of class devices to a bus devices. Kernel Hackers Manual October 2009 class_compat_unregister 9 2.6.32-rc5 class_compat_unregister unregister a compatibility class void class_compat_unregister struct class_compat * cls cls the class to unregister Kernel Hackers Manual October 2009 class_compat_create_link 9 2.6.32-rc5 class_compat_create_link create a compatibility class device link to a bus device int class_compat_create_link struct class_compat * cls struct device * dev struct device * device_link cls the compatibility class dev the target bus device device_link an optional device to which a device link should be created Kernel Hackers Manual October 2009 class_compat_remove_link 9 2.6.32-rc5 class_compat_remove_link remove a compatibility class device link to a bus device void class_compat_remove_link struct class_compat * cls struct device * dev struct device * device_link cls the compatibility class dev the target bus device device_link an optional device to which a device link was previously created Kernel Hackers Manual October 2009 request_firmware 9 2.6.32-rc5 request_firmware send firmware request and wait for it int request_firmware const struct firmware ** firmware_p const char * name struct device * device firmware_p pointer to firmware image name name of firmware file device device for which firmware is being loaded firmware_p will be used to return a firmware image by the name of name for device device. Should be called from user context where sleeping is allowed. name will be used as $FIRMWARE in the uevent environment and should be distinctive enough not to be confused with any other firmware image for this or any other device. Kernel Hackers Manual October 2009 release_firmware 9 2.6.32-rc5 release_firmware release the resource associated with a firmware image void release_firmware const struct firmware * fw fw firmware resource to release Kernel Hackers Manual October 2009 request_firmware_nowait 9 2.6.32-rc5 request_firmware_nowait int request_firmware_nowait struct module * module int uevent const char * name struct device * device void * context void (*cont) const struct firmware *fw, void *context module module requesting the firmware uevent sends uevent to copy the firmware image if this flag is non-zero else the firmware copy must be done manually. name name of firmware file device device for which firmware is being loaded context will be passed over to cont, and fw may be NULL if firmware request fails. cont function will be called asynchronously when the firmware request is over. Asynchronous variant of request_firmware for user contexts where it is not possible to sleep for long time. It can't be called in atomic contexts. Kernel Hackers Manual October 2009 transport_class_register 9 2.6.32-rc5 transport_class_register register an initial transport class int transport_class_register struct transport_class * tclass tclass a pointer to the transport class structure to be initialised The transport class contains an embedded class which is used to identify it. The caller should initialise this structure with zeros and then generic class must have been initialised with the actual transport class unique name. There's a macro DECLARE_TRANSPORT_CLASS to do this (declared classes still must be registered). Returns 0 on success or error on failure. Kernel Hackers Manual October 2009 transport_class_unregister 9 2.6.32-rc5 transport_class_unregister unregister a previously registered class void transport_class_unregister struct transport_class * tclass tclass The transport class to unregister Must be called prior to deallocating the memory for the transport class. Kernel Hackers Manual October 2009 anon_transport_class_register 9 2.6.32-rc5 anon_transport_class_register register an anonymous class int anon_transport_class_register struct anon_transport_class * atc atc The anon transport class to register The anonymous transport class contains both a transport class and a container. The idea of an anonymous class is that it never actually has any device attributes associated with it (and thus saves on container storage). So it can only be used for triggering events. Use prezero and then use DECLARE_ANON_TRANSPORT_CLASS to initialise the anon transport class storage. Kernel Hackers Manual October 2009 anon_transport_class_unregister 9 2.6.32-rc5 anon_transport_class_unregister unregister an anon class void anon_transport_class_unregister struct anon_transport_class * atc atc Pointer to the anon transport class to unregister Must be called prior to deallocating the memory for the anon transport class. Kernel Hackers Manual October 2009 transport_setup_device 9 2.6.32-rc5 transport_setup_device declare a new dev for transport class association but don't make it visible yet. void transport_setup_device struct device * dev dev the generic device representing the entity being added Usually, dev represents some component in the HBA system (either the HBA itself or a device remote across the HBA bus). This routine is simply a trigger point to see if any set of transport classes wishes to associate with the added device. This allocates storage for the class device and initialises it, but does not yet add it to the system or add attributes to it (you do this with transport_add_device). If you have no need for a separate setup and add operations, use transport_register_device (see transport_class.h). Kernel Hackers Manual October 2009 transport_add_device 9 2.6.32-rc5 transport_add_device declare a new dev for transport class association void transport_add_device struct device * dev dev the generic device representing the entity being added Usually, dev represents some component in the HBA system (either the HBA itself or a device remote across the HBA bus). This routine is simply a trigger point used to add the device to the system and register attributes for it. Kernel Hackers Manual October 2009 transport_configure_device 9 2.6.32-rc5 transport_configure_device configure an already set up device void transport_configure_device struct device * dev dev generic device representing device to be configured The idea of configure is simply to provide a point within the setup process to allow the transport class to extract information from a device after it has been setup. This is used in SCSI because we have to have a setup device to begin using the HBA, but after we send the initial inquiry, we use configure to extract the device parameters. The device need not have been added to be configured. Kernel Hackers Manual October 2009 transport_remove_device 9 2.6.32-rc5 transport_remove_device remove the visibility of a device void transport_remove_device struct device * dev dev generic device to remove This call removes the visibility of the device (to the user from sysfs), but does not destroy it. To eliminate a device entirely you must also call transport_destroy_device. If you don't need to do remove and destroy as separate operations, use transport_unregister_device (see transport_class.h) which will perform both calls for you. Kernel Hackers Manual October 2009 transport_destroy_device 9 2.6.32-rc5 transport_destroy_device destroy a removed device void transport_destroy_device struct device * dev dev device to eliminate from the transport class. This call triggers the elimination of storage associated with the transport classdev. Note: all it really does is relinquish a reference to the classdev. The memory will not be freed until the last reference goes to zero. Note also that the classdev retains a reference count on dev, so dev too will remain for as long as the transport class device remains around. Kernel Hackers Manual October 2009 sysdev_driver_register 9 2.6.32-rc5 sysdev_driver_register Register auxillary driver int sysdev_driver_register struct sysdev_class * cls struct sysdev_driver * drv cls Device class driver belongs to. drv Driver. drv is inserted into cls->drivers to be called on each operation on devices of that class. The refcount of cls is incremented. Kernel Hackers Manual October 2009 sysdev_driver_unregister 9 2.6.32-rc5 sysdev_driver_unregister Remove an auxillary driver. void sysdev_driver_unregister struct sysdev_class * cls struct sysdev_driver * drv cls Class driver belongs to. drv Driver. Kernel Hackers Manual October 2009 sysdev_register 9 2.6.32-rc5 sysdev_register add a system device to the tree int sysdev_register struct sys_device * sysdev sysdev device in question Kernel Hackers Manual October 2009 sysdev_suspend 9 2.6.32-rc5 sysdev_suspend Suspend all system devices. int sysdev_suspend pm_message_t state state Power state to enter. We perform an almost identical operation as sysdev_shutdown above, though calling ->suspend instead. Interrupts are disabled when this called. Devices are responsible for both saving state and quiescing or powering down the device. This is only called by the device PM core, so we let them handle all synchronization. Kernel Hackers Manual October 2009 sysdev_resume 9 2.6.32-rc5 sysdev_resume Bring system devices back to life. int sysdev_resume void void no arguments Similar to sysdev_suspend, but we iterate the list forwards to guarantee that parent devices are resumed before their children. Interrupts are disabled when called. Kernel Hackers Manual October 2009 platform_get_resource 9 2.6.32-rc5 platform_get_resource get a resource for a device struct resource * platform_get_resource struct platform_device * dev unsigned int type unsigned int num dev platform device type resource type num resource index Kernel Hackers Manual October 2009 platform_get_irq 9 2.6.32-rc5 platform_get_irq get an IRQ for a device int platform_get_irq struct platform_device * dev unsigned int num dev platform device num IRQ number index Kernel Hackers Manual October 2009 platform_get_resource_byname 9 2.6.32-rc5 platform_get_resource_byname get a resource for a device by name struct resource * platform_get_resource_byname struct platform_device * dev unsigned int type const char * name dev platform device type resource type name resource name Kernel Hackers Manual October 2009 platform_get_irq_byname 9 2.6.32-rc5 platform_get_irq_byname get an IRQ for a device int platform_get_irq_byname struct platform_device * dev const char * name dev platform device name IRQ name Kernel Hackers Manual October 2009 platform_add_devices 9 2.6.32-rc5 platform_add_devices add a numbers of platform devices int platform_add_devices struct platform_device ** devs int num devs array of platform devices to add num number of platform devices in array Kernel Hackers Manual October 2009 platform_device_put 9 2.6.32-rc5 platform_device_put void platform_device_put struct platform_device * pdev pdev platform device to free Free all memory associated with a platform device. This function must _only_ be externally called in error cases. All other usage is a bug. Kernel Hackers Manual October 2009 platform_device_alloc 9 2.6.32-rc5 platform_device_alloc struct platform_device * platform_device_alloc const char * name int id name base name of the device we're adding id instance id Create a platform device object which can have other objects attached to it, and which will have attached objects freed when it is released. Kernel Hackers Manual October 2009 platform_device_add_resources 9 2.6.32-rc5 platform_device_add_resources int platform_device_add_resources struct platform_device * pdev struct resource * res unsigned int num pdev platform device allocated by platform_device_alloc to add resources to res set of resources that needs to be allocated for the device num number of resources Add a copy of the resources to the platform device. The memory associated with the resources will be freed when the platform device is released. Kernel Hackers Manual October 2009 platform_device_add_data 9 2.6.32-rc5 platform_device_add_data int platform_device_add_data struct platform_device * pdev const void * data size_t size pdev platform device allocated by platform_device_alloc to add resources to data platform specific data for this platform device size size of platform specific data Add a copy of platform specific data to the platform device's platform_data pointer. The memory associated with the platform data will be freed when the platform device is released. Kernel Hackers Manual October 2009 platform_device_add 9 2.6.32-rc5 platform_device_add add a platform device to device hierarchy int platform_device_add struct platform_device * pdev pdev platform device we're adding This is part 2 of platform_device_register, though may be called separately _iff_ pdev was allocated by platform_device_alloc. Kernel Hackers Manual October 2009 platform_device_del 9 2.6.32-rc5 platform_device_del remove a platform-level device void platform_device_del struct platform_device * pdev pdev platform device we're removing Note that this function will also release all memory- and port-based resources owned by the device (dev->resource). This function must _only_ be externally called in error cases. All other usage is a bug. Kernel Hackers Manual October 2009 platform_device_register 9 2.6.32-rc5 platform_device_register add a platform-level device int platform_device_register struct platform_device * pdev pdev platform device we're adding Kernel Hackers Manual October 2009 platform_device_unregister 9 2.6.32-rc5 platform_device_unregister unregister a platform-level device void platform_device_unregister struct platform_device * pdev pdev platform device we're unregistering Unregistration is done in 2 steps. First we release all resources and remove it from the subsystem, then we drop reference count by calling platform_device_put. Kernel Hackers Manual October 2009 platform_device_register_simple 9 2.6.32-rc5 platform_device_register_simple struct platform_device * platform_device_register_simple const char * name int id struct resource * res unsigned int num name base name of the device we're adding id instance id res set of resources that needs to be allocated for the device num number of resources This function creates a simple platform device that requires minimal resource and memory management. Canned release function freeing memory allocated for the device allows drivers using such devices to be unloaded without waiting for the last reference to the device to be dropped. This interface is primarily intended for use with legacy drivers which probe hardware directly. Because such drivers create sysfs device nodes themselves, rather than letting system infrastructure handle such device enumeration tasks, they don't fully conform to the Linux driver model. In particular, when such drivers are built as modules, they can't be hotplugged. Kernel Hackers Manual October 2009 platform_driver_register 9 2.6.32-rc5 platform_driver_register int platform_driver_register struct platform_driver * drv drv platform driver structure Kernel Hackers Manual October 2009 platform_driver_unregister 9 2.6.32-rc5 platform_driver_unregister void platform_driver_unregister struct platform_driver * drv drv platform driver structure Kernel Hackers Manual October 2009 platform_driver_probe 9 2.6.32-rc5 platform_driver_probe register driver for non-hotpluggable device int __init_or_module platform_driver_probe struct platform_driver * drv int (*probe) struct platform_device * drv platform driver structure probe the driver probe routine, probably from an __init section Use this instead of platform_driver_register when you know the device is not hotpluggable and has already been registered, and you want to remove its run-once probe infrastructure from memory after the driver has bound to the device. One typical use for this would be with drivers for controllers integrated into system-on-chip processors, where the controller devices have been configured as part of board setup. Returns zero if the driver registered and bound to a device, else returns a negative error code and with the driver not registered. Kernel Hackers Manual October 2009 bus_for_each_dev 9 2.6.32-rc5 bus_for_each_dev device iterator. int bus_for_each_dev struct bus_type * bus struct device * start void * data int (*fn) struct device *, void * bus bus type. start device to start iterating from. data data for the callback. fn function to be called for each device. Iterate over bus's list of devices, and call fn for each, passing it data. If start is not NULL, we use that device to begin iterating from. We check the return of fn each time. If it returns anything other than 0, we break out and return that value. The device that returns a non-zero value is not retained in any way, nor is its refcount incremented. If the caller needs to retain this data, it should do so, and increment the reference count in the supplied callback. Kernel Hackers Manual October 2009 bus_find_device 9 2.6.32-rc5 bus_find_device device iterator for locating a particular device. struct device * bus_find_device struct bus_type * bus struct device * start void * data int (*match) struct device *dev, void *data bus bus type start Device to begin with data Data to pass to match function match Callback function to check device This is similar to the bus_for_each_dev function above, but it returns a reference to a device that is 'found' for later use, as determined by the match callback. The callback should return 0 if the device doesn't match and non-zero if it does. If the callback returns non-zero, this function will return to the caller and not iterate over any more devices. Kernel Hackers Manual October 2009 bus_find_device_by_name 9 2.6.32-rc5 bus_find_device_by_name device iterator for locating a particular device of a specific name struct device * bus_find_device_by_name struct bus_type * bus struct device * start const char * name bus bus type start Device to begin with name name of the device to match This is similar to the bus_find_device function above, but it handles searching by a name automatically, no need to write another strcmp matching function. Kernel Hackers Manual October 2009 bus_for_each_drv 9 2.6.32-rc5 bus_for_each_drv driver iterator int bus_for_each_drv struct bus_type * bus struct device_driver * start void * data int (*fn) struct device_driver *, void * bus bus we're dealing with. start driver to start iterating on. data data to pass to the callback. fn function to call for each driver. This is nearly identical to the device iterator above. We iterate over each driver that belongs to bus, and call fn for each. If fn returns anything but 0, we break out and return it. If start is not NULL, we use it as the head of the list. we don't return the driver that returns a non-zero value, nor do we leave the reference count incremented for that driver. If the caller needs to know that info, it must set it in the callback. It must also be sure to increment the refcount so it doesn't disappear before returning to the caller. Kernel Hackers Manual October 2009 bus_rescan_devices 9 2.6.32-rc5 bus_rescan_devices rescan devices on the bus for possible drivers int bus_rescan_devices struct bus_type * bus bus the bus to scan. This function will look for devices on the bus with no driver attached and rescan it against existing drivers to see if it matches any by calling device_attach for the unbound devices. Kernel Hackers Manual October 2009 device_reprobe 9 2.6.32-rc5 device_reprobe remove driver for a device and probe for a new driver int device_reprobe struct device * dev dev the device to reprobe This function detaches the attached driver (if any) for the given device and restarts the driver probing process. It is intended to use if probing criteria changed during a devices lifetime and driver attachment should change accordingly. Kernel Hackers Manual October 2009 bus_register 9 2.6.32-rc5 bus_register register a bus with the system. int bus_register struct bus_type * bus bus bus. Once we have that, we registered the bus with the kobject infrastructure, then register the children subsystems it has: the devices and drivers that belong to the bus. Kernel Hackers Manual October 2009 bus_unregister 9 2.6.32-rc5 bus_unregister remove a bus from the system void bus_unregister struct bus_type * bus bus bus. Unregister the child subsystems and the bus itself. Finally, we call bus_put to release the refcount Kernel Hackers Manual October 2009 dpm_resume_noirq 9 2.6.32-rc5 dpm_resume_noirq Execute early resume callbacks for non-sysdev devices. void dpm_resume_noirq pm_message_t state state PM transition of the system being carried out. Call the noirq resume handlers for all devices marked as DPM_OFF_IRQ and enable device drivers to receive interrupts. Kernel Hackers Manual October 2009 dpm_resume_end 9 2.6.32-rc5 dpm_resume_end Execute resume callbacks and complete system transition. void dpm_resume_end pm_message_t state state PM transition of the system being carried out. Execute resume callbacks for all devices and complete the PM transition of the system. Kernel Hackers Manual October 2009 dpm_suspend_noirq 9 2.6.32-rc5 dpm_suspend_noirq Execute late suspend callbacks for non-sysdev devices. int dpm_suspend_noirq pm_message_t state state PM transition of the system being carried out. Prevent device drivers from receiving interrupts and call the noirq suspend handlers for all non-sysdev devices. Kernel Hackers Manual October 2009 dpm_suspend_start 9 2.6.32-rc5 dpm_suspend_start Prepare devices for PM transition and suspend them. int dpm_suspend_start pm_message_t state state PM transition of the system being carried out. Prepare all non-sysdev devices for system PM transition and execute suspend callbacks for them. Kernel Hackers Manual October 2009 acpi_bus_register_driver 9 2.6.32-rc5 acpi_bus_register_driver register a driver with the ACPI bus int acpi_bus_register_driver struct acpi_driver * driver driver driver being registered Registers a driver with the ACPI bus. Searches the namespace for all devices that match the driver's criteria and binds. Returns zero for success or a negative error status for failure. Kernel Hackers Manual October 2009 acpi_bus_unregister_driver 9 2.6.32-rc5 acpi_bus_unregister_driver unregisters a driver with the APIC bus void acpi_bus_unregister_driver struct acpi_driver * driver driver driver to unregister Unregisters a driver with the ACPI bus. Searches the namespace for all devices that match the driver's criteria and unbinds. Kernel Hackers Manual October 2009 acpi_bus_driver_init 9 2.6.32-rc5 acpi_bus_driver_init add a device to a driver int acpi_bus_driver_init struct acpi_device * device struct acpi_driver * driver device the device to add and initialize driver driver for the device Used to initialize a device via its device driver. Called whenever a driver is bound to a device. Invokes the driver's add ops. Kernel Hackers Manual October 2009 pnp_register_protocol 9 2.6.32-rc5 pnp_register_protocol adds a pnp protocol to the pnp layer int pnp_register_protocol struct pnp_protocol * protocol protocol pointer to the corresponding pnp_protocol structure ISAPNP, PNPBIOS, etc Kernel Hackers Manual October 2009 pnp_unregister_protocol 9 2.6.32-rc5 pnp_unregister_protocol removes a pnp protocol from the pnp layer void pnp_unregister_protocol struct pnp_protocol * protocol protocol pointer to the corresponding pnp_protocol structure Kernel Hackers Manual October 2009 pnp_request_card_device 9 2.6.32-rc5 pnp_request_card_device Searches for a PnP device under the specified card struct pnp_dev * pnp_request_card_device struct pnp_card_link * clink const char * id struct pnp_dev * from clink pointer to the card link, cannot be NULL id pointer to a PnP ID structure that explains the rules for finding the device from Starting place to search from. If NULL it will start from the begining. Kernel Hackers Manual October 2009 pnp_release_card_device 9 2.6.32-rc5 pnp_release_card_device call this when the driver no longer needs the device void pnp_release_card_device struct pnp_dev * dev dev pointer to the PnP device stucture Kernel Hackers Manual October 2009 pnp_register_card_driver 9 2.6.32-rc5 pnp_register_card_driver registers a PnP card driver with the PnP Layer int pnp_register_card_driver struct pnp_card_driver * drv drv pointer to the driver to register Kernel Hackers Manual October 2009 pnp_unregister_card_driver 9 2.6.32-rc5 pnp_unregister_card_driver unregisters a PnP card driver from the PnP Layer void pnp_unregister_card_driver struct pnp_card_driver * drv drv pointer to the driver to unregister Kernel Hackers Manual October 2009 pnp_add_id 9 2.6.32-rc5 pnp_add_id adds an EISA id to the specified device struct pnp_id * pnp_add_id struct pnp_dev * dev char * id dev pointer to the desired device id pointer to an EISA id string Kernel Hackers Manual October 2009 pnp_start_dev 9 2.6.32-rc5 pnp_start_dev low-level start of the PnP device int pnp_start_dev struct pnp_dev * dev dev pointer to the desired device assumes that resources have already been allocated Kernel Hackers Manual October 2009 pnp_stop_dev 9 2.6.32-rc5 pnp_stop_dev low-level disable of the PnP device int pnp_stop_dev struct pnp_dev * dev dev pointer to the desired device does not free resources Kernel Hackers Manual October 2009 pnp_activate_dev 9 2.6.32-rc5 pnp_activate_dev activates a PnP device for use int pnp_activate_dev struct pnp_dev * dev dev pointer to the desired device does not validate or set resources so be careful. Kernel Hackers Manual October 2009 pnp_disable_dev 9 2.6.32-rc5 pnp_disable_dev disables device int pnp_disable_dev struct pnp_dev * dev dev pointer to the desired device inform the correct pnp protocol so that resources can be used by other devices Kernel Hackers Manual October 2009 pnp_is_active 9 2.6.32-rc5 pnp_is_active Determines if a device is active based on its current resources int pnp_is_active struct pnp_dev * dev dev pointer to the desired PnP device Kernel Hackers Manual October 2009 uio_event_notify 9 2.6.32-rc5 uio_event_notify trigger an interrupt event void uio_event_notify struct uio_info * info info UIO device capabilities Kernel Hackers Manual October 2009 __uio_register_device 9 2.6.32-rc5 __uio_register_device register a new userspace IO device int __uio_register_device struct module * owner struct device * parent struct uio_info * info owner module that creates the new device parent parent device info UIO device capabilities returns zero on success or a negative error code. Kernel Hackers Manual October 2009 uio_unregister_device 9 2.6.32-rc5 uio_unregister_device unregister a industrial IO device void uio_unregister_device struct uio_info * info info UIO device capabilities Kernel Hackers Manual October 2009 struct uio_mem 9 2.6.32-rc5 struct uio_mem description of a UIO memory region struct uio_mem { const char * name; unsigned long addr; unsigned long size; int memtype; void __iomem * internal_addr; struct uio_map * map; }; name name of the memory region for identification addr address of the device's memory size size of IO memtype type of memory addr points to internal_addr ioremap-ped version of addr, for driver internal use map for use by the UIO core only. Kernel Hackers Manual October 2009 struct uio_port 9 2.6.32-rc5 struct uio_port description of a UIO port region struct uio_port { const char * name; unsigned long start; unsigned long size; int porttype; struct uio_portio * portio; }; name name of the port region for identification start start of port region size size of port region porttype type of port (see UIO_PORT_* below) portio for use by the UIO core only. Kernel Hackers Manual October 2009 struct uio_info 9 2.6.32-rc5 struct uio_info UIO device capabilities struct uio_info { struct uio_device * uio_dev; const char * name; const char * version; struct uio_mem mem[MAX_UIO_MAPS]; struct uio_port port[MAX_UIO_PORT_REGIONS]; long irq; unsigned long irq_flags; void * priv; irqreturn_t (* handler) (int irq, struct uio_info *dev_info); int (* mmap) (struct uio_info *info, struct vm_area_struct *vma); int (* open) (struct uio_info *info, struct inode *inode); int (* release) (struct uio_info *info, struct inode *inode); int (* irqcontrol) (struct uio_info *info, s32 irq_on); }; uio_dev the UIO device this info belongs to name device name version device driver version mem[MAX_UIO_MAPS] list of mappable memory regions, size==0 for end of list port[MAX_UIO_PORT_REGIONS] list of port regions, size==0 for end of list irq interrupt number or UIO_IRQ_CUSTOM irq_flags flags for request_irq priv optional private data handler the device's irq handler mmap mmap operation for this uio device open open operation for this uio device release release operation for this uio device irqcontrol disable/enable irqs when 0/1 is written to /dev/uioX Kernel Hackers Manual October 2009 parport_yield 9 2.6.32-rc5 parport_yield relinquish a parallel port temporarily int parport_yield struct pardevice * dev dev a device on the parallel port This function relinquishes the port if it would be helpful to other drivers to do so. Afterwards it tries to reclaim the port using parport_claim, and the return value is the same as for parport_claim. If it fails, the port is left unclaimed and it is the driver's responsibility to reclaim the port. The parport_yield and parport_yield_blocking functions are for marking points in the driver at which other drivers may claim the port and use their devices. Yielding the port is similar to releasing it and reclaiming it, but is more efficient because no action is taken if there are no other devices needing the port. In fact, nothing is done even if there are other devices waiting but the current device is still within its timeslice. The default timeslice is half a second, but it can be adjusted via the /proc interface. Kernel Hackers Manual October 2009 parport_yield_blocking 9 2.6.32-rc5 parport_yield_blocking relinquish a parallel port temporarily int parport_yield_blocking struct pardevice * dev dev a device on the parallel port This function relinquishes the port if it would be helpful to other drivers to do so. Afterwards it tries to reclaim the port using parport_claim_or_block, and the return value is the same as for parport_claim_or_block. Kernel Hackers Manual October 2009 parport_wait_event 9 2.6.32-rc5 parport_wait_event wait for an event on a parallel port int parport_wait_event struct parport * port signed long timeout port port to wait on timeout time to wait (in jiffies) This function waits for up to timeout jiffies for an interrupt to occur on a parallel port. If the port timeout is set to zero, it returns immediately. If an interrupt occurs before the timeout period elapses, this function returns zero immediately. If it times out, it returns one. An error code less than zero indicates an error (most likely a pending signal), and the calling code should finish what it's doing as soon as it can. Kernel Hackers Manual October 2009 parport_wait_peripheral 9 2.6.32-rc5 parport_wait_peripheral wait for status lines to change in 35ms int parport_wait_peripheral struct parport * port unsigned char mask unsigned char result port port to watch mask status lines to watch result desired values of chosen status lines This function waits until the masked status lines have the desired values, or until 35ms have elapsed (see IEEE 1284-1994 page 24 to 25 for why this value in particular is hardcoded). The mask and result parameters are bitmasks, with the bits defined by the constants in parport.h: PARPORT_STATUS_BUSY, and so on. The port is polled quickly to start off with, in anticipation of a fast response from the peripheral. This fast polling time is configurable (using /proc), and defaults to 500usec. If the timeout for this port (see parport_set_timeout) is zero, the fast polling time is 35ms, and this function does not call schedule. If the timeout for this port is non-zero, after the fast polling fails it uses parport_wait_event to wait for up to 10ms, waking up if an interrupt occurs. Kernel Hackers Manual October 2009 parport_negotiate 9 2.6.32-rc5 parport_negotiate negotiate an IEEE 1284 mode int parport_negotiate struct parport * port int mode port port to use mode mode to negotiate to Use this to negotiate to a particular IEEE 1284 transfer mode. The mode parameter should be one of the constants in parport.h starting IEEE1284_MODE_xxx. The return value is 0 if the peripheral has accepted the negotiation to the mode specified, -1 if the peripheral is not IEEE 1284 compliant (or not present), or 1 if the peripheral has rejected the negotiation. Kernel Hackers Manual October 2009 parport_write 9 2.6.32-rc5 parport_write write a block of data to a parallel port ssize_t parport_write struct parport * port const void * buffer size_t len port port to write to buffer data buffer (in kernel space) len number of bytes of data to transfer This will write up to len bytes of buffer to the port specified, using the IEEE 1284 transfer mode most recently negotiated to (using parport_negotiate), as long as that mode supports forward transfers (host to peripheral). It is the caller's responsibility to ensure that the first len bytes of buffer are valid. This function returns the number of bytes transferred (if zero or positive), or else an error code. Kernel Hackers Manual October 2009 parport_read 9 2.6.32-rc5 parport_read read a block of data from a parallel port ssize_t parport_read struct parport * port void * buffer size_t len port port to read from buffer data buffer (in kernel space) len number of bytes of data to transfer This will read up to len bytes of buffer to the port specified, using the IEEE 1284 transfer mode most recently negotiated to (using parport_negotiate), as long as that mode supports reverse transfers (peripheral to host). It is the caller's responsibility to ensure that the first len bytes of buffer are available to write to. This function returns the number of bytes transferred (if zero or positive), or else an error code. Kernel Hackers Manual October 2009 parport_set_timeout 9 2.6.32-rc5 parport_set_timeout set the inactivity timeout for a device long parport_set_timeout struct pardevice * dev long inactivity dev device on a port inactivity inactivity timeout (in jiffies) This sets the inactivity timeout for a particular device on a port. This affects functions like parport_wait_peripheral. The special value 0 means not to call schedule while dealing with this device. The return value is the previous inactivity timeout. Any callers of parport_wait_event for this device are woken up. Kernel Hackers Manual October 2009 parport_register_driver 9 2.6.32-rc5 parport_register_driver register a parallel port device driver int parport_register_driver struct parport_driver * drv drv structure describing the driver This can be called by a parallel port device driver in order to receive notifications about ports being found in the system, as well as ports no longer available. The drv structure is allocated by the caller and must not be deallocated until after calling parport_unregister_driver. The driver's attach function may block. The port that attach is given will be valid for the duration of the callback, but if the driver wants to take a copy of the pointer it must call parport_get_port to do so. Calling parport_register_device on that port will do this for you. The driver's detach function may block. The port that detach is given will be valid for the duration of the callback, but if the driver wants to take a copy of the pointer it must call parport_get_port to do so. Returns 0 on success. Currently it always succeeds. Kernel Hackers Manual October 2009 parport_unregister_driver 9 2.6.32-rc5 parport_unregister_driver deregister a parallel port device driver void parport_unregister_driver struct parport_driver * drv drv structure describing the driver that was given to parport_register_driver This should be called by a parallel port device driver that has registered itself using parport_register_driver when it is about to be unloaded. When it returns, the driver's attach routine will no longer be called, and for each port that attach was called for, the detach routine will have been called. All the driver's attach and detach calls are guaranteed to have finished by the time this function returns. Kernel Hackers Manual October 2009 parport_get_port 9 2.6.32-rc5 parport_get_port increment a port's reference count struct parport * parport_get_port struct parport * port port the port This ensures that a struct parport pointer remains valid until the matching parport_put_port call. Kernel Hackers Manual October 2009 parport_put_port 9 2.6.32-rc5 parport_put_port decrement a port's reference count void parport_put_port struct parport * port port the port This should be called once for each call to parport_get_port, once the port is no longer needed. Kernel Hackers Manual October 2009 parport_register_port 9 2.6.32-rc5 parport_register_port register a parallel port struct parport * parport_register_port unsigned long base int irq int dma struct parport_operations * ops base base I/O address irq IRQ line dma DMA channel ops pointer to the port driver's port operations structure When a parallel port (lowlevel) driver finds a port that should be made available to parallel port device drivers, it should call parport_register_port. The base, irq, and dma parameters are for the convenience of port drivers, and for ports where they aren't meaningful needn't be set to anything special. They can be altered afterwards by adjusting the relevant members of the parport structure that is returned and represents the port. They should not be tampered with after calling parport_announce_port, however. If there are parallel port device drivers in the system that have registered themselves using parport_register_driver, they are not told about the port at this time; that is done by parport_announce_port. The ops structure is allocated by the caller, and must not be deallocated before calling parport_remove_port. If there is no memory to allocate a new parport structure, this function will return NULL. Kernel Hackers Manual October 2009 parport_announce_port 9 2.6.32-rc5 parport_announce_port tell device drivers about a parallel port void parport_announce_port struct parport * port port parallel port to announce After a port driver has registered a parallel port with parport_register_port, and performed any necessary initialisation or adjustments, it should call parport_announce_port in order to notify all device drivers that have called parport_register_driver. Their attach functions will be called, with port as the parameter. Kernel Hackers Manual October 2009 parport_remove_port 9 2.6.32-rc5 parport_remove_port deregister a parallel port void parport_remove_port struct parport * port port parallel port to deregister When a parallel port driver is forcibly unloaded, or a parallel port becomes inaccessible, the port driver must call this function in order to deal with device drivers that still want to use it. The parport structure associated with the port has its operations structure replaced with one containing 'null' operations that return errors or just don't do anything. Any drivers that have registered themselves using parport_register_driver are notified that the port is no longer accessible by having their detach routines called with port as the parameter. Kernel Hackers Manual October 2009 parport_register_device 9 2.6.32-rc5 parport_register_device register a device on a parallel port struct pardevice * parport_register_device struct parport * port const char * name int (*pf) void * void (*kf) void * void (*irq_func) void * int flags void * handle port port to which the device is attached name a name to refer to the device pf preemption callback kf kick callback (wake-up) irq_func interrupt handler flags registration flags handle data for callback functions This function, called by parallel port device drivers, declares that a device is connected to a port, and tells the system all it needs to know. The name is allocated by the caller and must not be deallocated until the caller calls parport_unregister_device for that device. The preemption callback function, pf, is called when this device driver has claimed access to the port but another device driver wants to use it. It is given handle as its parameter, and should return zero if it is willing for the system to release the port to another driver on its behalf. If it wants to keep control of the port it should return non-zero, and no action will be taken. It is good manners for the driver to try to release the port at the earliest opportunity after its preemption callback rejects a preemption attempt. Note that if a preemption callback is happy for preemption to go ahead, there is no need to release the port; it is done automatically. This function may not block, as it may be called from interrupt context. If the device driver does not support preemption, pf can be NULL. The wake-up (kick) callback function, kf, is called when the port is available to be claimed for exclusive access; that is, parport_claim is guaranteed to succeed when called from inside the wake-up callback function. If the driver wants to claim the port it should do so; otherwise, it need not take any action. This function may not block, as it may be called from interrupt context. If the device driver does not want to be explicitly invited to claim the port in this way, kf can be NULL. The interrupt handler, irq_func, is called when an interrupt arrives from the parallel port. Note that if a device driver wants to use interrupts it should use parport_enable_irq, and can also check the irq member of the parport structure representing the port. The parallel port (lowlevel) driver is the one that has called request_irq and whose interrupt handler is called first. This handler does whatever needs to be done to the hardware to acknowledge the interrupt (for PC-style ports there is nothing special to be done). It then tells the IEEE 1284 code about the interrupt, which may involve reacting to an IEEE 1284 event depending on the current IEEE 1284 phase. After this, it calls irq_func. Needless to say, irq_func will be called from interrupt context, and may not block. The PARPORT_DEV_EXCL flag is for preventing port sharing, and so should only be used when sharing the port with other device drivers is impossible and would lead to incorrect behaviour. Use it sparingly! Normally, flags will be zero. This function returns a pointer to a structure that represents the device on the port, or NULL if there is not enough memory to allocate space for that structure. Kernel Hackers Manual October 2009 parport_unregister_device 9 2.6.32-rc5 parport_unregister_device deregister a device on a parallel port void parport_unregister_device struct pardevice * dev dev pointer to structure representing device This undoes the effect of parport_register_device. Kernel Hackers Manual October 2009 parport_find_number 9 2.6.32-rc5 parport_find_number find a parallel port by number struct parport * parport_find_number int number number parallel port number This returns the parallel port with the specified number, or NULL if there is none. There is an implicit parport_get_port done already; to throw away the reference to the port that parport_find_number gives you, use parport_put_port. Kernel Hackers Manual October 2009 parport_find_base 9 2.6.32-rc5 parport_find_base find a parallel port by base address struct parport * parport_find_base unsigned long base base base I/O address This returns the parallel port with the specified base address, or NULL if there is none. There is an implicit parport_get_port done already; to throw away the reference to the port that parport_find_base gives you, use parport_put_port. Kernel Hackers Manual October 2009 parport_claim 9 2.6.32-rc5 parport_claim claim access to a parallel port device int parport_claim struct pardevice * dev dev pointer to structure representing a device on the port This function will not block and so can be used from interrupt context. If parport_claim succeeds in claiming access to the port it returns zero and the port is available to use. It may fail (returning non-zero) if the port is in use by another driver and that driver is not willing to relinquish control of the port. Kernel Hackers Manual October 2009 parport_claim_or_block 9 2.6.32-rc5 parport_claim_or_block claim access to a parallel port device int parport_claim_or_block struct pardevice * dev dev pointer to structure representing a device on the port This behaves like parport_claim, but will block if necessary to wait for the port to be free. A return value of 1 indicates that it slept; 0 means that it succeeded without needing to sleep. A negative error code indicates failure. Kernel Hackers Manual October 2009 parport_release 9 2.6.32-rc5 parport_release give up access to a parallel port device void parport_release struct pardevice * dev dev pointer to structure representing parallel port device This function cannot fail, but it should not be called without the port claimed. Similarly, if the port is already claimed you should not try claiming it again. Kernel Hackers Manual October 2009 parport_open 9 2.6.32-rc5 parport_open find a device by canonical device number struct pardevice * parport_open int devnum const char * name devnum canonical device number name name to associate with the device This function is similar to parport_register_device, except that it locates a device by its number rather than by the port it is attached to. All parameters except for devnum are the same as for parport_register_device. The return value is the same as for parport_register_device. Kernel Hackers Manual October 2009 parport_close 9 2.6.32-rc5 parport_close close a device opened with parport_open void parport_close struct pardevice * dev dev device to close This is to parport_open as parport_unregister_device is to parport_register_device. Kernel Hackers Manual October 2009 mpt_register 9 2.6.32-rc5 mpt_register Register protocol-specific main callback handler. u8 mpt_register MPT_CALLBACK cbfunc MPT_DRIVER_CLASS dclass cbfunc callback function pointer dclass Protocol driver's class (MPT_DRIVER_CLASS enum value) This routine is called by a protocol-specific driver (SCSI host, LAN, SCSI target) to register its reply callback routine. Each protocol-specific driver must do this before it will be able to use any IOC resources, such as obtaining request frames. The SCSI protocol driver currently calls this routine thrice in order to register separate callbacks; one for normal SCSI IO; one for MptScsiTaskMgmt requests; one for Scan/DV requests. Returns u8 valued handle in the range (and S.O.D. order) {N,...,7,6,5,...,1} if successful. A return value of MPT_MAX_PROTOCOL_DRIVERS (including zero!) should be considered an error by the caller. Kernel Hackers Manual October 2009 mpt_deregister 9 2.6.32-rc5 mpt_deregister Deregister a protocol drivers resources. void mpt_deregister u8 cb_idx cb_idx previously registered callback handle Each protocol-specific driver should call this routine when its module is unloaded. Kernel Hackers Manual October 2009 mpt_event_register 9 2.6.32-rc5 mpt_event_register Register protocol-specific event callback handler. int mpt_event_register u8 cb_idx MPT_EVHANDLER ev_cbfunc cb_idx previously registered (via mpt_register) callback handle ev_cbfunc callback function This routine can be called by one or more protocol-specific drivers if/when they choose to be notified of MPT events. Returns 0 for success. Kernel Hackers Manual October 2009 mpt_event_deregister 9 2.6.32-rc5 mpt_event_deregister Deregister protocol-specific event callback handler void mpt_event_deregister u8 cb_idx cb_idx previously registered callback handle Each protocol-specific driver should call this routine when it does not (or can no longer) handle events, or when its module is unloaded. Kernel Hackers Manual October 2009 mpt_reset_register 9 2.6.32-rc5 mpt_reset_register Register protocol-specific IOC reset handler. int mpt_reset_register u8 cb_idx MPT_RESETHANDLER reset_func cb_idx previously registered (via mpt_register) callback handle reset_func reset function This routine can be called by one or more protocol-specific drivers if/when they choose to be notified of IOC resets. Returns 0 for success. Kernel Hackers Manual October 2009 mpt_reset_deregister 9 2.6.32-rc5 mpt_reset_deregister Deregister protocol-specific IOC reset handler. void mpt_reset_deregister u8 cb_idx cb_idx previously registered callback handle Each protocol-specific driver should call this routine when it does not (or can no longer) handle IOC reset handling, or when its module is unloaded. Kernel Hackers Manual October 2009 mpt_device_driver_register 9 2.6.32-rc5 mpt_device_driver_register Register device driver hooks int mpt_device_driver_register struct mpt_pci_driver * dd_cbfunc u8 cb_idx dd_cbfunc driver callbacks struct cb_idx MPT protocol driver index Kernel Hackers Manual October 2009 mpt_device_driver_deregister 9 2.6.32-rc5 mpt_device_driver_deregister DeRegister device driver hooks void mpt_device_driver_deregister u8 cb_idx cb_idx MPT protocol driver index Kernel Hackers Manual October 2009 mpt_get_msg_frame 9 2.6.32-rc5 mpt_get_msg_frame Obtain an MPT request frame from the pool MPT_FRAME_HDR* mpt_get_msg_frame u8 cb_idx MPT_ADAPTER * ioc cb_idx Handle of registered MPT protocol driver ioc Pointer to MPT adapter structure Obtain an MPT request frame from the pool (of 1024) that are allocated per MPT adapter. Returns pointer to a MPT request frame or NULL if none are available or IOC is not active. Kernel Hackers Manual October 2009 mpt_put_msg_frame 9 2.6.32-rc5 mpt_put_msg_frame Send a protocol-specific MPT request frame to an IOC void mpt_put_msg_frame u8 cb_idx MPT_ADAPTER * ioc MPT_FRAME_HDR * mf cb_idx Handle of registered MPT protocol driver ioc Pointer to MPT adapter structure mf Pointer to MPT request frame This routine posts an MPT request frame to the request post FIFO of a specific MPT adapter. Kernel Hackers Manual October 2009 mpt_put_msg_frame_hi_pri 9 2.6.32-rc5 mpt_put_msg_frame_hi_pri Send a hi-pri protocol-specific MPT request frame void mpt_put_msg_frame_hi_pri u8 cb_idx MPT_ADAPTER * ioc MPT_FRAME_HDR * mf cb_idx Handle of registered MPT protocol driver ioc Pointer to MPT adapter structure mf Pointer to MPT request frame Send a protocol-specific MPT request frame to an IOC using hi-priority request queue. This routine posts an MPT request frame to the request post FIFO of a specific MPT adapter. Kernel Hackers Manual October 2009 mpt_free_msg_frame 9 2.6.32-rc5 mpt_free_msg_frame Place MPT request frame back on FreeQ. void mpt_free_msg_frame MPT_ADAPTER * ioc MPT_FRAME_HDR * mf ioc Pointer to MPT adapter structure mf Pointer to MPT request frame This routine places a MPT request frame back on the MPT adapter's FreeQ. Kernel Hackers Manual October 2009 mpt_send_handshake_request 9 2.6.32-rc5 mpt_send_handshake_request Send MPT request via doorbell handshake method. int mpt_send_handshake_request u8 cb_idx MPT_ADAPTER * ioc int reqBytes u32 * req int sleepFlag cb_idx Handle of registered MPT protocol driver ioc Pointer to MPT adapter structure reqBytes Size of the request in bytes req Pointer to MPT request frame sleepFlag Use schedule if CAN_SLEEP else use udelay. This routine is used exclusively to send MptScsiTaskMgmt requests since they are required to be sent via doorbell handshake. It is the callers responsibility to byte-swap fields in the request which are greater than 1 byte in size. Returns 0 for success, non-zero for failure. Kernel Hackers Manual October 2009 mpt_verify_adapter 9 2.6.32-rc5 mpt_verify_adapter Given IOC identifier, set pointer to its adapter structure. int mpt_verify_adapter int iocid MPT_ADAPTER ** iocpp iocid IOC unique identifier (integer) iocpp Pointer to pointer to IOC adapter Given a unique IOC identifier, set pointer to the associated MPT adapter structure. Returns iocid and sets iocpp if iocid is found. Returns -1 if iocid is not found. Kernel Hackers Manual October 2009 mpt_attach 9 2.6.32-rc5 mpt_attach Install a PCI intelligent MPT adapter. int mpt_attach struct pci_dev * pdev const struct pci_device_id * id pdev Pointer to pci_dev structure id PCI device ID information This routine performs all the steps necessary to bring the IOC of a MPT adapter to a OPERATIONAL state. This includes registering memory regions, registering the interrupt, and allocating request and reply memory pools. This routine also pre-fetches the LAN MAC address of a Fibre Channel MPT adapter. Returns 0 for success, non-zero for failure. Add support for polled controllers Kernel Hackers Manual October 2009 mpt_detach 9 2.6.32-rc5 mpt_detach Remove a PCI intelligent MPT adapter. void mpt_detach struct pci_dev * pdev pdev Pointer to pci_dev structure Kernel Hackers Manual October 2009 mpt_suspend 9 2.6.32-rc5 mpt_suspend Fusion MPT base driver suspend routine. int mpt_suspend struct pci_dev * pdev pm_message_t state pdev Pointer to pci_dev structure state new state to enter Kernel Hackers Manual October 2009 mpt_resume 9 2.6.32-rc5 mpt_resume Fusion MPT base driver resume routine. int mpt_resume struct pci_dev * pdev pdev Pointer to pci_dev structure Kernel Hackers Manual October 2009 mpt_GetIocState 9 2.6.32-rc5 mpt_GetIocState Get the current state of a MPT adapter. u32 mpt_GetIocState MPT_ADAPTER * ioc int cooked ioc Pointer to MPT_ADAPTER structure cooked Request raw or cooked IOC state Returns all IOC Doorbell register bits if cooked==0, else just the Doorbell bits in MPI_IOC_STATE_MASK. Kernel Hackers Manual October 2009 mpt_alloc_fw_memory 9 2.6.32-rc5 mpt_alloc_fw_memory allocate firmware memory int mpt_alloc_fw_memory MPT_ADAPTER * ioc int size ioc Pointer to MPT_ADAPTER structure size total FW bytes If memory has already been allocated, the same (cached) value is returned. Return 0 if successfull, or non-zero for failure Kernel Hackers Manual October 2009 mpt_free_fw_memory 9 2.6.32-rc5 mpt_free_fw_memory free firmware memory void mpt_free_fw_memory MPT_ADAPTER * ioc ioc Pointer to MPT_ADAPTER structure If alt_img is NULL, delete from ioc structure. Else, delete a secondary image in same format. Kernel Hackers Manual October 2009 mptbase_sas_persist_operation 9 2.6.32-rc5 mptbase_sas_persist_operation Perform operation on SAS Persistent Table int mptbase_sas_persist_operation MPT_ADAPTER * ioc u8 persist_opcode ioc Pointer to MPT_ADAPTER structure persist_opcode see below MPI_SAS_OP_CLEAR_NOT_PRESENT - Free all persist TargetID mappings for devices not currently present. MPI_SAS_OP_CLEAR_ALL_PERSISTENT - Clear al persist TargetID mappings Don't use not this function during interrupt time. Returns 0 for success, non-zero error Kernel Hackers Manual October 2009 mpt_raid_phys_disk_pg0 9 2.6.32-rc5 mpt_raid_phys_disk_pg0 returns phys disk page zero int mpt_raid_phys_disk_pg0 MPT_ADAPTER * ioc u8 phys_disk_num RaidPhysDiskPage0_t * phys_disk ioc Pointer to a Adapter Structure phys_disk_num io unit unique phys disk num generated by the ioc phys_disk requested payload data returned 0 on success -EFAULT if read of config page header fails or data pointer not NULL -ENOMEM if pci_alloc failed Kernel Hackers Manual October 2009 mpt_raid_phys_disk_get_num_paths 9 2.6.32-rc5 mpt_raid_phys_disk_get_num_paths returns number paths associated to this phys_num int mpt_raid_phys_disk_get_num_paths MPT_ADAPTER * ioc u8 phys_disk_num ioc Pointer to a Adapter Structure phys_disk_num io unit unique phys disk num generated by the ioc returns number paths Kernel Hackers Manual October 2009 mpt_raid_phys_disk_pg1 9 2.6.32-rc5 mpt_raid_phys_disk_pg1 returns phys disk page 1 int mpt_raid_phys_disk_pg1 MPT_ADAPTER * ioc u8 phys_disk_num RaidPhysDiskPage1_t * phys_disk ioc Pointer to a Adapter Structure phys_disk_num io unit unique phys disk num generated by the ioc phys_disk requested payload data returned 0 on success -EFAULT if read of config page header fails or data pointer not NULL -ENOMEM if pci_alloc failed Kernel Hackers Manual October 2009 mpt_findImVolumes 9 2.6.32-rc5 mpt_findImVolumes Identify IDs of hidden disks and RAID Volumes int mpt_findImVolumes MPT_ADAPTER * ioc ioc Pointer to a Adapter Strucutre 0 on success -EFAULT if read of config page header fails or data pointer not NULL -ENOMEM if pci_alloc failed Kernel Hackers Manual October 2009 mpt_config 9 2.6.32-rc5 mpt_config Generic function to issue config message int mpt_config MPT_ADAPTER * ioc CONFIGPARMS * pCfg ioc Pointer to an adapter structure pCfg Pointer to a configuration structure. Struct contains action, page address, direction, physical address and pointer to a configuration page header Page header is updated. Returns 0 for success -EPERM if not allowed due to ISR context -EAGAIN if no msg frames currently available -EFAULT for non-successful reply or no reply (timeout) Kernel Hackers Manual October 2009 mpt_print_ioc_summary 9 2.6.32-rc5 mpt_print_ioc_summary Write ASCII summary of IOC to a buffer. void mpt_print_ioc_summary MPT_ADAPTER * ioc char * buffer int * size int len int showlan ioc Pointer to MPT_ADAPTER structure buffer Pointer to buffer where IOC summary info should be written size Pointer to number of bytes we wrote (set by this routine) len Offset at which to start writing in buffer showlan Display LAN stuff? This routine writes (english readable) ASCII text, which represents a summary of IOC information, to a buffer. Kernel Hackers Manual October 2009 mpt_set_taskmgmt_in_progress_flag 9 2.6.32-rc5 mpt_set_taskmgmt_in_progress_flag set flags associated with task management int mpt_set_taskmgmt_in_progress_flag MPT_ADAPTER * ioc ioc Pointer to MPT_ADAPTER structure Returns 0 for SUCCESS or -1 if FAILED. If -1 is return, then it was not possible to set the flags Kernel Hackers Manual October 2009 mpt_clear_taskmgmt_in_progress_flag 9 2.6.32-rc5 mpt_clear_taskmgmt_in_progress_flag clear flags associated with task management void mpt_clear_taskmgmt_in_progress_flag MPT_ADAPTER * ioc ioc Pointer to MPT_ADAPTER structure Kernel Hackers Manual October 2009 mpt_halt_firmware 9 2.6.32-rc5 mpt_halt_firmware Halts the firmware if it is operational and panic the kernel void mpt_halt_firmware MPT_ADAPTER * ioc ioc Pointer to MPT_ADAPTER structure Kernel Hackers Manual October 2009 mpt_HardResetHandler 9 2.6.32-rc5 mpt_HardResetHandler Generic reset handler int mpt_HardResetHandler MPT_ADAPTER * ioc int sleepFlag ioc Pointer to MPT_ADAPTER structure sleepFlag Indicates if sleep or schedule must be called. Issues SCSI Task Management call based on input arg values. If TaskMgmt fails, returns associated SCSI request. _HardResetHandler can be invoked from an interrupt thread (timer) or a non-interrupt thread. In the former, must not call schedule. A return of -1 is a FATAL error case, as it means a FW reload/initialization failed. Returns 0 for SUCCESS or -1 if FAILED. Kernel Hackers Manual October 2009 mpt_get_cb_idx 9 2.6.32-rc5 mpt_get_cb_idx obtain cb_idx for registered driver u8 mpt_get_cb_idx MPT_DRIVER_CLASS dclass dclass class driver enum Returns cb_idx, or zero means it wasn't found Kernel Hackers Manual October 2009 mpt_is_discovery_complete 9 2.6.32-rc5 mpt_is_discovery_complete determine if discovery has completed int mpt_is_discovery_complete MPT_ADAPTER * ioc ioc per adatper instance Returns 1 when discovery completed, else zero. Kernel Hackers Manual October 2009 mpt_fault_reset_work 9 2.6.32-rc5 mpt_fault_reset_work work performed on workq after ioc fault void mpt_fault_reset_work struct work_struct * work work input argument, used to derive ioc Kernel Hackers Manual October 2009 mpt_interrupt 9 2.6.32-rc5 mpt_interrupt MPT adapter (IOC) specific interrupt handler. irqreturn_t mpt_interrupt int irq void * bus_id irq irq number (not used) bus_id bus identifier cookie == pointer to MPT_ADAPTER structure This routine is registered via the request_irq kernel API call, and handles all interrupts generated from a specific MPT adapter (also referred to as a IO Controller or IOC). This routine must clear the interrupt from the adapter and does so by reading the reply FIFO. Multiple replies may be processed per single call to this routine. This routine handles register-level access of the adapter but dispatches (calls) a protocol-specific callback routine to handle the protocol-specific details of the MPT request completion. Kernel Hackers Manual October 2009 mptbase_reply 9 2.6.32-rc5 mptbase_reply MPT base driver's callback routine int mptbase_reply MPT_ADAPTER * ioc MPT_FRAME_HDR * req MPT_FRAME_HDR * reply ioc Pointer to MPT_ADAPTER structure req Pointer to original MPT request frame reply Pointer to MPT reply frame (NULL if TurboReply) MPT base driver's callback routine; all base driver internal request/reply processing is routed here. Currently used for EventNotification and EventAck handling. Returns 1 indicating original alloc'd request frame ptr should be freed, or 0 if it shouldn't. Kernel Hackers Manual October 2009 mpt_add_sge 9 2.6.32-rc5 mpt_add_sge Place a simple 32 bit SGE at address pAddr. void mpt_add_sge void * pAddr u32 flagslength dma_addr_t dma_addr pAddr virtual address for SGE flagslength SGE flags and data transfer length dma_addr Physical address This routine places a MPT request frame back on the MPT adapter's FreeQ. Kernel Hackers Manual October 2009 mpt_add_sge_64bit 9 2.6.32-rc5 mpt_add_sge_64bit Place a simple 64 bit SGE at address pAddr. void mpt_add_sge_64bit void * pAddr u32 flagslength dma_addr_t dma_addr pAddr virtual address for SGE flagslength SGE flags and data transfer length dma_addr Physical address This routine places a MPT request frame back on the MPT adapter's FreeQ. Kernel Hackers Manual October 2009 mpt_add_sge_64bit_1078 9 2.6.32-rc5 mpt_add_sge_64bit_1078 Place a simple 64 bit SGE at address pAddr (1078 workaround). void mpt_add_sge_64bit_1078 void * pAddr u32 flagslength dma_addr_t dma_addr pAddr virtual address for SGE flagslength SGE flags and data transfer length dma_addr Physical address This routine places a MPT request frame back on the MPT adapter's FreeQ. Kernel Hackers Manual October 2009 mpt_add_chain 9 2.6.32-rc5 mpt_add_chain Place a 32 bit chain SGE at address pAddr. void mpt_add_chain void * pAddr u8 next u16 length dma_addr_t dma_addr pAddr virtual address for SGE next nextChainOffset value (u32's) length length of next SGL segment dma_addr Physical address Kernel Hackers Manual October 2009 mpt_add_chain_64bit 9 2.6.32-rc5 mpt_add_chain_64bit Place a 64 bit chain SGE at address pAddr. void mpt_add_chain_64bit void * pAddr u8 next u16 length dma_addr_t dma_addr pAddr virtual address for SGE next nextChainOffset value (u32's) length length of next SGL segment dma_addr Physical address Kernel Hackers Manual October 2009 mpt_host_page_access_control 9 2.6.32-rc5 mpt_host_page_access_control control the IOC's Host Page Buffer access int mpt_host_page_access_control MPT_ADAPTER * ioc u8 access_control_value int sleepFlag ioc Pointer to MPT adapter structure access_control_value define bits below sleepFlag Specifies whether the process can sleep Provides mechanism for the host driver to control the IOC's Host Page Buffer access. Access Control Value - bits[15:12] 0h Reserved 1h Enable Access { MPI_DB_HPBAC_ENABLE_ACCESS } 2h Disable Access { MPI_DB_HPBAC_DISABLE_ACCESS } 3h Free Buffer { MPI_DB_HPBAC_FREE_BUFFER } Returns 0 for success, non-zero for failure. Kernel Hackers Manual October 2009 mpt_host_page_alloc 9 2.6.32-rc5 mpt_host_page_alloc allocate system memory for the fw int mpt_host_page_alloc MPT_ADAPTER * ioc pIOCInit_t ioc_init ioc Pointer to pointer to IOC adapter ioc_init Pointer to ioc init config page If we already allocated memory in past, then resend the same pointer. Returns 0 for success, non-zero for failure. Kernel Hackers Manual October 2009 mpt_get_product_name 9 2.6.32-rc5 mpt_get_product_name returns product string void mpt_get_product_name u16 vendor u16 device u8 revision char * prod_name vendor pci vendor id device pci device id revision pci revision id prod_name string returned Returns product string displayed when driver loads, in /proc/mpt/summary and /sysfs/class/scsi_host/host<X>/version_product Kernel Hackers Manual October 2009 mpt_mapresources 9 2.6.32-rc5 mpt_mapresources map in memory mapped io int mpt_mapresources MPT_ADAPTER * ioc ioc Pointer to pointer to IOC adapter