# The Linux Kernel API

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.

## Driver Basics

### Driver Entry and Exit points

#### LINUX

Kernel Hackers Manual January 2008
module_init
9
2.6.24-rc6-git8

#### module_init

driver initialization entry point

##### Synopsis

        module_init
        x

##### Arguments

`x`

  function to be run at kernel boot time or module insertion

##### Description

`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.

#### LINUX

Kernel Hackers Manual January 2008
module_exit
9
2.6.24-rc6-git8

#### module_exit

driver exit entry point

##### Synopsis

        module_exit
        x

##### Arguments

`x`

  function to be run when driver is removed

##### Description

`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.

### Atomic and pointer manipulation

#### LINUX

Kernel Hackers Manual January 2008
atomic_read
9
2.6.24-rc6-git8

#### atomic_read

read atomic variable

##### Synopsis

        atomic_read
        v

##### Arguments

`v`

  pointer of type atomic_t

##### Description

Atomically reads the value of `v`.

#### LINUX

Kernel Hackers Manual January 2008
atomic_set
9
2.6.24-rc6-git8

#### atomic_set

set atomic variable

##### Synopsis

        atomic_set
        v
        i

##### Arguments

`v`

  pointer of type atomic_t

`i`

  required value

##### Description

Atomically sets the value of `v` to `i`.

#### LINUX

Kernel Hackers Manual January 2008
atomic_add
9
2.6.24-rc6-git8

#### atomic_add

add integer to atomic variable

##### Synopsis

       void atomic_add
       int i
       atomic_t * v

##### Arguments

`i`

  integer value to add

`v`

  pointer of type atomic_t

##### Description

Atomically adds `i` to `v`.

#### LINUX

Kernel Hackers Manual January 2008
atomic_sub
9
2.6.24-rc6-git8

#### atomic_sub

subtract integer from atomic variable

##### Synopsis

       void atomic_sub
       int i
       atomic_t * v

##### Arguments

`i`

  integer value to subtract

`v`

  pointer of type atomic_t

##### Description

Atomically subtracts `i` from `v`.

#### LINUX

Kernel Hackers Manual January 2008
atomic_sub_and_test
9
2.6.24-rc6-git8

#### atomic_sub_and_test

subtract value from variable and test result

##### Synopsis

       int atomic_sub_and_test
       int i
       atomic_t * v

##### Arguments

`i`

  integer value to subtract

`v`

  pointer of type atomic_t

##### Description

Atomically subtracts `i` from `v` and returns true if the result is zero, or false for all other cases.

#### LINUX

Kernel Hackers Manual January 2008
atomic_inc
9
2.6.24-rc6-git8

#### atomic_inc

increment atomic variable

##### Synopsis

       void atomic_inc
       atomic_t * v

##### Arguments

`v`

  pointer of type atomic_t

##### Description

Atomically increments `v` by 1.

#### LINUX

Kernel Hackers Manual January 2008
atomic_dec
9
2.6.24-rc6-git8

#### atomic_dec

decrement atomic variable

##### Synopsis

       void atomic_dec
       atomic_t * v

##### Arguments

`v`

  pointer of type atomic_t

##### Description

Atomically decrements `v` by 1.

#### LINUX

Kernel Hackers Manual January 2008
atomic_dec_and_test
9
2.6.24-rc6-git8

#### atomic_dec_and_test

decrement and test

##### Synopsis

       int atomic_dec_and_test
       atomic_t * v

##### Arguments

`v`

  pointer of type atomic_t

##### Description

Atomically decrements `v` by 1 and returns true if the result is 0, or false for all other cases.

#### LINUX

Kernel Hackers Manual January 2008
atomic_inc_and_test
9
2.6.24-rc6-git8

#### atomic_inc_and_test

increment and test

##### Synopsis

       int atomic_inc_and_test
       atomic_t * v

##### Arguments

`v`

  pointer of type atomic_t

##### Description

Atomically increments `v` by 1 and returns true if the result is zero, or false for all other cases.

#### LINUX

Kernel Hackers Manual January 2008
atomic_add_negative
9
2.6.24-rc6-git8

#### atomic_add_negative

add and test if negative

##### Synopsis

       int atomic_add_negative
       int i
       atomic_t * v

##### Arguments

`i`

  integer value to add

`v`

  pointer of type atomic_t

##### Description

Atomically adds `i` to `v` and returns true if the result is negative, or false when result is greater than or equal to zero.

#### LINUX

Kernel Hackers Manual January 2008
atomic_add_return
9
2.6.24-rc6-git8

#### atomic_add_return

add integer and return

##### Synopsis

       int atomic_add_return
       int i
       atomic_t * v

##### Arguments

`i`

  integer value to add

`v`

  pointer of type atomic_t

##### Description

Atomically adds `i` to `v` and returns `i` + `v`

#### LINUX

Kernel Hackers Manual January 2008
atomic_sub_return
9
2.6.24-rc6-git8

#### atomic_sub_return

subtract integer and return

##### Synopsis

       int atomic_sub_return
       int i
       atomic_t * v

##### Arguments

`i`

  integer value to subtract

`v`

  pointer of type atomic_t

##### Description

Atomically subtracts `i` from `v` and returns `v` - `i`

#### LINUX

Kernel Hackers Manual January 2008
atomic_add_unless
9
2.6.24-rc6-git8

#### atomic_add_unless

add unless the number is already a given value

##### Synopsis

       int atomic_add_unless
       atomic_t * v
       int a
       int u

##### Arguments

`v`

  pointer of type atomic_t

`a`

  the amount to add to v...

`u`

  ...unless v is equal to u.

##### Description

Atomically adds `a` to `v`, so long as `v` was not already `u`. Returns non-zero if `v` was not `u`, and zero otherwise.

#### LINUX

Kernel Hackers Manual January 2008
get_unaligned
9
2.6.24-rc6-git8

#### get_unaligned

get value from possibly mis-aligned location

##### Synopsis

        get_unaligned
        ptr

##### Arguments

`ptr`

  pointer to value

##### Description

This macro should be used for accessing values larger in size than single bytes at locations that are expected to be improperly aligned, e.g. retrieving a u16 value from a location not u16-aligned.

Note that unaligned accesses can be very expensive on some architectures.

#### LINUX

Kernel Hackers Manual January 2008
put_unaligned
9
2.6.24-rc6-git8

#### put_unaligned

put value to a possibly mis-aligned location

##### Synopsis

        put_unaligned
        val
        ptr

##### Arguments

`val`

  value to place

`ptr`

  pointer to location

##### Description

This macro should be used for placing values larger in size than single bytes at locations that are expected to be improperly aligned, e.g. writing a u16 value to a location not u16-aligned.

Note that unaligned accesses can be very expensive on some architectures.

### Delaying, scheduling, and timer routines

#### LINUX

Kernel Hackers Manual January 2008
pid_alive
9
2.6.24-rc6-git8

#### pid_alive

check that a task structure is not stale

##### Synopsis

       int pid_alive
       struct task_struct * p

##### Arguments

`p`

  Task structure to be checked.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
is_global_init
9
2.6.24-rc6-git8

#### is_global_init

check if a task structure is init

##### Synopsis

       int is_global_init
       struct task_struct * tsk

##### Arguments

`tsk`

  Task structure to be checked.

##### Description

Check if a task structure is the first user space task the kernel created.

#### LINUX

Kernel Hackers Manual January 2008
preempt_notifier_register
9
2.6.24-rc6-git8

#### preempt_notifier_register

tell me when current is being being preempted & rescheduled

##### Synopsis

       void preempt_notifier_register
       struct preempt_notifier * notifier

##### Arguments

`notifier`

  notifier struct to register

#### LINUX

Kernel Hackers Manual January 2008
preempt_notifier_unregister
9
2.6.24-rc6-git8

#### preempt_notifier_unregister

no longer interested in preemption notifications

##### Synopsis

       void preempt_notifier_unregister
       struct preempt_notifier * notifier

##### Arguments

`notifier`

  notifier struct to unregister

##### Description

This is safe to call from within a preemption notifier.

#### LINUX

Kernel Hackers Manual January 2008
__wake_up
9
2.6.24-rc6-git8

#### __wake_up

wake up threads blocked on a waitqueue.

##### Synopsis

       void fastcall __wake_up
       wait_queue_head_t * q
       unsigned int mode
       int nr_exclusive
       void * key

##### Arguments

`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

#### LINUX

Kernel Hackers Manual January 2008
__wake_up_sync
9
2.6.24-rc6-git8

#### __wake_up_sync

wake up threads blocked on a waitqueue.

##### Synopsis

       void fastcall __wake_up_sync
       wait_queue_head_t * q
       unsigned int mode
       int nr_exclusive

##### Arguments

`q`

  the waitqueue

`mode`

  which threads

`nr_exclusive`

  how many wake-one or wake-many threads to wake up

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
task_nice
9
2.6.24-rc6-git8

#### task_nice

return the nice value of a given task.

##### Synopsis

       int task_nice
       const struct task_struct * p

##### Arguments

`p`

  the task in question.

#### LINUX

Kernel Hackers Manual January 2008
sched_setscheduler
9
2.6.24-rc6-git8

#### sched_setscheduler

change the scheduling policy and/or RT priority of a thread.

##### Synopsis

       int sched_setscheduler
       struct task_struct * p
       int policy
       struct sched_param * param

##### Arguments

`p`

  the task in question.

`policy`

  new policy.

`param`

  structure containing the new RT priority.

##### Description

NOTE that the task may be already dead.

#### LINUX

Kernel Hackers Manual January 2008
yield
9
2.6.24-rc6-git8

#### yield

yield the current processor to other threads.

##### Synopsis

       void __sched yield
        void

##### Arguments

`void`

  no arguments

##### Description

This is a shortcut for kernel-space yielding - it marks the thread runnable and calls `sys_sched_yield`.

#### LINUX

Kernel Hackers Manual January 2008
__round_jiffies
9
2.6.24-rc6-git8

#### __round_jiffies

function to round jiffies to a full second

##### Synopsis

       unsigned long __round_jiffies
       unsigned long j
       int cpu

##### Arguments

`j`

  the time in (absolute) jiffies that should be rounded

`cpu`

  the processor number on which the timeout will happen

##### Description

`__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.

#### LINUX

Kernel Hackers Manual January 2008
__round_jiffies_relative
9
2.6.24-rc6-git8

#### __round_jiffies_relative

function to round jiffies to a full second

##### Synopsis

       unsigned long __round_jiffies_relative
       unsigned long j
       int cpu

##### Arguments

`j`

  the time in (relative) jiffies that should be rounded

`cpu`

  the processor number on which the timeout will happen

##### Description

`__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.

#### LINUX

Kernel Hackers Manual January 2008
round_jiffies
9
2.6.24-rc6-git8

#### round_jiffies

function to round jiffies to a full second

##### Synopsis

       unsigned long round_jiffies
       unsigned long j

##### Arguments

`j`

  the time in (absolute) jiffies that should be rounded

##### Description

`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.

#### LINUX

Kernel Hackers Manual January 2008
round_jiffies_relative
9
2.6.24-rc6-git8

#### round_jiffies_relative

function to round jiffies to a full second

##### Synopsis

       unsigned long round_jiffies_relative
       unsigned long j

##### Arguments

`j`

  the time in (relative) jiffies that should be rounded

##### Description

`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.

#### LINUX

Kernel Hackers Manual January 2008
init_timer
9
2.6.24-rc6-git8

#### init_timer

initialize a timer.

##### Synopsis

       void fastcall init_timer
       struct timer_list * timer

##### Arguments

`timer`

  the timer to be initialized

##### Description

`init_timer` must be done to a timer prior calling *any* of the other timer functions.

#### LINUX

Kernel Hackers Manual January 2008
mod_timer
9
2.6.24-rc6-git8

#### mod_timer

modify a timer's timeout

##### Synopsis

       int mod_timer
       struct timer_list * timer
       unsigned long expires

##### Arguments

`timer`

  the timer to be modified

`expires`

  new timeout in jiffies

##### Description

`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.)

#### LINUX

Kernel Hackers Manual January 2008
del_timer
9
2.6.24-rc6-git8

#### del_timer

deactive a timer.

##### Synopsis

       int del_timer
       struct timer_list * timer

##### Arguments

`timer`

  the timer to be deactivated

##### Description

`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.)

#### LINUX

Kernel Hackers Manual January 2008
try_to_del_timer_sync
9
2.6.24-rc6-git8

#### try_to_del_timer_sync

Try to deactivate a timer

##### Synopsis

       int try_to_del_timer_sync
       struct timer_list * timer

##### Arguments

`timer`

  timer do del

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
del_timer_sync
9
2.6.24-rc6-git8

#### del_timer_sync

deactivate a timer and wait for the handler to finish.

##### Synopsis

       int del_timer_sync
       struct timer_list * timer

##### Arguments

`timer`

  the timer to be deactivated

##### Description

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.

##### Synchronization rules

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.

#### LINUX

Kernel Hackers Manual January 2008
schedule_timeout
9
2.6.24-rc6-git8

#### schedule_timeout

sleep until timeout

##### Synopsis

       signed long __sched schedule_timeout
       signed long timeout

##### Arguments

`timeout`

  timeout value in jiffies

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
msleep
9
2.6.24-rc6-git8

#### msleep

sleep safely even with waitqueue interruptions

##### Synopsis

       void msleep
       unsigned int msecs

##### Arguments

`msecs`

  Time in milliseconds to sleep for

#### LINUX

Kernel Hackers Manual January 2008
msleep_interruptible
9
2.6.24-rc6-git8

#### msleep_interruptible

sleep waiting for signals

##### Synopsis

       unsigned long msleep_interruptible
       unsigned int msecs

##### Arguments

`msecs`

  Time in milliseconds to sleep for

### High-resolution timers

#### LINUX

Kernel Hackers Manual January 2008
ktime_set
9
2.6.24-rc6-git8

#### ktime_set

Set a ktime_t variable from a seconds/nanoseconds value

##### Synopsis

       ktime_t ktime_set
       const long secs
       const unsigned long nsecs

##### Arguments

`secs`

  seconds to set

`nsecs`

  nanoseconds to set

##### Description

Return the ktime_t representation of the value

#### LINUX

Kernel Hackers Manual January 2008
ktime_sub
9
2.6.24-rc6-git8

#### ktime_sub

subtract two ktime_t variables

##### Synopsis

       ktime_t ktime_sub
       const ktime_t lhs
       const ktime_t rhs

##### Arguments

`lhs`

  minuend

`rhs`

  subtrahend

##### Description

Returns the remainder of the substraction

#### LINUX

Kernel Hackers Manual January 2008
ktime_add
9
2.6.24-rc6-git8

#### ktime_add

add two ktime_t variables

##### Synopsis

       ktime_t ktime_add
       const ktime_t add1
       const ktime_t add2

##### Arguments

`add1`

  addend1

`add2`

  addend2

##### Description

Returns the sum of `add1` and `add2`.

#### LINUX

Kernel Hackers Manual January 2008
timespec_to_ktime
9
2.6.24-rc6-git8

#### timespec_to_ktime

convert a timespec to ktime_t format

##### Synopsis

       ktime_t timespec_to_ktime
       const struct timespec ts

##### Arguments

`ts`

  the timespec variable to convert

##### Description

Returns a ktime_t variable with the converted timespec value

#### LINUX

Kernel Hackers Manual January 2008
timeval_to_ktime
9
2.6.24-rc6-git8

#### timeval_to_ktime

convert a timeval to ktime_t format

##### Synopsis

       ktime_t timeval_to_ktime
       const struct timeval tv

##### Arguments

`tv`

  the timeval variable to convert

##### Description

Returns a ktime_t variable with the converted timeval value

#### LINUX

Kernel Hackers Manual January 2008
ktime_to_timespec
9
2.6.24-rc6-git8

#### ktime_to_timespec

convert a ktime_t variable to timespec format

##### Synopsis

       struct timespec ktime_to_timespec
       const ktime_t kt

##### Arguments

`kt`

  the ktime_t variable to convert

##### Description

Returns the timespec representation of the ktime value

#### LINUX

Kernel Hackers Manual January 2008
ktime_to_timeval
9
2.6.24-rc6-git8

#### ktime_to_timeval

convert a ktime_t variable to timeval format

##### Synopsis

       struct timeval ktime_to_timeval
       const ktime_t kt

##### Arguments

`kt`

  the ktime_t variable to convert

##### Description

Returns the timeval representation of the ktime value

#### LINUX

Kernel Hackers Manual January 2008
ktime_to_ns
9
2.6.24-rc6-git8

#### ktime_to_ns

convert a ktime_t variable to scalar nanoseconds

##### Synopsis

       s64 ktime_to_ns
       const ktime_t kt

##### Arguments

`kt`

  the ktime_t variable to convert

##### Description

Returns the scalar nanoseconds representation of `kt`

#### LINUX

Kernel Hackers Manual January 2008
ktime_equal
9
2.6.24-rc6-git8

#### ktime_equal

Compares two ktime_t variables to see if they are equal

##### Synopsis

       int ktime_equal
       const ktime_t cmp1
       const ktime_t cmp2

##### Arguments

`cmp1`

  comparable1

`cmp2`

  comparable2

##### Description

Compare two ktime_t variables, returns 1 if equal

#### LINUX

Kernel Hackers Manual January 2008
struct hrtimer
9
2.6.24-rc6-git8

#### struct hrtimer

the basic hrtimer structure

##### Synopsis

    struct hrtimer {
      struct rb_node node;
      ktime_t expires;
      enum hrtimer_restart		(* function) (struct hrtimer *);
      struct hrtimer_clock_base * base;
      unsigned long state;
    #ifdef CONFIG_HIGH_RES_TIMERS
      enum hrtimer_cb_mode cb_mode;
      struct list_head cb_entry;
    #endif
    #ifdef CONFIG_TIMER_STATS
      void * start_site;
      char start_comm[16];
      int start_pid;
    #endif
    };

##### Members

node

  red black tree node for time ordered insertion

expires

  the absolute expiry time in the hrtimers internal representation. The time is related to the clock on which the timer is based.

function

  timer expiry callback function

base

  pointer to the timer base (per cpu and per clock)

state

  state information (See bit values above)

cb_mode

  high resolution timer feature to select the callback execution mode

cb_entry

  list head to enqueue an expired timer into the callback list

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

start_pid

  timer statistics field to store the pid of the task which started the timer

##### Description

The hrtimer structure must be initialized by `hrtimer_init`

#### LINUX

Kernel Hackers Manual January 2008
struct hrtimer_sleeper
9
2.6.24-rc6-git8

#### struct hrtimer_sleeper

simple sleeper structure

##### Synopsis

    struct hrtimer_sleeper {
      struct hrtimer timer;
      struct task_struct * task;
    };

##### Members

timer

  embedded timer structure

task

  task to wake up

##### Description

task is set to NULL, when the timer expires.

#### LINUX

Kernel Hackers Manual January 2008
struct hrtimer_clock_base
9
2.6.24-rc6-git8

#### struct hrtimer_clock_base

the timer base for a specific clock

##### Synopsis

    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 (* get_softirq_time) (void);
      ktime_t softirq_time;
    #ifdef CONFIG_HIGH_RES_TIMERS
      ktime_t offset;
      int (* reprogram) (struct hrtimer *t,struct hrtimer_clock_base *b,ktime_t n);
    #endif
    };

##### Members

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

get_softirq_time

  function to retrieve the current time from the softirq

softirq_time

  the time when running the hrtimer queue in the softirq

offset

  offset of this clock to the monotonic base

reprogram

  function to reprogram the timer event

#### LINUX

Kernel Hackers Manual January 2008
ktime_get
9
2.6.24-rc6-git8

#### ktime_get

get the monotonic time in ktime_t format

##### Synopsis

       ktime_t ktime_get
        void

##### Arguments

`void`

  no arguments

##### Description

returns the time in ktime_t format

#### LINUX

Kernel Hackers Manual January 2008
ktime_get_real
9
2.6.24-rc6-git8

#### ktime_get_real

get the real (wall-) time in ktime_t format

##### Synopsis

       ktime_t ktime_get_real
        void

##### Arguments

`void`

  no arguments

##### Description

returns the time in ktime_t format

#### LINUX

Kernel Hackers Manual January 2008
ktime_get_ts
9
2.6.24-rc6-git8

#### ktime_get_ts

get the monotonic clock in timespec format

##### Synopsis

       void ktime_get_ts
       struct timespec * ts

##### Arguments

`ts`

  pointer to timespec variable

##### Description

The function calculates the monotonic clock from the realtime clock and the wall_to_monotonic offset and stores the result in normalized timespec format in the variable pointed to by `ts`.

#### LINUX

Kernel Hackers Manual January 2008
ktime_add_ns
9
2.6.24-rc6-git8

#### ktime_add_ns

Add a scalar nanoseconds value to a ktime_t variable

##### Synopsis

       ktime_t ktime_add_ns
       const ktime_t kt
       u64 nsec

##### Arguments

`kt`

  addend

`nsec`

  the scalar nsec value to add

##### Description

Returns the sum of kt and nsec in ktime_t format

#### LINUX

Kernel Hackers Manual January 2008
ktime_sub_ns
9
2.6.24-rc6-git8

#### ktime_sub_ns

Subtract a scalar nanoseconds value from a ktime_t variable

##### Synopsis

       ktime_t ktime_sub_ns
       const ktime_t kt
       u64 nsec

##### Arguments

`kt`

  minuend

`nsec`

  the scalar nsec value to subtract

##### Description

Returns the subtraction of `nsec` from `kt` in ktime_t format

#### LINUX

Kernel Hackers Manual January 2008
hrtimer_forward
9
2.6.24-rc6-git8

#### hrtimer_forward

forward the timer expiry

##### Synopsis

       unsigned long hrtimer_forward
       struct hrtimer * timer
       ktime_t now
       ktime_t interval

##### Arguments

`timer`

  hrtimer to forward

`now`

  forward past this time

`interval`

  the interval to forward

##### Description

Forward the timer expiry so it will expire in the future. Returns the number of overruns.

#### LINUX

Kernel Hackers Manual January 2008
hrtimer_start
9
2.6.24-rc6-git8

#### hrtimer_start

(re)start an relative timer on the current CPU

##### Synopsis

       int hrtimer_start
       struct hrtimer * timer
       ktime_t tim
       const enum hrtimer_mode mode

##### Arguments

`timer`

  the timer to be added

`tim`

  expiry time

`mode`

  expiry mode: absolute (HRTIMER_ABS) or relative (HRTIMER_REL)

##### Returns

0 on success 1 when the timer was active

#### LINUX

Kernel Hackers Manual January 2008
hrtimer_try_to_cancel
9
2.6.24-rc6-git8

#### hrtimer_try_to_cancel

try to deactivate a timer

##### Synopsis

       int hrtimer_try_to_cancel
       struct hrtimer * timer

##### Arguments

`timer`

  hrtimer to stop

##### Returns

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

#### LINUX

Kernel Hackers Manual January 2008
hrtimer_cancel
9
2.6.24-rc6-git8

#### hrtimer_cancel

cancel a timer and wait for the handler to finish.

##### Synopsis

       int hrtimer_cancel
       struct hrtimer * timer

##### Arguments

`timer`

  the timer to be cancelled

##### Returns

0 when the timer was not active 1 when the timer was active

#### LINUX

Kernel Hackers Manual January 2008
hrtimer_get_remaining
9
2.6.24-rc6-git8

#### hrtimer_get_remaining

get remaining time for the timer

##### Synopsis

       ktime_t hrtimer_get_remaining
       const struct hrtimer * timer

##### Arguments

`timer`

  the timer to read

#### LINUX

Kernel Hackers Manual January 2008
hrtimer_init
9
2.6.24-rc6-git8

#### hrtimer_init

initialize a timer to the given clock

##### Synopsis

       void hrtimer_init
       struct hrtimer * timer
       clockid_t clock_id
       enum hrtimer_mode mode

##### Arguments

`timer`

  the timer to be initialized

`clock_id`

  the clock to be used

`mode`

  timer mode abs/rel

#### LINUX

Kernel Hackers Manual January 2008
hrtimer_get_res
9
2.6.24-rc6-git8

#### hrtimer_get_res

get the timer resolution for a clock

##### Synopsis

       int hrtimer_get_res
       const clockid_t which_clock
       struct timespec * tp

##### Arguments

`which_clock`

  which clock to query

`tp`

  pointer to timespec variable to store the resolution

##### Description

Store the resolution of the clock selected by `which_clock` in the variable pointed to by `tp`.

### Workqueues and Kevents

#### LINUX

Kernel Hackers Manual January 2008
queue_work
9
2.6.24-rc6-git8

#### queue_work

queue work on a workqueue

##### Synopsis

       int fastcall queue_work
       struct workqueue_struct * wq
       struct work_struct * work

##### Arguments

`wq`

  workqueue to use

`work`

  work to queue

##### Description

Returns 0 if `work` was already on a queue, non-zero otherwise.

We queue the work to the CPU it was submitted, but there is no guarantee that it will be processed by that CPU.

#### LINUX

Kernel Hackers Manual January 2008
queue_delayed_work
9
2.6.24-rc6-git8

#### queue_delayed_work

queue work on a workqueue after delay

##### Synopsis

       int fastcall queue_delayed_work
       struct workqueue_struct * wq
       struct delayed_work * dwork
       unsigned long delay

##### Arguments

`wq`

  workqueue to use

`dwork`

  delayable work to queue

`delay`

  number of jiffies to wait before queueing

##### Description

Returns 0 if `work` was already on a queue, non-zero otherwise.

#### LINUX

Kernel Hackers Manual January 2008
queue_delayed_work_on
9
2.6.24-rc6-git8

#### queue_delayed_work_on

queue work on specific CPU after delay

##### Synopsis

       int queue_delayed_work_on
       int cpu
       struct workqueue_struct * wq
       struct delayed_work * dwork
       unsigned long delay

##### Arguments

`cpu`

  CPU number to execute work on

`wq`

  workqueue to use

`dwork`

  work to queue

`delay`

  number of jiffies to wait before queueing

##### Description

Returns 0 if `work` was already on a queue, non-zero otherwise.

#### LINUX

Kernel Hackers Manual January 2008
flush_workqueue
9
2.6.24-rc6-git8

#### flush_workqueue

ensure that any scheduled work has run to completion.

##### Synopsis

       void fastcall flush_workqueue
       struct workqueue_struct * wq

##### Arguments

`wq`

  workqueue to flush

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
cancel_work_sync
9
2.6.24-rc6-git8

#### cancel_work_sync

block until a work_struct's callback has terminated

##### Synopsis

       int cancel_work_sync
       struct work_struct * work

##### Arguments

`work`

  the work which is to be flushed

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
cancel_delayed_work_sync
9
2.6.24-rc6-git8

#### cancel_delayed_work_sync

reliably kill off a delayed work.

##### Synopsis

       int cancel_delayed_work_sync
       struct delayed_work * dwork

##### Arguments

`dwork`

  the delayed work struct

##### Description

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`.

#### LINUX

Kernel Hackers Manual January 2008
schedule_work
9
2.6.24-rc6-git8

#### schedule_work

put work task in global workqueue

##### Synopsis

       int fastcall schedule_work
       struct work_struct * work

##### Arguments

`work`

  job to be done

##### Description

This puts a job in the kernel-global workqueue.

#### LINUX

Kernel Hackers Manual January 2008
schedule_delayed_work
9
2.6.24-rc6-git8

#### schedule_delayed_work

put work task in global workqueue after delay

##### Synopsis

       int fastcall schedule_delayed_work
       struct delayed_work * dwork
       unsigned long delay

##### Arguments

`dwork`

  job to be done

`delay`

  number of jiffies to wait or 0 for immediate execution

##### Description

After waiting for a given time this puts a job in the kernel-global workqueue.

#### LINUX

Kernel Hackers Manual January 2008
schedule_delayed_work_on
9
2.6.24-rc6-git8

#### schedule_delayed_work_on

queue work in global workqueue on CPU after delay

##### Synopsis

       int schedule_delayed_work_on
       int cpu
       struct delayed_work * dwork
       unsigned long delay

##### Arguments

`cpu`

  cpu to use

`dwork`

  job to be done

`delay`

  number of jiffies to wait

##### Description

After waiting for a given time this puts a job in the kernel-global workqueue on the specified CPU.

#### LINUX

Kernel Hackers Manual January 2008
execute_in_process_context
9
2.6.24-rc6-git8

#### execute_in_process_context

reliably execute the routine with user context

##### Synopsis

       int execute_in_process_context
       work_func_t fn
       struct execute_work * ew

##### Arguments

`fn`

  the function to execute

`ew`

  guaranteed storage for the execute work structure (must be available when the work executes)

##### Description

Executes the function immediately if process context is available, otherwise schedules the function for delayed execution.

##### Returns

0 - function was executed 1 - function was scheduled for execution

#### LINUX

Kernel Hackers Manual January 2008
destroy_workqueue
9
2.6.24-rc6-git8

#### destroy_workqueue

safely terminate a workqueue

##### Synopsis

       void destroy_workqueue
       struct workqueue_struct * wq

##### Arguments

`wq`

  target workqueue

##### Description

Safely destroy a workqueue. All work currently pending will be done first.

### Internal Functions

#### LINUX

Kernel Hackers Manual January 2008
reparent_to_kthreadd
9
2.6.24-rc6-git8

#### reparent_to_kthreadd

Reparent the calling kernel thread to kthreadd

##### Synopsis

       void reparent_to_kthreadd
        void

##### Arguments

`void`

  no arguments

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
sys_tgkill
9
2.6.24-rc6-git8

#### sys_tgkill

send signal to one specific thread

##### Synopsis

       long sys_tgkill
       int tgid
       int pid
       int sig

##### Arguments

`tgid`

  the thread group ID of the thread

`pid`

  the PID of the thread

`sig`

  signal to be sent

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
kthread_run
9
2.6.24-rc6-git8

#### kthread_run

create and wake a thread.

##### Synopsis

        kthread_run
        threadfn
        data
        namefmt
        ...

##### Arguments

`threadfn`

  the function to run until signal_pending(current).

`data`

  data ptr for `threadfn`.

`namefmt`

  printf-style name for the thread.

`...`

  variable arguments

##### Description

Convenient wrapper for `kthread_create` followed by `wake_up_process`. Returns the kthread or ERR_PTR(-ENOMEM).

#### LINUX

Kernel Hackers Manual January 2008
kthread_should_stop
9
2.6.24-rc6-git8

#### kthread_should_stop

should this kthread return now?

##### Synopsis

       int kthread_should_stop
        void

##### Arguments

`void`

  no arguments

##### Description

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`.

#### LINUX

Kernel Hackers Manual January 2008
kthread_create
9
2.6.24-rc6-git8

#### kthread_create

create a kthread.

##### Synopsis

       struct task_struct * kthread_create
       int (*threadfn)
         void *data
       void * data
       const char namefmt[]
        ...

##### Arguments

`threadfn`

  the function to run until signal_pending(current).

`data`

  data ptr for `threadfn`.

`namefmt[]`

  printf-style name for the thread.

`...`

  variable arguments

##### Description

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).

#### LINUX

Kernel Hackers Manual January 2008
kthread_bind
9
2.6.24-rc6-git8

#### kthread_bind

bind a just-created kthread to a cpu.

##### Synopsis

       void kthread_bind
       struct task_struct * k
       unsigned int cpu

##### Arguments

`k`

  thread created by `kthread_create`.

`cpu`

  cpu (might not be online, must be possible) for `k` to run on.

##### Description

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`).

#### LINUX

Kernel Hackers Manual January 2008
kthread_stop
9
2.6.24-rc6-git8

#### kthread_stop

stop a thread created by `kthread_create`.

##### Synopsis

       int kthread_stop
       struct task_struct * k

##### Arguments

`k`

  thread created by `kthread_create`.

##### Description

Sets `kthread_should_stop` for `k` to return true, wakes it, and waits for it to exit. Your `threadfn` must not call `do_exit` itself if you use this function! This can also be called after `kthread_create` instead of calling `wake_up_process`: the thread will exit without calling `threadfn`.

Returns the result of `threadfn`, or `-EINTR` if `wake_up_process` was never called.

### Kernel objects manipulation

#### LINUX

Kernel Hackers Manual January 2008
kobject_get_path
9
2.6.24-rc6-git8

#### kobject_get_path

generate and return the path associated with a given kobj and kset pair.

##### Synopsis

       char * kobject_get_path
       struct kobject * kobj
       gfp_t gfp_mask

##### Arguments

`kobj`

  kobject in question, with which to build the path

`gfp_mask`

  the allocation type used to allocate the path

##### Description

The result must be freed by the caller with `kfree`.

##### Description

The result must be freed by the caller with `kfree`.

#### LINUX

Kernel Hackers Manual January 2008
kobject_init
9
2.6.24-rc6-git8

#### kobject_init

initialize object.

##### Synopsis

       void kobject_init
       struct kobject * kobj

##### Arguments

`kobj`

  object in question.

#### LINUX

Kernel Hackers Manual January 2008
kobject_add
9
2.6.24-rc6-git8

#### kobject_add

add an object to the hierarchy.

##### Synopsis

       int kobject_add
       struct kobject * kobj

##### Arguments

`kobj`

  object.

#### LINUX

Kernel Hackers Manual January 2008
kobject_register
9
2.6.24-rc6-git8

#### kobject_register

initialize and add an object.

##### Synopsis

       int kobject_register
       struct kobject * kobj

##### Arguments

`kobj`

  object in question.

#### LINUX

Kernel Hackers Manual January 2008
kobject_set_name
9
2.6.24-rc6-git8

#### kobject_set_name

Set the name of a kobject

##### Synopsis

       int kobject_set_name
       struct kobject * kobj
       const char * fmt
        ...

##### Arguments

`kobj`

  kobject to name

`fmt`

  format string used to build the name

`...`

  variable arguments

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
kobject_del
9
2.6.24-rc6-git8

#### kobject_del

unlink kobject from hierarchy.

##### Synopsis

       void kobject_del
       struct kobject * kobj

##### Arguments

`kobj`

  object.

#### LINUX

Kernel Hackers Manual January 2008
kobject_unregister
9
2.6.24-rc6-git8

#### kobject_unregister

remove object from hierarchy and decrement refcount.

##### Synopsis

       void kobject_unregister
       struct kobject * kobj

##### Arguments

`kobj`

  object going away.

#### LINUX

Kernel Hackers Manual January 2008
kobject_get
9
2.6.24-rc6-git8

#### kobject_get

increment refcount for object.

##### Synopsis

       struct kobject * kobject_get
       struct kobject * kobj

##### Arguments

`kobj`

  object.

#### LINUX

Kernel Hackers Manual January 2008
kobject_put
9
2.6.24-rc6-git8

#### kobject_put

decrement refcount for object.

##### Synopsis

       void kobject_put
       struct kobject * kobj

##### Arguments

`kobj`

  object.

##### Description

Decrement the refcount, and if 0, call `kobject_cleanup`.

#### LINUX

Kernel Hackers Manual January 2008
kset_register
9
2.6.24-rc6-git8

#### kset_register

initialize and add a kset.

##### Synopsis

       int kset_register
       struct kset * k

##### Arguments

`k`

  kset.

#### LINUX

Kernel Hackers Manual January 2008
kset_unregister
9
2.6.24-rc6-git8

#### kset_unregister

remove a kset.

##### Synopsis

       void kset_unregister
       struct kset * k

##### Arguments

`k`

  kset.

#### LINUX

Kernel Hackers Manual January 2008
subsys_create_file
9
2.6.24-rc6-git8

#### subsys_create_file

export sysfs attribute file.

##### Synopsis

       int subsys_create_file
       struct kset * s
       struct subsys_attribute * a

##### Arguments

`s`

  subsystem.

`a`

  subsystem attribute descriptor.

### Kernel utility functions

#### LINUX

Kernel Hackers Manual January 2008
upper_32_bits
9
2.6.24-rc6-git8

#### upper_32_bits

return bits 32-63 of a number

##### Synopsis

        upper_32_bits
        n

##### Arguments

`n`

  the number we're accessing

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
container_of
9
2.6.24-rc6-git8

#### container_of

cast a member of a structure out to the containing structure

##### Synopsis

        container_of
        ptr
        type
        member

##### Arguments

`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.

#### LINUX

Kernel Hackers Manual January 2008
printk
9
2.6.24-rc6-git8

#### printk

print a kernel message

##### Synopsis

       int printk
       const char * fmt
        ...

##### Arguments

`fmt`

  format string

`...`

  variable arguments

##### Description

This is `printk`. It can be called from any context. We want it to work. Be aware of the fact that if oops_in_progress is not set, we might try to wake klogd up which could deadlock on runqueue lock if `printk` is called from scheduler code.

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.

##### See also

printf(3)

#### LINUX

Kernel Hackers Manual January 2008
acquire_console_sem
9
2.6.24-rc6-git8

#### acquire_console_sem

lock the console system for exclusive use.

##### Synopsis

       void acquire_console_sem
        void

##### Arguments

`void`

  no arguments

##### Description

Acquires a semaphore which guarantees that the caller has exclusive access to the console system and the console_drivers list.

Can sleep, returns nothing.

#### LINUX

Kernel Hackers Manual January 2008
release_console_sem
9
2.6.24-rc6-git8

#### release_console_sem

unlock the console system

##### Synopsis

       void release_console_sem
        void

##### Arguments

`void`

  no arguments

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
console_conditional_schedule
9
2.6.24-rc6-git8

#### console_conditional_schedule

yield the CPU if required

##### Synopsis

       void __sched console_conditional_schedule
        void

##### Arguments

`void`

  no arguments

##### Description

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`.

#### LINUX

Kernel Hackers Manual January 2008
printk_timed_ratelimit
9
2.6.24-rc6-git8

#### printk_timed_ratelimit

caller-controlled printk ratelimiting

##### Synopsis

       bool printk_timed_ratelimit
       unsigned long * caller_jiffies
       unsigned int interval_msecs

##### Arguments

`caller_jiffies`

  pointer to caller's state

`interval_msecs`

  minimum interval between prints

##### Description

`printk_timed_ratelimit` returns true if more than `interval_msecs` milliseconds have elapsed since the last time `printk_timed_ratelimit` returned true.

#### LINUX

Kernel Hackers Manual January 2008
panic
9
2.6.24-rc6-git8

#### panic

halt the system

##### Synopsis

       NORET_TYPE void panic
       const char * fmt
        ...

##### Arguments

`fmt`

  The text string to print

`...`

  variable arguments

##### Description

Display a message, then perform cleanups.

This function never returns.

#### LINUX

Kernel Hackers Manual January 2008
emergency_restart
9
2.6.24-rc6-git8

#### emergency_restart

reboot the system

##### Synopsis

       void emergency_restart
        void

##### Arguments

`void`

  no arguments

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
kernel_restart
9
2.6.24-rc6-git8

#### kernel_restart

reboot the system

##### Synopsis

       void kernel_restart
       char * cmd

##### Arguments

`cmd`

  pointer to buffer containing command to execute for restart or `NULL`

##### Description

Shutdown everything and perform a clean reboot. This is not safe to call in interrupt context.

#### LINUX

Kernel Hackers Manual January 2008
kernel_halt
9
2.6.24-rc6-git8

#### kernel_halt

halt the system

##### Synopsis

       void kernel_halt
        void

##### Arguments

`void`

  no arguments

##### Description

Shutdown everything and perform a clean system halt.

#### LINUX

Kernel Hackers Manual January 2008
kernel_power_off
9
2.6.24-rc6-git8

#### kernel_power_off

power_off the system

##### Synopsis

       void kernel_power_off
        void

##### Arguments

`void`

  no arguments

##### Description

Shutdown everything and perform a clean system power_off.

#### LINUX

Kernel Hackers Manual January 2008
orderly_poweroff
9
2.6.24-rc6-git8

#### orderly_poweroff

Trigger an orderly system poweroff

##### Synopsis

       int orderly_poweroff
       bool force

##### Arguments

`force`

  force poweroff if command execution fails

##### Description

This may be called from any context to trigger a system shutdown. If the orderly shutdown fails, it will force an immediate shutdown.

#### LINUX

Kernel Hackers Manual January 2008
call_rcu
9
2.6.24-rc6-git8

#### call_rcu

Queue an RCU callback for invocation after a grace period.

##### Synopsis

       void fastcall call_rcu
       struct rcu_head * head
       void (*func)
         struct rcu_head *rcu

##### Arguments

`head`

  structure to be used for queueing the RCU updates.

`func`

  actual update function to be invoked after the grace period

##### Description

The update function will be invoked some time after a full grace period elapses, in other words after all currently executing RCU read-side critical sections have completed. RCU read-side critical sections are delimited by `rcu_read_lock` and `rcu_read_unlock`, and may be nested.

#### LINUX

Kernel Hackers Manual January 2008
call_rcu_bh
9
2.6.24-rc6-git8

#### call_rcu_bh

Queue an RCU for invocation after a quicker grace period.

##### Synopsis

       void fastcall call_rcu_bh
       struct rcu_head * head
       void (*func)
         struct rcu_head *rcu

##### Arguments

`head`

  structure to be used for queueing the RCU updates.

`func`

  actual update function to be invoked after the grace period

##### Description

The update function will be invoked some time after a full grace period elapses, in other words after all currently executing RCU read-side critical sections have completed. `call_rcu_bh` assumes that the read-side critical sections end on completion of a softirq handler. This means that read-side critical sections in process context must not be interrupted by softirqs. This interface is to be used when most of the read-side critical sections are in softirq context. RCU read-side critical sections are delimited by `rcu_read_lock` and `rcu_read_unlock`, * if in interrupt context or `rcu_read_lock_bh` and `rcu_read_unlock_bh`, if in process context. These may be nested.

#### LINUX

Kernel Hackers Manual January 2008
rcu_barrier
9
2.6.24-rc6-git8

#### rcu_barrier

Wait until all the in-flight RCUs are complete.

##### Synopsis

       void rcu_barrier
        void

##### Arguments

`void`

  no arguments

#### LINUX

Kernel Hackers Manual January 2008
synchronize_rcu
9
2.6.24-rc6-git8

#### synchronize_rcu

wait until a grace period has elapsed.

##### Synopsis

       void synchronize_rcu
        void

##### Arguments

`void`

  no arguments

##### Description

Control will return to the caller some time after a full grace period has elapsed, in other words after all currently executing RCU read-side critical sections have completed. RCU read-side critical sections are delimited by `rcu_read_lock` and `rcu_read_unlock`, and may be nested.

If your read-side code is not protected by `rcu_read_lock`, do -not- use `synchronize_rcu`.

### Device Resource Management

#### LINUX

Kernel Hackers Manual January 2008
devres_alloc
9
2.6.24-rc6-git8

#### devres_alloc

Allocate device resource data

##### Synopsis

       void * devres_alloc
       dr_release_t release
       size_t size
       gfp_t gfp

##### Arguments

`release`

  Release function devres will be associated with

`size`

  Allocation size

`gfp`

  Allocation flags

##### Description

Allocate devres of `size` bytes. The allocated area is zeroed, then associated with `release`. The returned pointer can be passed to other devres_*() functions.

##### RETURNS

Pointer to allocated devres on success, NULL on failure.

#### LINUX

Kernel Hackers Manual January 2008
devres_free
9
2.6.24-rc6-git8

#### devres_free

Free device resource data

##### Synopsis

       void devres_free
       void * res

##### Arguments

`res`

  Pointer to devres data to free

##### Description

Free devres created with `devres_alloc`.

#### LINUX

Kernel Hackers Manual January 2008
devres_add
9
2.6.24-rc6-git8

#### devres_add

Register device resource

##### Synopsis

       void devres_add
       struct device * dev
       void * res

##### Arguments

`dev`

  Device to add resource to

`res`

  Resource to register

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
devres_find
9
2.6.24-rc6-git8

#### devres_find

Find device resource

##### Synopsis

       void * devres_find
       struct device * dev
       dr_release_t release
       dr_match_t match
       void * match_data

##### Arguments

`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

##### Description

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.

##### RETURNS

Pointer to found devres, NULL if not found.

#### LINUX

Kernel Hackers Manual January 2008
devres_get
9
2.6.24-rc6-git8

#### devres_get

Find devres, if non-existent, add one atomically

##### Synopsis

       void * devres_get
       struct device * dev
       void * new_res
       dr_match_t match
       void * match_data

##### Arguments

`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

##### Description

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.

##### RETURNS

Pointer to found or added devres.

#### LINUX

Kernel Hackers Manual January 2008
devres_remove
9
2.6.24-rc6-git8

#### devres_remove

Find a device resource and remove it

##### Synopsis

       void * devres_remove
       struct device * dev
       dr_release_t release
       dr_match_t match
       void * match_data

##### Arguments

`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

##### Description

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.

##### RETURNS

Pointer to removed devres on success, NULL if not found.

#### LINUX

Kernel Hackers Manual January 2008
devres_destroy
9
2.6.24-rc6-git8

#### devres_destroy

Find a device resource and destroy it

##### Synopsis

       int devres_destroy
       struct device * dev
       dr_release_t release
       dr_match_t match
       void * match_data

##### Arguments

`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

##### Description

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.

##### RETURNS

0 if devres is found and freed, -ENOENT if not found.

#### LINUX

Kernel Hackers Manual January 2008
devres_open_group
9
2.6.24-rc6-git8

#### devres_open_group

Open a new devres group

##### Synopsis

       void * devres_open_group
       struct device * dev
       void * id
       gfp_t gfp

##### Arguments

`dev`

  Device to open devres group for

`id`

  Separator ID

`gfp`

  Allocation flags

##### Description

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.

##### RETURNS

ID of the new group, NULL on failure.

#### LINUX

Kernel Hackers Manual January 2008
devres_close_group
9
2.6.24-rc6-git8

#### devres_close_group

Close a devres group

##### Synopsis

       void devres_close_group
       struct device * dev
       void * id

##### Arguments

`dev`

  Device to close devres group for

`id`

  ID of target group, can be NULL

##### Description

Close the group identified by `id`. If `id` is NULL, the latest open group is selected.

#### LINUX

Kernel Hackers Manual January 2008
devres_remove_group
9
2.6.24-rc6-git8

#### devres_remove_group

Remove a devres group

##### Synopsis

       void devres_remove_group
       struct device * dev
       void * id

##### Arguments

`dev`

  Device to remove group for

`id`

  ID of target group, can be NULL

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
devres_release_group
9
2.6.24-rc6-git8

#### devres_release_group

Release resources in a devres group

##### Synopsis

       int devres_release_group
       struct device * dev
       void * id

##### Arguments

`dev`

  Device to release group for

`id`

  ID of target group, can be NULL

##### Description

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.

##### RETURNS

The number of released non-group resources.

#### LINUX

Kernel Hackers Manual January 2008
devm_kzalloc
9
2.6.24-rc6-git8

#### devm_kzalloc

Resource-managed kzalloc

##### Synopsis

       void * devm_kzalloc
       struct device * dev
       size_t size
       gfp_t gfp

##### Arguments

`dev`

  Device to allocate memory for

`size`

  Allocation size

`gfp`

  Allocation gfp flags

##### Description

Managed kzalloc. Memory allocated with this function is automatically freed on driver detach. Like all other devres resources, guaranteed alignment is unsigned long long.

##### RETURNS

Pointer to allocated memory on success, NULL on failure.

#### LINUX

Kernel Hackers Manual January 2008
devm_kfree
9
2.6.24-rc6-git8

#### devm_kfree

Resource-managed kfree

##### Synopsis

       void devm_kfree
       struct device * dev
       void * p

##### Arguments

`dev`

  Device this memory belongs to

`p`

  Memory to free

##### Description

Free memory allocated with `dev_kzalloc`.

## Data Types

### Doubly Linked Lists

#### LINUX

Kernel Hackers Manual January 2008
list_add
9
2.6.24-rc6-git8

#### list_add

add a new entry

##### Synopsis

       void list_add
       struct list_head * new
       struct list_head * head

##### Arguments

`new`

  new entry to be added

`head`

  list head to add it after

##### Description

Insert a new entry after the specified head. This is good for implementing stacks.

#### LINUX

Kernel Hackers Manual January 2008
list_add_tail
9
2.6.24-rc6-git8

#### list_add_tail

add a new entry

##### Synopsis

       void list_add_tail
       struct list_head * new
       struct list_head * head

##### Arguments

`new`

  new entry to be added

`head`

  list head to add it before

##### Description

Insert a new entry before the specified head. This is useful for implementing queues.

#### LINUX

Kernel Hackers Manual January 2008
list_add_rcu
9
2.6.24-rc6-git8

#### list_add_rcu

add a new entry to rcu-protected list

##### Synopsis

       void list_add_rcu
       struct list_head * new
       struct list_head * head

##### Arguments

`new`

  new entry to be added

`head`

  list head to add it after

##### Description

Insert a new entry after the specified head. This is good for implementing stacks.

The caller must take whatever precautions are necessary (such as holding appropriate locks) to avoid racing with another list-mutation primitive, such as `list_add_rcu` or `list_del_rcu`, running on this same list. However, it is perfectly legal to run concurrently with the _rcu list-traversal primitives, such as `list_for_each_entry_rcu`.

#### LINUX

Kernel Hackers Manual January 2008
list_add_tail_rcu
9
2.6.24-rc6-git8

#### list_add_tail_rcu

add a new entry to rcu-protected list

##### Synopsis

       void list_add_tail_rcu
       struct list_head * new
       struct list_head * head

##### Arguments

`new`

  new entry to be added

`head`

  list head to add it before

##### Description

Insert a new entry before the specified head. This is useful for implementing queues.

The caller must take whatever precautions are necessary (such as holding appropriate locks) to avoid racing with another list-mutation primitive, such as `list_add_tail_rcu` or `list_del_rcu`, running on this same list. However, it is perfectly legal to run concurrently with the _rcu list-traversal primitives, such as `list_for_each_entry_rcu`.

#### LINUX

Kernel Hackers Manual January 2008
list_del
9
2.6.24-rc6-git8

#### list_del

deletes entry from list.

##### Synopsis

       void list_del
       struct list_head * entry

##### Arguments

`entry`

  the element to delete from the list.

##### Note

`list_empty` on entry does not return true after this, the entry is in an undefined state.

#### LINUX

Kernel Hackers Manual January 2008
list_del_rcu
9
2.6.24-rc6-git8

#### list_del_rcu

deletes entry from list without re-initialization

##### Synopsis

       void list_del_rcu
       struct list_head * entry

##### Arguments

`entry`

  the element to delete from the list.

##### Note

`list_empty` on entry does not return true after this, the entry is in an undefined state. It is useful for RCU based lockfree traversal.

In particular, it means that we can not poison the forward pointers that may still be used for walking the list.

The caller must take whatever precautions are necessary (such as holding appropriate locks) to avoid racing with another list-mutation primitive, such as `list_del_rcu` or `list_add_rcu`, running on this same list. However, it is perfectly legal to run concurrently with the _rcu list-traversal primitives, such as `list_for_each_entry_rcu`.

Note that the caller is not permitted to immediately free the newly deleted entry. Instead, either `synchronize_rcu` or `call_rcu` must be used to defer freeing until an RCU grace period has elapsed.

#### LINUX

Kernel Hackers Manual January 2008
list_replace
9
2.6.24-rc6-git8

#### list_replace

replace old entry by new one

##### Synopsis

       void list_replace
       struct list_head * old
       struct list_head * new

##### Arguments

`old`

  the element to be replaced

`new`

  the new element to insert

##### Description

If `old` was empty, it will be overwritten.

#### LINUX

Kernel Hackers Manual January 2008
list_replace_rcu
9
2.6.24-rc6-git8

#### list_replace_rcu

replace old entry by new one

##### Synopsis

       void list_replace_rcu
       struct list_head * old
       struct list_head * new

##### Arguments

`old`

  the element to be replaced

`new`

  the new element to insert

##### Description

The `old` entry will be replaced with the `new` entry atomically.

##### Note

`old` should not be empty.

#### LINUX

Kernel Hackers Manual January 2008
list_del_init
9
2.6.24-rc6-git8

#### list_del_init

deletes entry from list and reinitialize it.

##### Synopsis

       void list_del_init
       struct list_head * entry

##### Arguments

`entry`

  the element to delete from the list.

#### LINUX

Kernel Hackers Manual January 2008
list_move
9
2.6.24-rc6-git8

#### list_move

delete from one list and add as another's head

##### Synopsis

       void list_move
       struct list_head * list
       struct list_head * head

##### Arguments

`list`

  the entry to move

`head`

  the head that will precede our entry

#### LINUX

Kernel Hackers Manual January 2008
list_move_tail
9
2.6.24-rc6-git8

#### list_move_tail

delete from one list and add as another's tail

##### Synopsis

       void list_move_tail
       struct list_head * list
       struct list_head * head

##### Arguments

`list`

  the entry to move

`head`

  the head that will follow our entry

#### LINUX

Kernel Hackers Manual January 2008
list_is_last
9
2.6.24-rc6-git8

#### list_is_last

tests whether `list` is the last entry in list `head`

##### Synopsis

       int list_is_last
       const struct list_head * list
       const struct list_head * head

##### Arguments

`list`

  the entry to test

`head`

  the head of the list

#### LINUX

Kernel Hackers Manual January 2008
list_empty
9
2.6.24-rc6-git8

#### list_empty

tests whether a list is empty

##### Synopsis

       int list_empty
       const struct list_head * head

##### Arguments

`head`

  the list to test.

#### LINUX

Kernel Hackers Manual January 2008
list_empty_careful
9
2.6.24-rc6-git8

#### list_empty_careful

tests whether a list is empty and not being modified

##### Synopsis

       int list_empty_careful
       const struct list_head * head

##### Arguments

`head`

  the list to test

##### Description

tests whether a list is empty _and_ checks that no other CPU might be in the process of modifying either member (next or prev)

##### NOTE

using `list_empty_careful` without synchronization can only be safe if the only activity that can happen to the list entry is `list_del_init`. Eg. it cannot be used if another CPU could re-`list_add` it.

#### LINUX

Kernel Hackers Manual January 2008
list_splice
9
2.6.24-rc6-git8

#### list_splice

join two lists

##### Synopsis

       void list_splice
       struct list_head * list
       struct list_head * head

##### Arguments

`list`

  the new list to add.

`head`

  the place to add it in the first list.

#### LINUX

Kernel Hackers Manual January 2008
list_splice_init
9
2.6.24-rc6-git8

#### list_splice_init

join two lists and reinitialise the emptied list.

##### Synopsis

       void list_splice_init
       struct list_head * list
       struct list_head * head

##### Arguments

`list`

  the new list to add.

`head`

  the place to add it in the first list.

##### Description

The list at `list` is reinitialised

#### LINUX

Kernel Hackers Manual January 2008
list_splice_init_rcu
9
2.6.24-rc6-git8

#### list_splice_init_rcu

splice an RCU-protected list into an existing list.

##### Synopsis

       void list_splice_init_rcu
       struct list_head * list
       struct list_head * head
       void (*sync)
         void

##### Arguments

`list`

  the RCU-protected list to splice

`head`

  the place in the list to splice the first list into

`sync`

  function to sync: `synchronize_rcu`, `synchronize_sched`, ...

##### Description

`head` can be RCU-read traversed concurrently with this function.

Note that this function blocks.

##### Important note

the caller must take whatever action is necessary to prevent any other updates to `head`. In principle, it is possible to modify the list as soon as `sync` begins execution. If this sort of thing becomes necessary, an alternative version based on `call_rcu` could be created. But only if -really- needed -- there is no shortage of RCU API members.

#### LINUX

Kernel Hackers Manual January 2008
list_entry
9
2.6.24-rc6-git8

#### list_entry

get the struct for this entry

##### Synopsis

        list_entry
        ptr
        type
        member

##### Arguments

`ptr`

  the &struct list_head pointer.

`type`

  the type of the struct this is embedded in.

`member`

  the name of the list_struct within the struct.

#### LINUX

Kernel Hackers Manual January 2008
list_first_entry
9
2.6.24-rc6-git8

#### list_first_entry

get the first element from a list

##### Synopsis

        list_first_entry
        ptr
        type
        member

##### Arguments

`ptr`

  the list head to take the element from.

`type`

  the type of the struct this is embedded in.

`member`

  the name of the list_struct within the struct.

##### Description

Note, that list is expected to be not empty.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each
9
2.6.24-rc6-git8

#### list_for_each

iterate over a list

##### Synopsis

        list_for_each
        pos
        head

##### Arguments

`pos`

  the &struct list_head to use as a loop cursor.

`head`

  the head for your list.

#### LINUX

Kernel Hackers Manual January 2008
__list_for_each
9
2.6.24-rc6-git8

#### __list_for_each

iterate over a list

##### Synopsis

        __list_for_each
        pos
        head

##### Arguments

`pos`

  the &struct list_head to use as a loop cursor.

`head`

  the head for your list.

##### Description

This variant differs from `list_for_each` in that it's the simplest possible list iteration code, no prefetching is done. Use this for code that knows the list to be very short (empty or 1 entry) most of the time.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_prev
9
2.6.24-rc6-git8

#### list_for_each_prev

iterate over a list backwards

##### Synopsis

        list_for_each_prev
        pos
        head

##### Arguments

`pos`

  the &struct list_head to use as a loop cursor.

`head`

  the head for your list.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_safe
9
2.6.24-rc6-git8

#### list_for_each_safe

iterate over a list safe against removal of list entry

##### Synopsis

        list_for_each_safe
        pos
        n
        head

##### Arguments

`pos`

  the &struct list_head to use as a loop cursor.

`n`

  another &struct list_head to use as temporary storage

`head`

  the head for your list.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_prev_safe
9
2.6.24-rc6-git8

#### list_for_each_prev_safe

iterate over a list backwards safe against removal of list entry

##### Synopsis

        list_for_each_prev_safe
        pos
        n
        head

##### Arguments

`pos`

  the &struct list_head to use as a loop cursor.

`n`

  another &struct list_head to use as temporary storage

`head`

  the head for your list.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_entry
9
2.6.24-rc6-git8

#### list_for_each_entry

iterate over list of given type

##### Synopsis

        list_for_each_entry
        pos
        head
        member

##### Arguments

`pos`

  the type * to use as a loop cursor.

`head`

  the head for your list.

`member`

  the name of the list_struct within the struct.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_entry_reverse
9
2.6.24-rc6-git8

#### list_for_each_entry_reverse

iterate backwards over list of given type.

##### Synopsis

        list_for_each_entry_reverse
        pos
        head
        member

##### Arguments

`pos`

  the type * to use as a loop cursor.

`head`

  the head for your list.

`member`

  the name of the list_struct within the struct.

#### LINUX

Kernel Hackers Manual January 2008
list_prepare_entry
9
2.6.24-rc6-git8

#### list_prepare_entry

prepare a pos entry for use in `list_for_each_entry_continue`

##### Synopsis

        list_prepare_entry
        pos
        head
        member

##### Arguments

`pos`

  the type * to use as a start point

`head`

  the head of the list

`member`

  the name of the list_struct within the struct.

##### Description

Prepares a pos entry for use as a start point in `list_for_each_entry_continue`.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_entry_continue
9
2.6.24-rc6-git8

#### list_for_each_entry_continue

continue iteration over list of given type

##### Synopsis

        list_for_each_entry_continue
        pos
        head
        member

##### Arguments

`pos`

  the type * to use as a loop cursor.

`head`

  the head for your list.

`member`

  the name of the list_struct within the struct.

##### Description

Continue to iterate over list of given type, continuing after the current position.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_entry_continue_reverse
9
2.6.24-rc6-git8

#### list_for_each_entry_continue_reverse

iterate backwards from the given point

##### Synopsis

        list_for_each_entry_continue_reverse
        pos
        head
        member

##### Arguments

`pos`

  the type * to use as a loop cursor.

`head`

  the head for your list.

`member`

  the name of the list_struct within the struct.

##### Description

Start to iterate over list of given type backwards, continuing after the current position.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_entry_from
9
2.6.24-rc6-git8

#### list_for_each_entry_from

iterate over list of given type from the current point

##### Synopsis

        list_for_each_entry_from
        pos
        head
        member

##### Arguments

`pos`

  the type * to use as a loop cursor.

`head`

  the head for your list.

`member`

  the name of the list_struct within the struct.

##### Description

Iterate over list of given type, continuing from current position.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_entry_safe
9
2.6.24-rc6-git8

#### list_for_each_entry_safe

iterate over list of given type safe against removal of list entry

##### Synopsis

        list_for_each_entry_safe
        pos
        n
        head
        member

##### Arguments

`pos`

  the type * to use as a loop cursor.

`n`

  another type * to use as temporary storage

`head`

  the head for your list.

`member`

  the name of the list_struct within the struct.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_entry_safe_continue
9
2.6.24-rc6-git8

#### list_for_each_entry_safe_continue

##### Synopsis

        list_for_each_entry_safe_continue
        pos
        n
        head
        member

##### Arguments

`pos`

  the type * to use as a loop cursor.

`n`

  another type * to use as temporary storage

`head`

  the head for your list.

`member`

  the name of the list_struct within the struct.

##### Description

Iterate over list of given type, continuing after current point, safe against removal of list entry.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_entry_safe_from
9
2.6.24-rc6-git8

#### list_for_each_entry_safe_from

##### Synopsis

        list_for_each_entry_safe_from
        pos
        n
        head
        member

##### Arguments

`pos`

  the type * to use as a loop cursor.

`n`

  another type * to use as temporary storage

`head`

  the head for your list.

`member`

  the name of the list_struct within the struct.

##### Description

Iterate over list of given type from current point, safe against removal of list entry.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_entry_safe_reverse
9
2.6.24-rc6-git8

#### list_for_each_entry_safe_reverse

##### Synopsis

        list_for_each_entry_safe_reverse
        pos
        n
        head
        member

##### Arguments

`pos`

  the type * to use as a loop cursor.

`n`

  another type * to use as temporary storage

`head`

  the head for your list.

`member`

  the name of the list_struct within the struct.

##### Description

Iterate backwards over list of given type, safe against removal of list entry.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_rcu
9
2.6.24-rc6-git8

#### list_for_each_rcu

iterate over an rcu-protected list

##### Synopsis

        list_for_each_rcu
        pos
        head

##### Arguments

`pos`

  the &struct list_head to use as a loop cursor.

`head`

  the head for your list.

##### Description

This list-traversal primitive may safely run concurrently with the _rcu list-mutation primitives such as `list_add_rcu` as long as the traversal is guarded by `rcu_read_lock`.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_safe_rcu
9
2.6.24-rc6-git8

#### list_for_each_safe_rcu

##### Synopsis

        list_for_each_safe_rcu
        pos
        n
        head

##### Arguments

`pos`

  the &struct list_head to use as a loop cursor.

`n`

  another &struct list_head to use as temporary storage

`head`

  the head for your list.

##### Description

Iterate over an rcu-protected list, safe against removal of list entry.

This list-traversal primitive may safely run concurrently with the _rcu list-mutation primitives such as `list_add_rcu` as long as the traversal is guarded by `rcu_read_lock`.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_entry_rcu
9
2.6.24-rc6-git8

#### list_for_each_entry_rcu

iterate over rcu list of given type

##### Synopsis

        list_for_each_entry_rcu
        pos
        head
        member

##### Arguments

`pos`

  the type * to use as a loop cursor.

`head`

  the head for your list.

`member`

  the name of the list_struct within the struct.

##### Description

This list-traversal primitive may safely run concurrently with the _rcu list-mutation primitives such as `list_add_rcu` as long as the traversal is guarded by `rcu_read_lock`.

#### LINUX

Kernel Hackers Manual January 2008
list_for_each_continue_rcu
9
2.6.24-rc6-git8

#### list_for_each_continue_rcu

##### Synopsis

        list_for_each_continue_rcu
        pos
        head

##### Arguments

`pos`

  the &struct list_head to use as a loop cursor.

`head`

  the head for your list.

##### Description

Iterate over an rcu-protected list, continuing after current point.

This list-traversal primitive may safely run concurrently with the _rcu list-mutation primitives such as `list_add_rcu` as long as the traversal is guarded by `rcu_read_lock`.

#### LINUX

Kernel Hackers Manual January 2008
hlist_del_rcu
9
2.6.24-rc6-git8

#### hlist_del_rcu

deletes entry from hash list without re-initialization

##### Synopsis

       void hlist_del_rcu
       struct hlist_node * n

##### Arguments

`n`

  the element to delete from the hash list.

##### Note

`list_unhashed` on entry does not return true after this, the entry is in an undefined state. It is useful for RCU based lockfree traversal.

In particular, it means that we can not poison the forward pointers that may still be used for walking the hash list.

The caller must take whatever precautions are necessary (such as holding appropriate locks) to avoid racing with another list-mutation primitive, such as `hlist_add_head_rcu` or `hlist_del_rcu`, running on this same list. However, it is perfectly legal to run concurrently with the _rcu list-traversal primitives, such as `hlist_for_each_entry`.

#### LINUX

Kernel Hackers Manual January 2008
hlist_replace_rcu
9
2.6.24-rc6-git8

#### hlist_replace_rcu

replace old entry by new one

##### Synopsis

       void hlist_replace_rcu
       struct hlist_node * old
       struct hlist_node * new

##### Arguments

`old`

  the element to be replaced

`new`

  the new element to insert

##### Description

The `old` entry will be replaced with the `new` entry atomically.

#### LINUX

Kernel Hackers Manual January 2008
hlist_add_head_rcu
9
2.6.24-rc6-git8

#### hlist_add_head_rcu

##### Synopsis

       void hlist_add_head_rcu
       struct hlist_node * n
       struct hlist_head * h

##### Arguments

`n`

  the element to add to the hash list.

`h`

  the list to add to.

##### Description

Adds the specified element to the specified hlist, while permitting racing traversals.

The caller must take whatever precautions are necessary (such as holding appropriate locks) to avoid racing with another list-mutation primitive, such as `hlist_add_head_rcu` or `hlist_del_rcu`, running on this same list. However, it is perfectly legal to run concurrently with the _rcu list-traversal primitives, such as `hlist_for_each_entry_rcu`, used to prevent memory-consistency problems on Alpha CPUs. Regardless of the type of CPU, the list-traversal primitive must be guarded by `rcu_read_lock`.

#### LINUX

Kernel Hackers Manual January 2008
hlist_add_before_rcu
9
2.6.24-rc6-git8

#### hlist_add_before_rcu

##### Synopsis

       void hlist_add_before_rcu
       struct hlist_node * n
       struct hlist_node * next

##### Arguments

`n`

  the new element to add to the hash list.

`next`

  the existing element to add the new element before.

##### Description

Adds the specified element to the specified hlist before the specified node while permitting racing traversals.

The caller must take whatever precautions are necessary (such as holding appropriate locks) to avoid racing with another list-mutation primitive, such as `hlist_add_head_rcu` or `hlist_del_rcu`, running on this same list. However, it is perfectly legal to run concurrently with the _rcu list-traversal primitives, such as `hlist_for_each_entry_rcu`, used to prevent memory-consistency problems on Alpha CPUs.

#### LINUX

Kernel Hackers Manual January 2008
hlist_add_after_rcu
9
2.6.24-rc6-git8

#### hlist_add_after_rcu

##### Synopsis

       void hlist_add_after_rcu
       struct hlist_node * prev
       struct hlist_node * n

##### Arguments

`prev`

  the existing element to add the new element after.

`n`

  the new element to add to the hash list.

##### Description

Adds the specified element to the specified hlist after the specified node while permitting racing traversals.

The caller must take whatever precautions are necessary (such as holding appropriate locks) to avoid racing with another list-mutation primitive, such as `hlist_add_head_rcu` or `hlist_del_rcu`, running on this same list. However, it is perfectly legal to run concurrently with the _rcu list-traversal primitives, such as `hlist_for_each_entry_rcu`, used to prevent memory-consistency problems on Alpha CPUs.

#### LINUX

Kernel Hackers Manual January 2008
hlist_for_each_entry
9
2.6.24-rc6-git8

#### hlist_for_each_entry

iterate over list of given type

##### Synopsis

        hlist_for_each_entry
        tpos
        pos
        head
        member

##### Arguments

`tpos`

  the type * to use as a loop cursor.

`pos`

  the &struct hlist_node to use as a loop cursor.

`head`

  the head for your list.

`member`

  the name of the hlist_node within the struct.

#### LINUX

Kernel Hackers Manual January 2008
hlist_for_each_entry_continue
9
2.6.24-rc6-git8

#### hlist_for_each_entry_continue

iterate over a hlist continuing after current point

##### Synopsis

        hlist_for_each_entry_continue
        tpos
        pos
        member

##### Arguments

`tpos`

  the type * to use as a loop cursor.

`pos`

  the &struct hlist_node to use as a loop cursor.

`member`

  the name of the hlist_node within the struct.

#### LINUX

Kernel Hackers Manual January 2008
hlist_for_each_entry_from
9
2.6.24-rc6-git8

#### hlist_for_each_entry_from

iterate over a hlist continuing from current point

##### Synopsis

        hlist_for_each_entry_from
        tpos
        pos
        member

##### Arguments

`tpos`

  the type * to use as a loop cursor.

`pos`

  the &struct hlist_node to use as a loop cursor.

`member`

  the name of the hlist_node within the struct.

#### LINUX

Kernel Hackers Manual January 2008
hlist_for_each_entry_safe
9
2.6.24-rc6-git8

#### hlist_for_each_entry_safe

iterate over list of given type safe against removal of list entry

##### Synopsis

        hlist_for_each_entry_safe
        tpos
        pos
        n
        head
        member

##### Arguments

`tpos`

  the type * to use as a loop cursor.

`pos`

  the &struct hlist_node to use as a loop cursor.

`n`

  another &struct hlist_node to use as temporary storage

`head`

  the head for your list.

`member`

  the name of the hlist_node within the struct.

#### LINUX

Kernel Hackers Manual January 2008
hlist_for_each_entry_rcu
9
2.6.24-rc6-git8

#### hlist_for_each_entry_rcu

iterate over rcu list of given type

##### Synopsis

        hlist_for_each_entry_rcu
        tpos
        pos
        head
        member

##### Arguments

`tpos`

  the type * to use as a loop cursor.

`pos`

  the &struct hlist_node to use as a loop cursor.

`head`

  the head for your list.

`member`

  the name of the hlist_node within the struct.

##### Description

This list-traversal primitive may safely run concurrently with the _rcu list-mutation primitives such as `hlist_add_head_rcu` as long as the traversal is guarded by `rcu_read_lock`.

## Basic C Library Functions

When writing drivers, you cannot in general use routines which are from the C Library. Some of the functions have been found generally useful and they are listed below. The behaviour of these functions may vary slightly from those defined by ANSI, and these deviations are noted in the text.

### String Conversions

#### LINUX

Kernel Hackers Manual January 2008
simple_strtoll
9
2.6.24-rc6-git8

#### simple_strtoll

convert a string to a signed long long

##### Synopsis

       long long simple_strtoll
       const char * cp
       char ** endp
       unsigned int base

##### Arguments

`cp`

  The start of the string

`endp`

  A pointer to the end of the parsed string will be placed here

`base`

  The number base to use

#### LINUX

Kernel Hackers Manual January 2008
simple_strtoul
9
2.6.24-rc6-git8

#### simple_strtoul

convert a string to an unsigned long

##### Synopsis

       unsigned long simple_strtoul
       const char * cp
       char ** endp
       unsigned int base

##### Arguments

`cp`

  The start of the string

`endp`

  A pointer to the end of the parsed string will be placed here

`base`

  The number base to use

#### LINUX

Kernel Hackers Manual January 2008
simple_strtol
9
2.6.24-rc6-git8

#### simple_strtol

convert a string to a signed long

##### Synopsis

       long simple_strtol
       const char * cp
       char ** endp
       unsigned int base

##### Arguments

`cp`

  The start of the string

`endp`

  A pointer to the end of the parsed string will be placed here

`base`

  The number base to use

#### LINUX

Kernel Hackers Manual January 2008
simple_strtoull
9
2.6.24-rc6-git8

#### simple_strtoull

convert a string to an unsigned long long

##### Synopsis

       unsigned long long simple_strtoull
       const char * cp
       char ** endp
       unsigned int base

##### Arguments

`cp`

  The start of the string

`endp`

  A pointer to the end of the parsed string will be placed here

`base`

  The number base to use

#### LINUX

Kernel Hackers Manual January 2008
vsnprintf
9
2.6.24-rc6-git8

#### vsnprintf

Format a string and place it in a buffer

##### Synopsis

       int vsnprintf
       char * buf
       size_t size
       const char * fmt
       va_list args

##### Arguments

`buf`

  The buffer to place the result into

`size`

  The size of the buffer, including the trailing null space

`fmt`

  The format string to use

`args`

  Arguments for the format string

##### Description

The return value is the number of characters which would be generated for the given input, excluding the trailing '\0', as per ISO C99. If you want to have the exact number of characters written into `buf` as return value (not including the trailing '\0'), use `vscnprintf`. If the return is greater than or equal to `size`, the resulting string is truncated.

Call this function if you are already dealing with a va_list. You probably want `snprintf` instead.

#### LINUX

Kernel Hackers Manual January 2008
vscnprintf
9
2.6.24-rc6-git8

#### vscnprintf

Format a string and place it in a buffer

##### Synopsis

       int vscnprintf
       char * buf
       size_t size
       const char * fmt
       va_list args

##### Arguments

`buf`

  The buffer to place the result into

`size`

  The size of the buffer, including the trailing null space

`fmt`

  The format string to use

`args`

  Arguments for the format string

##### Description

The return value is the number of characters which have been written into the `buf` not including the trailing '\0'. If `size` is <= 0 the function returns 0.

Call this function if you are already dealing with a va_list. You probably want `scnprintf` instead.

#### LINUX

Kernel Hackers Manual January 2008
snprintf
9
2.6.24-rc6-git8

#### snprintf

Format a string and place it in a buffer

##### Synopsis

       int snprintf
       char * buf
       size_t size
       const char * fmt
        ...

##### Arguments

`buf`

  The buffer to place the result into

`size`

  The size of the buffer, including the trailing null space

`fmt`

  The format string to use @...: Arguments for the format string

`...`

  variable arguments

##### Description

The return value is the number of characters which would be generated for the given input, excluding the trailing null, as per ISO C99. If the return is greater than or equal to `size`, the resulting string is truncated.

#### LINUX

Kernel Hackers Manual January 2008
scnprintf
9
2.6.24-rc6-git8

#### scnprintf

Format a string and place it in a buffer

##### Synopsis

       int scnprintf
       char * buf
       size_t size
       const char * fmt
        ...

##### Arguments

`buf`

  The buffer to place the result into

`size`

  The size of the buffer, including the trailing null space

`fmt`

  The format string to use @...: Arguments for the format string

`...`

  variable arguments

##### Description

The return value is the number of characters written into `buf` not including the trailing '\0'. If `size` is <= 0 the function returns 0.

#### LINUX

Kernel Hackers Manual January 2008
vsprintf
9
2.6.24-rc6-git8

#### vsprintf

Format a string and place it in a buffer

##### Synopsis

       int vsprintf
       char * buf
       const char * fmt
       va_list args

##### Arguments

`buf`

  The buffer to place the result into

`fmt`

  The format string to use

`args`

  Arguments for the format string

##### Description

The function returns the number of characters written into `buf`. Use `vsnprintf` or `vscnprintf` in order to avoid buffer overflows.

Call this function if you are already dealing with a va_list. You probably want `sprintf` instead.

#### LINUX

Kernel Hackers Manual January 2008
sprintf
9
2.6.24-rc6-git8

#### sprintf

Format a string and place it in a buffer

##### Synopsis

       int sprintf
       char * buf
       const char * fmt
        ...

##### Arguments

`buf`

  The buffer to place the result into

`fmt`

  The format string to use @...: Arguments for the format string

`...`

  variable arguments

##### Description

The function returns the number of characters written into `buf`. Use `snprintf` or `scnprintf` in order to avoid buffer overflows.

#### LINUX

Kernel Hackers Manual January 2008
vsscanf
9
2.6.24-rc6-git8

#### vsscanf

Unformat a buffer into a list of arguments

##### Synopsis

       int vsscanf
       const char * buf
       const char * fmt
       va_list args

##### Arguments

`buf`

  input buffer

`fmt`

  format of buffer

`args`

  arguments

#### LINUX

Kernel Hackers Manual January 2008
sscanf
9
2.6.24-rc6-git8

#### sscanf

Unformat a buffer into a list of arguments

##### Synopsis

       int sscanf
       const char * buf
       const char * fmt
        ...

##### Arguments

`buf`

  input buffer

`fmt`

  formatting of buffer @...: resulting arguments

`...`

  variable arguments

### String Manipulation

#### LINUX

Kernel Hackers Manual January 2008
strnicmp
9
2.6.24-rc6-git8

#### strnicmp

Case insensitive, length-limited string comparison

##### Synopsis

       int strnicmp
       const char * s1
       const char * s2
       size_t len

##### Arguments

`s1`

  One string

`s2`

  The other string

`len`

  the maximum number of characters to compare

#### LINUX

Kernel Hackers Manual January 2008
strcpy
9
2.6.24-rc6-git8

#### strcpy

Copy a `NUL` terminated string

##### Synopsis

       char * strcpy
       char * dest
       const char * src

##### Arguments

`dest`

  Where to copy the string to

`src`

  Where to copy the string from

#### LINUX

Kernel Hackers Manual January 2008
strncpy
9
2.6.24-rc6-git8

#### strncpy

Copy a length-limited, `NUL-terminated` string

##### Synopsis

       char * strncpy
       char * dest
       const char * src
       size_t count

##### Arguments

`dest`

  Where to copy the string to

`src`

  Where to copy the string from

`count`

  The maximum number of bytes to copy

##### Description

The result is not `NUL-terminated` if the source exceeds `count` bytes.

In the case where the length of `src` is less than that of count, the remainder of `dest` will be padded with `NUL`.

#### LINUX

Kernel Hackers Manual January 2008
strlcpy
9
2.6.24-rc6-git8

#### strlcpy

Copy a `NUL` terminated string into a sized buffer

##### Synopsis

       size_t strlcpy
       char * dest
       const char * src
       size_t size

##### Arguments

`dest`

  Where to copy the string to

`src`

  Where to copy the string from

`size`

  size of destination buffer

##### BSD

the result is always a valid NUL-terminated string that fits in the buffer (unless, of course, the buffer size is zero). It does not pad out the result like `strncpy` does.

#### LINUX

Kernel Hackers Manual January 2008
strcat
9
2.6.24-rc6-git8

#### strcat

Append one `NUL-terminated` string to another

##### Synopsis

       char * strcat
       char * dest
       const char * src

##### Arguments

`dest`

  The string to be appended to

`src`

  The string to append to it

#### LINUX

Kernel Hackers Manual January 2008
strncat
9
2.6.24-rc6-git8

#### strncat

Append a length-limited, `NUL-terminated` string to another

##### Synopsis

       char * strncat
       char * dest
       const char * src
       size_t count

##### Arguments

`dest`

  The string to be appended to

`src`

  The string to append to it

`count`

  The maximum numbers of bytes to copy

##### Description

Note that in contrast to `strncpy`, `strncat` ensures the result is terminated.

#### LINUX

Kernel Hackers Manual January 2008
strlcat
9
2.6.24-rc6-git8

#### strlcat

Append a length-limited, `NUL-terminated` string to another

##### Synopsis

       size_t strlcat
       char * dest
       const char * src
       size_t count

##### Arguments

`dest`

  The string to be appended to

`src`

  The string to append to it

`count`

  The size of the destination buffer.

#### LINUX

Kernel Hackers Manual January 2008
strcmp
9
2.6.24-rc6-git8

#### strcmp

Compare two strings

##### Synopsis

       int strcmp
       const char * cs
       const char * ct

##### Arguments

`cs`

  One string

`ct`

  Another string

#### LINUX

Kernel Hackers Manual January 2008
strncmp
9
2.6.24-rc6-git8

#### strncmp

Compare two length-limited strings

##### Synopsis

       int strncmp
       const char * cs
       const char * ct
       size_t count

##### Arguments

`cs`

  One string

`ct`

  Another string

`count`

  The maximum number of bytes to compare

#### LINUX

Kernel Hackers Manual January 2008
strchr
9
2.6.24-rc6-git8

#### strchr

Find the first occurrence of a character in a string

##### Synopsis

       char * strchr
       const char * s
       int c

##### Arguments

`s`

  The string to be searched

`c`

  The character to search for

#### LINUX

Kernel Hackers Manual January 2008
strrchr
9
2.6.24-rc6-git8

#### strrchr

Find the last occurrence of a character in a string

##### Synopsis

       char * strrchr
       const char * s
       int c

##### Arguments

`s`

  The string to be searched

`c`

  The character to search for

#### LINUX

Kernel Hackers Manual January 2008
strnchr
9
2.6.24-rc6-git8

#### strnchr

Find a character in a length limited string

##### Synopsis

       char * strnchr
       const char * s
       size_t count
       int c

##### Arguments

`s`

  The string to be searched

`count`

  The number of characters to be searched

`c`

  The character to search for

#### LINUX

Kernel Hackers Manual January 2008
strstrip
9
2.6.24-rc6-git8

#### strstrip

Removes leading and trailing whitespace from `s`.

##### Synopsis

       char * strstrip
       char * s

##### Arguments

`s`

  The string to be stripped.

##### Description

Note that the first trailing whitespace is replaced with a `NUL-terminator` in the given string `s`. Returns a pointer to the first non-whitespace character in `s`.

#### LINUX

Kernel Hackers Manual January 2008
strlen
9
2.6.24-rc6-git8

#### strlen

Find the length of a string

##### Synopsis

       size_t strlen
       const char * s

##### Arguments

`s`

  The string to be sized

#### LINUX

Kernel Hackers Manual January 2008
strnlen
9
2.6.24-rc6-git8

#### strnlen

Find the length of a length-limited string

##### Synopsis

       size_t strnlen
       const char * s
       size_t count

##### Arguments

`s`

  The string to be sized

`count`

  The maximum number of bytes to search

#### LINUX

Kernel Hackers Manual January 2008
strspn
9
2.6.24-rc6-git8

#### strspn

Calculate the length of the initial substring of `s` which only contain letters in `accept`

##### Synopsis

       size_t strspn
       const char * s
       const char * accept

##### Arguments

`s`

  The string to be searched

`accept`

  The string to search for

#### LINUX

Kernel Hackers Manual January 2008
strcspn
9
2.6.24-rc6-git8

#### strcspn

Calculate the length of the initial substring of `s` which does not contain letters in `reject`

##### Synopsis

       size_t strcspn
       const char * s
       const char * reject

##### Arguments

`s`

  The string to be searched

`reject`

  The string to avoid

#### LINUX

Kernel Hackers Manual January 2008
strpbrk
9
2.6.24-rc6-git8

#### strpbrk

Find the first occurrence of a set of characters

##### Synopsis

       char * strpbrk
       const char * cs
       const char * ct

##### Arguments

`cs`

  The string to be searched

`ct`

  The characters to search for

#### LINUX

Kernel Hackers Manual January 2008
strsep
9
2.6.24-rc6-git8

#### strsep

Split a string into tokens

##### Synopsis

       char * strsep
       char ** s
       const char * ct

##### Arguments

`s`

  The string to be searched

`ct`

  The characters to search for

##### Description

`strsep` updates `s` to point after the token, ready for the next call.

It returns empty tokens, too, behaving exactly like the libc function of that name. In fact, it was stolen from glibc2 and de-fancy-fied. Same semantics, slimmer shape. ;)

#### LINUX

Kernel Hackers Manual January 2008
memset
9
2.6.24-rc6-git8

#### memset

Fill a region of memory with the given value

##### Synopsis

       void * memset
       void * s
       int c
       size_t count

##### Arguments

`s`

  Pointer to the start of the area.

`c`

  The byte to fill the area with

`count`

  The size of the area.

##### Description

Do not use `memset` to access IO space, use `memset_io` instead.

#### LINUX

Kernel Hackers Manual January 2008
memcpy
9
2.6.24-rc6-git8

#### memcpy

Copy one area of memory to another

##### Synopsis

       void * memcpy
       void * dest
       const void * src
       size_t count

##### Arguments

`dest`

  Where to copy to

`src`

  Where to copy from

`count`

  The size of the area.

##### Description

You should not use this function to access IO space, use `memcpy_toio` or `memcpy_fromio` instead.

#### LINUX

Kernel Hackers Manual January 2008
memmove
9
2.6.24-rc6-git8

#### memmove

Copy one area of memory to another

##### Synopsis

       void * memmove
       void * dest
       const void * src
       size_t count

##### Arguments

`dest`

  Where to copy to

`src`

  Where to copy from

`count`

  The size of the area.

##### Description

Unlike `memcpy`, `memmove` copes with overlapping areas.

#### LINUX

Kernel Hackers Manual January 2008
memcmp
9
2.6.24-rc6-git8

#### memcmp

Compare two areas of memory

##### Synopsis

       int memcmp
       const void * cs
       const void * ct
       size_t count

##### Arguments

`cs`

  One area of memory

`ct`

  Another area of memory

`count`

  The size of the area.

#### LINUX

Kernel Hackers Manual January 2008
memscan
9
2.6.24-rc6-git8

#### memscan

Find a character in an area of memory.

##### Synopsis

       void * memscan
       void * addr
       int c
       size_t size

##### Arguments

`addr`

  The memory area

`c`

  The byte to search for

`size`

  The size of the area.

##### Description

returns the address of the first occurrence of `c`, or 1 byte past the area if `c` is not found

#### LINUX

Kernel Hackers Manual January 2008
strstr
9
2.6.24-rc6-git8

#### strstr

Find the first substring in a `NUL` terminated string

##### Synopsis

       char * strstr
       const char * s1
       const char * s2

##### Arguments

`s1`

  The string to be searched

`s2`

  The string to search for

#### LINUX

Kernel Hackers Manual January 2008
memchr
9
2.6.24-rc6-git8

#### memchr

Find a character in an area of memory.

##### Synopsis

       void * memchr
       const void * s
       int c
       size_t n

##### Arguments

`s`

  The memory area

`c`

  The byte to search for

`n`

  The size of the area.

##### Description

returns the address of the first occurrence of `c`, or `NULL` if `c` is not found

### Bit Operations

#### LINUX

Kernel Hackers Manual January 2008
set_bit
9
2.6.24-rc6-git8

#### set_bit

Atomically set a bit in memory

##### Synopsis

       void set_bit
       int nr
       volatile unsigned long * addr

##### Arguments

`nr`

  the bit to set

`addr`

  the address to start counting from

##### Description

This function is atomic and may not be reordered. See `__set_bit` if you do not require the atomic guarantees.

##### Note

there are no guarantees that this function will not be reordered on non x86 architectures, so if you are writing portable code, make sure not to rely on its reordering guarantees.

Note that `nr` may be almost arbitrarily large; this function is not restricted to acting on a single-word quantity.

#### LINUX

Kernel Hackers Manual January 2008
__set_bit
9
2.6.24-rc6-git8

#### __set_bit

Set a bit in memory

##### Synopsis

       void __set_bit
       int nr
       volatile unsigned long * addr

##### Arguments

`nr`

  the bit to set

`addr`

  the address to start counting from

##### Description

Unlike `set_bit`, this function is non-atomic and may be reordered. If it's called on the same region of memory simultaneously, the effect may be that only one operation succeeds.

#### LINUX

Kernel Hackers Manual January 2008
clear_bit
9
2.6.24-rc6-git8

#### clear_bit

Clears a bit in memory

##### Synopsis

       void clear_bit
       int nr
       volatile unsigned long * addr

##### Arguments

`nr`

  Bit to clear

`addr`

  Address to start counting from

##### Description

`clear_bit` is atomic and may not be reordered. However, it does not contain a memory barrier, so if it is used for locking purposes, you should call `smp_mb__before_clear_bit` and/or `smp_mb__after_clear_bit` in order to ensure changes are visible on other processors.

#### LINUX

Kernel Hackers Manual January 2008
__change_bit
9
2.6.24-rc6-git8

#### __change_bit

Toggle a bit in memory

##### Synopsis

       void __change_bit
       int nr
       volatile unsigned long * addr

##### Arguments

`nr`

  the bit to change

`addr`

  the address to start counting from

##### Description

Unlike `change_bit`, this function is non-atomic and may be reordered. If it's called on the same region of memory simultaneously, the effect may be that only one operation succeeds.

#### LINUX

Kernel Hackers Manual January 2008
change_bit
9
2.6.24-rc6-git8

#### change_bit

Toggle a bit in memory

##### Synopsis

       void change_bit
       int nr
       volatile unsigned long * addr

##### Arguments

`nr`

  Bit to change

`addr`

  Address to start counting from

##### Description

`change_bit` is atomic and may not be reordered. It may be reordered on other architectures than x86. Note that `nr` may be almost arbitrarily large; this function is not restricted to acting on a single-word quantity.

#### LINUX

Kernel Hackers Manual January 2008
test_and_set_bit
9
2.6.24-rc6-git8

#### test_and_set_bit

Set a bit and return its old value

##### Synopsis

       int test_and_set_bit
       int nr
       volatile unsigned long * addr

##### Arguments

`nr`

  Bit to set

`addr`

  Address to count from

##### Description

This operation is atomic and cannot be reordered. It may be reordered on other architectures than x86. It also implies a memory barrier.

#### LINUX

Kernel Hackers Manual January 2008
test_and_set_bit_lock
9
2.6.24-rc6-git8

#### test_and_set_bit_lock

Set a bit and return its old value for lock

##### Synopsis

       int test_and_set_bit_lock
       int nr
       volatile unsigned long * addr

##### Arguments

`nr`

  Bit to set

`addr`

  Address to count from

##### Description

This is the same as test_and_set_bit on x86.

#### LINUX

Kernel Hackers Manual January 2008
__test_and_set_bit
9
2.6.24-rc6-git8

#### __test_and_set_bit

Set a bit and return its old value

##### Synopsis

       int __test_and_set_bit
       int nr
       volatile unsigned long * addr

##### Arguments

`nr`

  Bit to set

`addr`

  Address to count from

##### Description

This operation is non-atomic and can be reordered. If two examples of this operation race, one can appear to succeed but actually fail. You must protect multiple accesses with a lock.

#### LINUX

Kernel Hackers Manual January 2008
test_and_clear_bit
9
2.6.24-rc6-git8

#### test_and_clear_bit

Clear a bit and return its old value

##### Synopsis

       int test_and_clear_bit
       int nr
       volatile unsigned long * addr

##### Arguments

`nr`

  Bit to clear

`addr`

  Address to count from

##### Description

This operation is atomic and cannot be reordered. It can be reorderdered on other architectures other than x86. It also implies a memory barrier.

#### LINUX

Kernel Hackers Manual January 2008
__test_and_clear_bit
9
2.6.24-rc6-git8

#### __test_and_clear_bit

Clear a bit and return its old value

##### Synopsis

       int __test_and_clear_bit
       int nr
       volatile unsigned long * addr

##### Arguments

`nr`

  Bit to clear

`addr`

  Address to count from

##### Description

This operation is non-atomic and can be reordered. If two examples of this operation race, one can appear to succeed but actually fail. You must protect multiple accesses with a lock.

#### LINUX

Kernel Hackers Manual January 2008
test_and_change_bit
9
2.6.24-rc6-git8

#### test_and_change_bit

Change a bit and return its old value

##### Synopsis

       int test_and_change_bit
       int nr
       volatile unsigned long * addr

##### Arguments

`nr`

  Bit to change

`addr`

  Address to count from

##### Description

This operation is atomic and cannot be reordered. It also implies a memory barrier.

#### LINUX

Kernel Hackers Manual January 2008
test_bit
9
2.6.24-rc6-git8

#### test_bit

Determine whether a bit is set

##### Synopsis

       int test_bit
       int nr
       const volatile void * addr

##### Arguments

`nr`

  bit number to test

`addr`

  Address to start counting from

#### LINUX

Kernel Hackers Manual January 2008
find_first_zero_bit
9
2.6.24-rc6-git8

#### find_first_zero_bit

find the first zero bit in a memory region

##### Synopsis

       int find_first_zero_bit
       const unsigned long * addr
       unsigned size

##### Arguments

`addr`

  The address to start the search at

`size`

  The maximum size to search

##### Description

Returns the bit-number of the first zero bit, not the number of the byte containing a bit.

#### LINUX

Kernel Hackers Manual January 2008
find_next_zero_bit
9
2.6.24-rc6-git8

#### find_next_zero_bit

find the first zero bit in a memory region

##### Synopsis

       int find_next_zero_bit
       const unsigned long * addr
       int size
       int offset

##### Arguments

`addr`

  The address to base the search on

`size`

  The maximum size to search

`offset`

  The bitnumber to start searching at

#### LINUX

Kernel Hackers Manual January 2008
__ffs
9
2.6.24-rc6-git8

#### __ffs

find first bit in word.

##### Synopsis

       unsigned long __ffs
       unsigned long word

##### Arguments

`word`

  The word to search

##### Description

Undefined if no bit exists, so code should check against 0 first.

#### LINUX

Kernel Hackers Manual January 2008
find_first_bit
9
2.6.24-rc6-git8

#### find_first_bit

find the first set bit in a memory region

##### Synopsis

       unsigned find_first_bit
       const unsigned long * addr
       unsigned size

##### Arguments

`addr`

  The address to start the search at

`size`

  The maximum size to search

##### Description

Returns the bit-number of the first set bit, not the number of the byte containing a bit.

#### LINUX

Kernel Hackers Manual January 2008
find_next_bit
9
2.6.24-rc6-git8

#### find_next_bit

find the first set bit in a memory region

##### Synopsis

       int find_next_bit
       const unsigned long * addr
       int size
       int offset

##### Arguments

`addr`

  The address to base the search on

`size`

  The maximum size to search

`offset`

  The bitnumber to start searching at

#### LINUX

Kernel Hackers Manual January 2008
ffz
9
2.6.24-rc6-git8

#### ffz

find first zero in word.

##### Synopsis

       unsigned long ffz
       unsigned long word

##### Arguments

`word`

  The word to search

##### Description

Undefined if no zero exists, so code should check against ~0UL first.

#### LINUX

Kernel Hackers Manual January 2008
ffs
9
2.6.24-rc6-git8

#### ffs

find first bit set

##### Synopsis

       int ffs
       int x

##### Arguments

`x`

  the word to search

##### Description

This is defined the same way as the libc and compiler builtin ffs routines, therefore differs in spirit from the above `ffz` (man ffs).

#### LINUX

Kernel Hackers Manual January 2008
fls
9
2.6.24-rc6-git8

#### fls

find last bit set

##### Synopsis

       int fls
       int x

##### Arguments

`x`

  the word to search

##### Description

This is defined the same way as `ffs`.

## Basic Kernel Library Functions

The Linux kernel provides more basic utility functions.

### Bitmap Operations

#### LINUX

Kernel Hackers Manual January 2008
__bitmap_shift_right
9
2.6.24-rc6-git8

#### __bitmap_shift_right

logical right shift of the bits in a bitmap

##### Synopsis

       void __bitmap_shift_right
       unsigned long * dst
       const unsigned long * src
       int shift
       int bits

##### Arguments

`dst`

  destination bitmap

`src`

  source bitmap

`shift`

  shift by this many bits

`bits`

  bitmap size, in bits

##### Description

Shifting right (dividing) means moving bits in the MS -> LS bit direction. Zeros are fed into the vacated MS positions and the LS bits shifted off the bottom are lost.

#### LINUX

Kernel Hackers Manual January 2008
__bitmap_shift_left
9
2.6.24-rc6-git8

#### __bitmap_shift_left

logical left shift of the bits in a bitmap

##### Synopsis

       void __bitmap_shift_left
       unsigned long * dst
       const unsigned long * src
       int shift
       int bits

##### Arguments

`dst`

  destination bitmap

`src`

  source bitmap

`shift`

  shift by this many bits

`bits`

  bitmap size, in bits

##### Description

Shifting left (multiplying) means moving bits in the LS -> MS direction. Zeros are fed into the vacated LS bit positions and those MS bits shifted off the top are lost.

#### LINUX

Kernel Hackers Manual January 2008
bitmap_scnprintf
9
2.6.24-rc6-git8

#### bitmap_scnprintf

convert bitmap to an ASCII hex string.

##### Synopsis

       int bitmap_scnprintf
       char * buf
       unsigned int buflen
       const unsigned long * maskp
       int nmaskbits

##### Arguments

`buf`

  byte buffer into which string is placed

`buflen`

  reserved size of `buf`, in bytes

`maskp`

  pointer to bitmap to convert

`nmaskbits`

  size of bitmap, in bits

##### Description

Exactly `nmaskbits` bits are displayed. Hex digits are grouped into comma-separated sets of eight digits per set.

#### LINUX

Kernel Hackers Manual January 2008
__bitmap_parse
9
2.6.24-rc6-git8

#### __bitmap_parse

convert an ASCII hex string into a bitmap.

##### Synopsis

       int __bitmap_parse
       const char * buf
       unsigned int buflen
       int is_user
       unsigned long * maskp
       int nmaskbits

##### Arguments

`buf`

  pointer to buffer containing string.

`buflen`

  buffer size in bytes. If string is smaller than this then it must be terminated with a \0.

`is_user`

  location of buffer, 0 indicates kernel space

`maskp`

  pointer to bitmap array that will contain result.

`nmaskbits`

  size of bitmap, in bits.

##### Description

Commas group hex digits into chunks. Each chunk defines exactly 32 bits of the resultant bitmask. No chunk may specify a value larger than 32 bits (`-EOVERFLOW`), and if a chunk specifies a smaller value then leading 0-bits are prepended. `-EINVAL` is returned for illegal characters and for grouping errors such as 1,,5, ,44, , and "". Leading and trailing whitespace accepted, but not embedded whitespace.

#### LINUX

Kernel Hackers Manual January 2008
bitmap_parse_user
9
2.6.24-rc6-git8

#### bitmap_parse_user

##### Synopsis

       int bitmap_parse_user
       const char __user * ubuf
       unsigned int ulen
       unsigned long * maskp
       int nmaskbits

##### Arguments

`ubuf`

  pointer to user buffer containing string.

`ulen`

  buffer size in bytes. If string is smaller than this then it must be terminated with a \0.

`maskp`

  pointer to bitmap array that will contain result.

`nmaskbits`

  size of bitmap, in bits.

##### Description

Wrapper for `__bitmap_parse`, providing it with user buffer.

We cannot have this as an inline function in bitmap.h because it needs linux/uaccess.h to get the `access_ok` declaration and this causes cyclic dependencies.

##### Description

Wrapper for `__bitmap_parse`, providing it with user buffer.

We cannot have this as an inline function in bitmap.h because it needs linux/uaccess.h to get the `access_ok` declaration and this causes cyclic dependencies.

#### LINUX

Kernel Hackers Manual January 2008
bitmap_scnlistprintf
9
2.6.24-rc6-git8

#### bitmap_scnlistprintf

convert bitmap to list format ASCII string

##### Synopsis

       int bitmap_scnlistprintf
       char * buf
       unsigned int buflen
       const unsigned long * maskp
       int nmaskbits

##### Arguments

`buf`

  byte buffer into which string is placed

`buflen`

  reserved size of `buf`, in bytes

`maskp`

  pointer to bitmap to convert

`nmaskbits`

  size of bitmap, in bits

##### Description

Output format is a comma-separated list of decimal numbers and ranges. Consecutively set bits are shown as two hyphen-separated decimal numbers, the smallest and largest bit numbers set in the range. Output format is compatible with the format accepted as input by `bitmap_parselist`.

The return value is the number of characters which would be generated for the given input, excluding the trailing '\0', as per ISO C99.

#### LINUX

Kernel Hackers Manual January 2008
bitmap_parselist
9
2.6.24-rc6-git8

#### bitmap_parselist

convert list format ASCII string to bitmap

##### Synopsis

       int bitmap_parselist
       const char * bp
       unsigned long * maskp
       int nmaskbits

##### Arguments

`bp`

  read nul-terminated user string from this buffer

`maskp`

  write resulting mask here

`nmaskbits`

  number of bits in mask to be written

##### Description

Input format is a comma-separated list of decimal numbers and ranges. Consecutively set bits are shown as two hyphen-separated decimal numbers, the smallest and largest bit numbers set in the range.

Returns 0 on success, -errno on invalid input strings.

##### Error values

`-EINVAL`: second number in range smaller than first `-EINVAL`: invalid character in string `-ERANGE`: bit number specified too large for mask

#### LINUX

Kernel Hackers Manual January 2008
bitmap_remap
9
2.6.24-rc6-git8

#### bitmap_remap

Apply map defined by a pair of bitmaps to another bitmap

##### Synopsis

       void bitmap_remap
       unsigned long * dst
       const unsigned long * src
       const unsigned long * old
       const unsigned long * new
       int bits

##### Arguments

`dst`

  remapped result

`src`

  subset to be remapped

`old`

  defines domain of map

`new`

  defines range of map

`bits`

  number of bits in each of these bitmaps

##### Description

Let `old` and `new` define a mapping of bit positions, such that whatever position is held by the n-th set bit in `old` is mapped to the n-th set bit in `new`. In the more general case, allowing for the possibility that the weight 'w' of `new` is less than the weight of `old`, map the position of the n-th set bit in `old` to the position of the m-th set bit in `new`, where m == n % w.

If either of the `old` and `new` bitmaps are empty, or if `src` and `dst` point to the same location, then this routine copies `src` to `dst`.

The positions of unset bits in `old` are mapped to themselves (the identify map).

Apply the above specified mapping to `src`, placing the result in `dst`, clearing any bits previously set in `dst`.

For example, lets say that `old` has bits 4 through 7 set, and `new` has bits 12 through 15 set. This defines the mapping of bit position 4 to 12, 5 to 13, 6 to 14 and 7 to 15, and of all other bit positions unchanged. So if say `src` comes into this routine with bits 1, 5 and 7 set, then `dst` should leave with bits 1, 13 and 15 set.

#### LINUX

Kernel Hackers Manual January 2008
bitmap_bitremap
9
2.6.24-rc6-git8

#### bitmap_bitremap

Apply map defined by a pair of bitmaps to a single bit

##### Synopsis

       int bitmap_bitremap
       int oldbit
       const unsigned long * old
       const unsigned long * new
       int bits

##### Arguments

`oldbit`

  bit position to be mapped

`old`

  defines domain of map

`new`

  defines range of map

`bits`

  number of bits in each of these bitmaps

##### Description

Let `old` and `new` define a mapping of bit positions, such that whatever position is held by the n-th set bit in `old` is mapped to the n-th set bit in `new`. In the more general case, allowing for the possibility that the weight 'w' of `new` is less than the weight of `old`, map the position of the n-th set bit in `old` to the position of the m-th set bit in `new`, where m == n % w.

The positions of unset bits in `old` are mapped to themselves (the identify map).

Apply the above specified mapping to bit position `oldbit`, returning the new bit position.

For example, lets say that `old` has bits 4 through 7 set, and `new` has bits 12 through 15 set. This defines the mapping of bit position 4 to 12, 5 to 13, 6 to 14 and 7 to 15, and of all other bit positions unchanged. So if say `oldbit` is 5, then this routine returns 13.

#### LINUX

Kernel Hackers Manual January 2008
bitmap_find_free_region
9
2.6.24-rc6-git8

#### bitmap_find_free_region

find a contiguous aligned mem region

##### Synopsis

       int bitmap_find_free_region
       unsigned long * bitmap
       int bits
       int order

##### Arguments

`bitmap`

  array of unsigned longs corresponding to the bitmap

`bits`

  number of bits in the bitmap

`order`

  region size (log base 2 of number of bits) to find

##### Description

Find a region of free (zero) bits in a `bitmap` of `bits` bits and allocate them (set them to one). Only consider regions of length a power (`order`) of two, aligned to that power of two, which makes the search algorithm much faster.

Return the bit offset in bitmap of the allocated region, or -errno on failure.

#### LINUX

Kernel Hackers Manual January 2008
bitmap_release_region
9
2.6.24-rc6-git8

#### bitmap_release_region

release allocated bitmap region

##### Synopsis

       void bitmap_release_region
       unsigned long * bitmap
       int pos
       int order

##### Arguments

`bitmap`

  array of unsigned longs corresponding to the bitmap

`pos`

  beginning of bit region to release

`order`

  region size (log base 2 of number of bits) to release

##### Description

This is the complement to `__bitmap_find_free_region` and releases the found region (by clearing it in the bitmap).

No return value.

#### LINUX

Kernel Hackers Manual January 2008
bitmap_allocate_region
9
2.6.24-rc6-git8

#### bitmap_allocate_region

allocate bitmap region

##### Synopsis

       int bitmap_allocate_region
       unsigned long * bitmap
       int pos
       int order

##### Arguments

`bitmap`

  array of unsigned longs corresponding to the bitmap

`pos`

  beginning of bit region to allocate

`order`

  region size (log base 2 of number of bits) to allocate

##### Description

Allocate (set bits in) a specified region of a bitmap.

Return 0 on success, or `-EBUSY` if specified region wasn't free (not all bits were zero).

#### LINUX

Kernel Hackers Manual January 2008
bitmap_pos_to_ord
9
2.6.24-rc6-git8

#### bitmap_pos_to_ord

##### Synopsis

       int bitmap_pos_to_ord
       const unsigned long * buf
       int pos
       int bits

##### Arguments

`buf`

  pointer to a bitmap

`pos`

  a bit position in `buf` (0 <= `pos` < `bits`)

`bits`

  number of valid bit positions in `buf`

##### Description

Map the bit at position `pos` in `buf` (of length `bits`) to the ordinal of which set bit it is. If it is not set or if `pos` is not a valid bit position, map to -1.

If for example, just bits 4 through 7 are set in `buf`, then `pos` values 4 through 7 will get mapped to 0 through 3, respectively, and other `pos` values will get mapped to 0. When `pos` value 7 gets mapped to (returns) `ord` value 3 in this example, that means that bit 7 is the 3rd (starting with 0th) set bit in `buf`.

The bit positions 0 through `bits` are valid positions in `buf`.

#### LINUX

Kernel Hackers Manual January 2008
bitmap_ord_to_pos
9
2.6.24-rc6-git8

#### bitmap_ord_to_pos

##### Synopsis

       int bitmap_ord_to_pos
       const unsigned long * buf
       int ord
       int bits

##### Arguments

`buf`

  pointer to bitmap

`ord`

  ordinal bit position (n-th set bit, n >= 0)

`bits`

  number of valid bit positions in `buf`

##### Description

Map the ordinal offset of bit `ord` in `buf` to its position in `buf`. Value of `ord` should be in range 0 <= `ord` < weight(buf), else results are undefined.

If for example, just bits 4 through 7 are set in `buf`, then `ord` values 0 through 3 will get mapped to 4 through 7, respectively, and all other `ord` values return undefined values. When `ord` value 3 gets mapped to (returns) `pos` value 7 in this example, that means that the 3rd set bit (starting with 0th) is at position 7 in `buf`.

The bit positions 0 through `bits` are valid positions in `buf`.

### Command-line Parsing

#### LINUX

Kernel Hackers Manual January 2008
get_option
9
2.6.24-rc6-git8

#### get_option

Parse integer from an option string

##### Synopsis

       int get_option
       char ** str
       int * pint

##### Arguments

`str`

  option string

`pint`

  (output) integer value parsed from `str`

##### Description

Read an int from an option string; if available accept a subsequent comma as well.

##### Return values

0 - no int in string 1 - int found, no subsequent comma 2 - int found including a subsequent comma 3 - hyphen found to denote a range

#### LINUX

Kernel Hackers Manual January 2008
get_options
9
2.6.24-rc6-git8

#### get_options

Parse a string into a list of integers

##### Synopsis

       char * get_options
       const char * str
       int nints
       int * ints

##### Arguments

`str`

  String to be parsed

`nints`

  size of integer array

`ints`

  integer array

##### Description

This function parses a string containing a comma-separated list of integers, a hyphen-separated range of _positive_ integers, or a combination of both. The parse halts when the array is full, or when no more numbers can be retrieved from the string.

Return value is the character in the string which caused the parse to end (typically a null terminator, if `str` is completely parseable).

#### LINUX

Kernel Hackers Manual January 2008
memparse
9
2.6.24-rc6-git8

#### memparse

parse a string with mem suffixes into a number

##### Synopsis

       unsigned long long memparse
       char * ptr
       char ** retptr

##### Arguments

`ptr`

  Where parse begins

`retptr`

  (output) Pointer to next char after parse completes

##### Description

Parses a string into a number. The number stored at `ptr` is potentially suffixed with `K` (for kilobytes, or 1024 bytes), `M` (for megabytes, or 1048576 bytes), or `G` (for gigabytes, or 1073741824). If the number is suffixed with K, M, or G, then the return value is the number multiplied by one kilobyte, one megabyte, or one gigabyte, respectively.

### CRC Functions

#### LINUX

Kernel Hackers Manual January 2008
crc7
9
2.6.24-rc6-git8

#### crc7

update the CRC7 for the data buffer

##### Synopsis

       u8 crc7
       u8 crc
       const u8 * buffer
       size_t len

##### Arguments

`crc`

  previous CRC7 value

`buffer`

  data pointer

`len`

  number of bytes in the buffer

##### Context

any

##### Description

Returns the updated CRC7 value.

#### LINUX

Kernel Hackers Manual January 2008
crc16
9
2.6.24-rc6-git8

#### crc16

compute the CRC-16 for the data buffer

##### Synopsis

       u16 crc16
       u16 crc
       u8 const * buffer
       size_t len

##### Arguments

`crc`

  previous CRC value

`buffer`

  data pointer

`len`

  number of bytes in the buffer

##### Description

Returns the updated CRC value.

#### LINUX

Kernel Hackers Manual January 2008
crc_itu_t
9
2.6.24-rc6-git8

#### crc_itu_t

Compute the CRC-ITU-T for the data buffer

##### Synopsis

       u16 crc_itu_t
       u16 crc
       const u8 * buffer
       size_t len

##### Arguments

`crc`

  previous CRC value

`buffer`

  data pointer

`len`

  number of bytes in the buffer

##### Description

Returns the updated CRC value

##### Description

Returns the updated CRC value

#### LINUX

Kernel Hackers Manual January 2008
crc32_le
9
2.6.24-rc6-git8

#### crc32_le

Calculate bitwise little-endian Ethernet AUTODIN II CRC32

##### Synopsis

       u32 __pure crc32_le
       u32 crc
       unsigned char const * p
       size_t len

##### Arguments

`crc`

  seed value for computation. ~0 for Ethernet, sometimes 0 for other uses, or the previous crc32 value if computing incrementally.

`p`

  pointer to buffer over which CRC is run

`len`

  length of buffer `p`

#### LINUX

Kernel Hackers Manual January 2008
crc32_be
9
2.6.24-rc6-git8

#### crc32_be

Calculate bitwise big-endian Ethernet AUTODIN II CRC32

##### Synopsis

       u32 __pure crc32_be
       u32 crc
       unsigned char const * p
       size_t len

##### Arguments

`crc`

  seed value for computation. ~0 for Ethernet, sometimes 0 for other uses, or the previous crc32 value if computing incrementally.

`p`

  pointer to buffer over which CRC is run

`len`

  length of buffer `p`

#### LINUX

Kernel Hackers Manual January 2008
crc_ccitt
9
2.6.24-rc6-git8

#### crc_ccitt

recompute the CRC for the data buffer

##### Synopsis

       u16 crc_ccitt
       u16 crc
       u8 const * buffer
       size_t len

##### Arguments

`crc`

  previous CRC value

`buffer`

  data pointer

`len`

  number of bytes in the buffer

## Memory Management in Linux

### The Slab Cache

#### LINUX

Kernel Hackers Manual January 2008
kcalloc
9
2.6.24-rc6-git8

#### kcalloc

allocate memory for an array. The memory is set to zero.

##### Synopsis

       void * kcalloc
       size_t n
       size_t size
       gfp_t flags

##### Arguments

`n`

  number of elements.

`size`

  element size.

`flags`

  the type of memory to allocate.

##### Description

The `flags` argument may be one of:

`GFP_USER` - Allocate memory on behalf of user. May sleep.

`GFP_KERNEL` - Allocate normal kernel ram. May sleep.

`GFP_ATOMIC` - Allocation will not sleep. May use emergency pools. For example, use this inside interrupt handlers.

`GFP_HIGHUSER` - Allocate pages from high memory.

`GFP_NOIO` - Do not do any I/O at all while trying to get memory.

`GFP_NOFS` - Do not make any fs calls while trying to get memory.

`GFP_NOWAIT` - Allocation will not sleep.

`GFP_THISNODE` - Allocate node-local memory only.

`GFP_DMA` - Allocation suitable for DMA. Should only be used for `kmalloc` caches. Otherwise, use a slab created with SLAB_DMA.

Also it is possible to set different flags by OR'ing in one or more of the following additional `flags`:

`__GFP_COLD` - Request cache-cold pages instead of trying to return cache-warm pages.

`__GFP_HIGH` - This allocation has high priority and may use emergency pools.

`__GFP_NOFAIL` - Indicate that this allocation is in no way allowed to fail (think twice before using).

`__GFP_NORETRY` - If memory is not immediately available, then give up at once.

`__GFP_NOWARN` - If allocation fails, don't issue any warnings.

`__GFP_REPEAT` - If allocation fails initially, try once more before failing.

There are other flags available as well, but these are not intended for general use, and so are not documented here. For a full list of potential flags, always refer to linux/gfp.h.

#### LINUX

Kernel Hackers Manual January 2008
kmalloc_node
9
2.6.24-rc6-git8

#### kmalloc_node

allocate memory from a specific node

##### Synopsis

       void * kmalloc_node
       size_t size
       gfp_t flags
       int node

##### Arguments

`size`

  how many bytes of memory are required.

`flags`

  the type of memory to allocate (see kcalloc).

`node`

  node to allocate from.

##### Description

`kmalloc` for non-local nodes, used to allocate from a specific node if available. Equivalent to `kmalloc` in the non-NUMA single-node case.

#### LINUX

Kernel Hackers Manual January 2008
kzalloc
9
2.6.24-rc6-git8

#### kzalloc

allocate memory. The memory is set to zero.

##### Synopsis

       void * kzalloc
       size_t size
       gfp_t flags

##### Arguments

`size`

  how many bytes of memory are required.

`flags`

  the type of memory to allocate (see kmalloc).

#### LINUX

Kernel Hackers Manual January 2008
kmem_cache_create
9
2.6.24-rc6-git8

#### kmem_cache_create

Create a cache.

##### Synopsis

       struct kmem_cache * kmem_cache_create
       const char * name
       size_t size
       size_t align
       unsigned long flags
       void (*ctor)
         struct kmem_cache *, void *

##### Arguments

`name`

  A string which is used in /proc/slabinfo to identify this cache.

`size`

  The size of objects to be created in this cache.

`align`

  The required alignment for the objects.

`flags`

  SLAB flags

`ctor`

  A constructor for the objects.

##### Description

Returns a ptr to the cache on success, NULL on failure. Cannot be called within a int, but can be interrupted. The `ctor` is run when new pages are allocated by the cache.

`name` must be valid until the cache is destroyed. This implies that the module calling this has to destroy the cache before getting unloaded.

The flags are

`SLAB_POISON` - Poison the slab with a known test pattern (a5a5a5a5) to catch references to uninitialised memory.

`SLAB_RED_ZONE` - Insert `Red' zones around the allocated memory to check for buffer overruns.

`SLAB_HWCACHE_ALIGN` - Align the objects in this cache to a hardware cacheline. This can be beneficial if you're counting cycles as closely as davem.

#### LINUX

Kernel Hackers Manual January 2008
kmem_cache_shrink
9
2.6.24-rc6-git8

#### kmem_cache_shrink

Shrink a cache.

##### Synopsis

       int kmem_cache_shrink
       struct kmem_cache * cachep

##### Arguments

`cachep`

  The cache to shrink.

##### Description

Releases as many slabs as possible for a cache. To help debugging, a zero exit status indicates all slabs were released.

#### LINUX

Kernel Hackers Manual January 2008
kmem_cache_destroy
9
2.6.24-rc6-git8

#### kmem_cache_destroy

delete a cache

##### Synopsis

       void kmem_cache_destroy
       struct kmem_cache * cachep

##### Arguments

`cachep`

  the cache to destroy

##### Description

Remove a &struct kmem_cache object from the slab cache.

It is expected this function will be called by a module when it is unloaded. This will remove the cache completely, and avoid a duplicate cache being allocated each time a module is loaded and unloaded, if the module doesn't have persistent in-kernel storage across loads and unloads.

The cache must be empty before calling this function.

The caller must guarantee that noone will allocate memory from the cache during the `kmem_cache_destroy`.

#### LINUX

Kernel Hackers Manual January 2008
kmem_cache_alloc
9
2.6.24-rc6-git8

#### kmem_cache_alloc

Allocate an object

##### Synopsis

       void * kmem_cache_alloc
       struct kmem_cache * cachep
       gfp_t flags

##### Arguments

`cachep`

  The cache to allocate from.

`flags`

  See `kmalloc`.

##### Description

Allocate an object from this cache. The flags are only relevant if the cache has no available objects.

#### LINUX

Kernel Hackers Manual January 2008
kmem_cache_free
9
2.6.24-rc6-git8

#### kmem_cache_free

Deallocate an object

##### Synopsis

       void kmem_cache_free
       struct kmem_cache * cachep
       void * objp

##### Arguments

`cachep`

  The cache the allocation was from.

`objp`

  The previously allocated object.

##### Description

Free an object which was previously allocated from this cache.

#### LINUX

Kernel Hackers Manual January 2008
kfree
9
2.6.24-rc6-git8

#### kfree

free previously allocated memory

##### Synopsis

       void kfree
       const void * objp

##### Arguments

`objp`

  pointer returned by kmalloc.

##### Description

If `objp` is NULL, no operation is performed.

Don't free memory not originally allocated by `kmalloc` or you will run into trouble.

#### LINUX

Kernel Hackers Manual January 2008
ksize
9
2.6.24-rc6-git8

#### ksize

get the actual amount of memory allocated for a given object

##### Synopsis

       size_t ksize
       const void * objp

##### Arguments

`objp`

  Pointer to the object

##### Description

kmalloc may internally round up allocations and return more memory than requested. `ksize` can be used to determine the actual amount of memory allocated. The caller may use this additional memory, even though a smaller amount of memory was initially specified with the kmalloc call. The caller must guarantee that objp points to a valid object previously allocated with either `kmalloc` or `kmem_cache_alloc`. The object must not be freed during the duration of the call.

### User Space Memory Access

#### LINUX

Kernel Hackers Manual January 2008
access_ok
9
2.6.24-rc6-git8

#### access_ok

Checks if a user space pointer is valid

##### Synopsis

        access_ok
        type
        addr
        size

##### Arguments

`type`

  Type of access: `VERIFY_READ` or `VERIFY_WRITE`. Note that `VERIFY_WRITE` is a superset of `VERIFY_READ` - if it is safe to write to a block, it is always safe to read from it.

`addr`

  User space pointer to start of block to check

`size`

  Size of block to check

##### Context

User context only. This function may sleep.

##### Description

Checks if a pointer to a block of memory in user space is valid.

Returns true (nonzero) if the memory block may be valid, false (zero) if it is definitely invalid.

Note that, depending on architecture, this function probably just checks that the pointer is in the user space range - after calling this function, memory access functions may still return -EFAULT.

#### LINUX

Kernel Hackers Manual January 2008
get_user
9
2.6.24-rc6-git8

#### get_user

Get a simple variable from user space.

##### Synopsis

        get_user
        x
        ptr

##### Arguments

`x`

  Variable to store result.

`ptr`

  Source address, in user space.

##### Context

User context only. This function may sleep.

##### Description

This macro copies a single simple variable from user space to kernel space. It supports simple types like char and int, but not larger data types like structures or arrays.

`ptr` must have pointer-to-simple-variable type, and the result of dereferencing `ptr` must be assignable to `x` without a cast.

Returns zero on success, or -EFAULT on error. On error, the variable `x` is set to zero.

#### LINUX

Kernel Hackers Manual January 2008
put_user
9
2.6.24-rc6-git8

#### put_user

Write a simple value into user space.

##### Synopsis

        put_user
        x
        ptr

##### Arguments

`x`

  Value to copy to user space.

`ptr`

  Destination address, in user space.

##### Context

User context only. This function may sleep.

##### Description

This macro copies a single simple value from kernel space to user space. It supports simple types like char and int, but not larger data types like structures or arrays.

`ptr` must have pointer-to-simple-variable type, and `x` must be assignable to the result of dereferencing `ptr`.

Returns zero on success, or -EFAULT on error.

#### LINUX

Kernel Hackers Manual January 2008
__get_user
9
2.6.24-rc6-git8

#### __get_user

Get a simple variable from user space, with less checking.

##### Synopsis

        __get_user
        x
        ptr

##### Arguments

`x`

  Variable to store result.

`ptr`

  Source address, in user space.

##### Context

User context only. This function may sleep.

##### Description

This macro copies a single simple variable from user space to kernel space. It supports simple types like char and int, but not larger data types like structures or arrays.

`ptr` must have pointer-to-simple-variable type, and the result of dereferencing `ptr` must be assignable to `x` without a cast.

Caller must check the pointer with `access_ok` before calling this function.

Returns zero on success, or -EFAULT on error. On error, the variable `x` is set to zero.

#### LINUX

Kernel Hackers Manual January 2008
__put_user
9
2.6.24-rc6-git8

#### __put_user

Write a simple value into user space, with less checking.

##### Synopsis

        __put_user
        x
        ptr

##### Arguments

`x`

  Value to copy to user space.

`ptr`

  Destination address, in user space.

##### Context

User context only. This function may sleep.

##### Description

This macro copies a single simple value from kernel space to user space. It supports simple types like char and int, but not larger data types like structures or arrays.

`ptr` must have pointer-to-simple-variable type, and `x` must be assignable to the result of dereferencing `ptr`.

Caller must check the pointer with `access_ok` before calling this function.

Returns zero on success, or -EFAULT on error.

#### LINUX

Kernel Hackers Manual January 2008
__copy_to_user_inatomic
9
2.6.24-rc6-git8

#### __copy_to_user_inatomic

Copy a block of data into user space, with less checking.

##### Synopsis

       unsigned long __must_check __copy_to_user_inatomic
       void __user * to
       const void * from
       unsigned long n

##### Arguments

`to`

  Destination address, in user space.

`from`

  Source address, in kernel space.

`n`

  Number of bytes to copy.

##### Context

User context only.

##### Description

Copy data from kernel space to user space. Caller must check the specified block with `access_ok` before calling this function. The caller should also make sure he pins the user space address so that the we don't result in page fault and sleep.

Here we special-case 1, 2 and 4-byte copy_*_user invocations. On a fault we return the initial request size (1, 2 or 4), as copy_*_user should do. If a store crosses a page boundary and gets a fault, the x86 will not write anything, so this is accurate.

#### LINUX

Kernel Hackers Manual January 2008
__copy_to_user
9
2.6.24-rc6-git8

#### __copy_to_user

Copy a block of data into user space, with less checking.

##### Synopsis

       unsigned long __must_check __copy_to_user
       void __user * to
       const void * from
       unsigned long n

##### Arguments

`to`

  Destination address, in user space.

`from`

  Source address, in kernel space.

`n`

  Number of bytes to copy.

##### Context

User context only. This function may sleep.

##### Description

Copy data from kernel space to user space. Caller must check the specified block with `access_ok` before calling this function.

Returns number of bytes that could not be copied. On success, this will be zero.

#### LINUX

Kernel Hackers Manual January 2008
__copy_from_user
9
2.6.24-rc6-git8

#### __copy_from_user

Copy a block of data from user space, with less checking.

##### Synopsis

       unsigned long __copy_from_user
       void * to
       const void __user * from
       unsigned long n

##### Arguments

`to`

  Destination address, in kernel space.

`from`

  Source address, in user space.

`n`

  Number of bytes to copy.

##### Context

User context only. This function may sleep.

##### Description

Copy data from user space to kernel space. Caller must check the specified block with `access_ok` before calling this function.

Returns number of bytes that could not be copied. On success, this will be zero.

If some data could not be copied, this function will pad the copied data to the requested size using zero bytes.

An alternate version - `__copy_from_user_inatomic` - may be called from atomic context and will fail rather than sleep. In this case the uncopied bytes will *NOT* be padded with zeros. See fs/filemap.h for explanation of why this is needed.

#### LINUX

Kernel Hackers Manual January 2008
strlen_user
9
2.6.24-rc6-git8

#### strlen_user

Get the size of a string in user space.

##### Synopsis

        strlen_user
        str

##### Arguments

`str`

  The string to measure.

##### Context

User context only. This function may sleep.

##### Description

Get the size of a NUL-terminated string in user space.

Returns the size of the string INCLUDING the terminating NUL. On exception, returns 0.

If there is a limit on the length of a valid string, you may wish to consider using `strnlen_user` instead.

#### LINUX

Kernel Hackers Manual January 2008
__strncpy_from_user
9
2.6.24-rc6-git8

#### __strncpy_from_user

Copy a NUL terminated string from userspace, with less checking.

##### Synopsis

       long __strncpy_from_user
       char * dst
       const char __user * src
       long count

##### Arguments

`dst`

  Destination address, in kernel space. This buffer must be at least `count` bytes long.

`src`

  Source address, in user space.

`count`

  Maximum number of bytes to copy, including the trailing NUL.

##### Description

Copies a NUL-terminated string from userspace to kernel space. Caller must check the specified block with `access_ok` before calling this function.

On success, returns the length of the string (not including the trailing NUL).

If access to userspace fails, returns -EFAULT (some data may have been copied).

If `count` is smaller than the length of the string, copies `count` bytes and returns `count`.

#### LINUX

Kernel Hackers Manual January 2008
strncpy_from_user
9
2.6.24-rc6-git8

#### strncpy_from_user

Copy a NUL terminated string from userspace.

##### Synopsis

       long strncpy_from_user
       char * dst
       const char __user * src
       long count

##### Arguments

`dst`

  Destination address, in kernel space. This buffer must be at least `count` bytes long.

`src`

  Source address, in user space.

`count`

  Maximum number of bytes to copy, including the trailing NUL.

##### Description

Copies a NUL-terminated string from userspace to kernel space.

On success, returns the length of the string (not including the trailing NUL).

If access to userspace fails, returns -EFAULT (some data may have been copied).

If `count` is smaller than the length of the string, copies `count` bytes and returns `count`.

#### LINUX

Kernel Hackers Manual January 2008
clear_user
9
2.6.24-rc6-git8

#### clear_user

Zero a block of memory in user space.

##### Synopsis

       unsigned long clear_user
       void __user * to
       unsigned long n

##### Arguments

`to`

  Destination address, in user space.

`n`

  Number of bytes to zero.

##### Description

Zero a block of memory in user space.

Returns number of bytes that could not be cleared. On success, this will be zero.

#### LINUX

Kernel Hackers Manual January 2008
__clear_user
9
2.6.24-rc6-git8

#### __clear_user

Zero a block of memory in user space, with less checking.

##### Synopsis

       unsigned long __clear_user
       void __user * to
       unsigned long n

##### Arguments

`to`

  Destination address, in user space.

`n`

  Number of bytes to zero.

##### Description

Zero a block of memory in user space. Caller must check the specified block with `access_ok` before calling this function.

Returns number of bytes that could not be cleared. On success, this will be zero.

#### LINUX

Kernel Hackers Manual January 2008
strnlen_user
9
2.6.24-rc6-git8

#### strnlen_user

Get the size of a string in user space.

##### Synopsis

       long strnlen_user
       const char __user * s
       long n

##### Arguments

`s`

  The string to measure.

`n`

  The maximum valid length

##### Description

Get the size of a NUL-terminated string in user space.

Returns the size of the string INCLUDING the terminating NUL. On exception, returns 0. If the string is too long, returns a value greater than `n`.

#### LINUX

Kernel Hackers Manual January 2008
copy_to_user
9
2.6.24-rc6-git8

#### copy_to_user

Copy a block of data into user space.

##### Synopsis

       unsigned long copy_to_user
       void __user * to
       const void * from
       unsigned long n

##### Arguments

`to`

  Destination address, in user space.

`from`

  Source address, in kernel space.

`n`

  Number of bytes to copy.

##### Context

User context only. This function may sleep.

##### Description

Copy data from kernel space to user space.

Returns number of bytes that could not be copied. On success, this will be zero.

#### LINUX

Kernel Hackers Manual January 2008
copy_from_user
9
2.6.24-rc6-git8

#### copy_from_user

Copy a block of data from user space.

##### Synopsis

       unsigned long copy_from_user
       void * to
       const void __user * from
       unsigned long n

##### Arguments

`to`

  Destination address, in kernel space.

`from`

  Source address, in user space.

`n`

  Number of bytes to copy.

##### Context

User context only. This function may sleep.

##### Description

Copy data from user space to kernel space.

Returns number of bytes that could not be copied. On success, this will be zero.

If some data could not be copied, this function will pad the copied data to the requested size using zero bytes.

### More Memory Management Functions

#### LINUX

Kernel Hackers Manual January 2008
read_cache_pages
9
2.6.24-rc6-git8

#### read_cache_pages

populate an address space with some pages & start reads against them

##### Synopsis

       int read_cache_pages
       struct address_space * mapping
       struct list_head * pages
       int (*filler)
         void *, struct page *
       void * data

##### Arguments

`mapping`

  the address_space

`pages`

  The address of a list_head which contains the target pages. These pages have their ->index populated and are otherwise uninitialised.

`filler`

  callback routine for filling a single page.

`data`

  private data for the callback routine.

##### Description

Hides the details of the LRU cache etc from the filesystems.

#### LINUX

Kernel Hackers Manual January 2008
page_cache_sync_readahead
9
2.6.24-rc6-git8

#### page_cache_sync_readahead

generic file readahead

##### Synopsis

       void page_cache_sync_readahead
       struct address_space * mapping
       struct file_ra_state * ra
       struct file * filp
       pgoff_t offset
       unsigned long req_size

##### Arguments

`mapping`

  address_space which holds the pagecache and I/O vectors

`ra`

  file_ra_state which holds the readahead state

`filp`

  passed on to ->`readpage` and ->`readpages`

`offset`

  start offset into `mapping`, in pagecache page-sized units

`req_size`

  hint: total size of the read which the caller is performing in pagecache pages

##### Description

`page_cache_sync_readahead` should be called when a cache miss happened: it will submit the read. The readahead logic may decide to piggyback more pages onto the read request if access patterns suggest it will improve performance.

#### LINUX

Kernel Hackers Manual January 2008
page_cache_async_readahead
9
2.6.24-rc6-git8

#### page_cache_async_readahead

file readahead for marked pages

##### Synopsis

       void page_cache_async_readahead
       struct address_space * mapping
       struct file_ra_state * ra
       struct file * filp
       struct page * page
       pgoff_t offset
       unsigned long req_size

##### Arguments

`mapping`

  address_space which holds the pagecache and I/O vectors

`ra`

  file_ra_state which holds the readahead state

`filp`

  passed on to ->`readpage` and ->`readpages`

`page`

  the page at `offset` which has the PG_readahead flag set

`offset`

  start offset into `mapping`, in pagecache page-sized units

`req_size`

  hint: total size of the read which the caller is performing in pagecache pages

##### Description

`page_cache_async_ondemand` should be called when a page is used which

##### has the PG_readahead flag

this is a marker to suggest that the application has used up enough of the readahead window that we should start pulling in

#### LINUX

Kernel Hackers Manual January 2008
filemap_flush
9
2.6.24-rc6-git8

#### filemap_flush

mostly a non-blocking flush

##### Synopsis

       int filemap_flush
       struct address_space * mapping

##### Arguments

`mapping`

  target address_space

##### Description

This is a mostly non-blocking flush. Not suitable for data-integrity purposes - I/O may not be started against all dirty pages.

#### LINUX

Kernel Hackers Manual January 2008
sync_page_range
9
2.6.24-rc6-git8

#### sync_page_range

write and wait on all pages in the passed range

##### Synopsis

       int sync_page_range
       struct inode * inode
       struct address_space * mapping
       loff_t pos
       loff_t count

##### Arguments

`inode`

  target inode

`mapping`

  target address_space

`pos`

  beginning offset in pages to write

`count`

  number of bytes to write

##### Description

Write and wait upon all the pages in the passed range. This is a data integrity operation. It waits upon in-flight writeout before starting and waiting upon new writeout. If there was an IO error, return it.

We need to re-take i_mutex during the generic_osync_inode list walk because it is otherwise livelockable.

#### LINUX

Kernel Hackers Manual January 2008
sync_page_range_nolock
9
2.6.24-rc6-git8

#### sync_page_range_nolock

##### Synopsis

       int sync_page_range_nolock
       struct inode * inode
       struct address_space * mapping
       loff_t pos
       loff_t count

##### Arguments

`inode`

  target inode

`mapping`

  target address_space

`pos`

  beginning offset in pages to write

`count`

  number of bytes to write

##### Note

Holding i_mutex across `sync_page_range_nolock` is not a good idea as it forces O_SYNC writers to different parts of the same file to be serialised right until io completion.

#### LINUX

Kernel Hackers Manual January 2008
filemap_fdatawait
9
2.6.24-rc6-git8

#### filemap_fdatawait

wait for all under-writeback pages to complete

##### Synopsis

       int filemap_fdatawait
       struct address_space * mapping

##### Arguments

`mapping`

  address space structure to wait for

##### Description

Walk the list of under-writeback pages of the given address space and wait for all of them.

#### LINUX

Kernel Hackers Manual January 2008
add_to_page_cache
9
2.6.24-rc6-git8

#### add_to_page_cache

add newly allocated pagecache pages

##### Synopsis

       int add_to_page_cache
       struct page * page
       struct address_space * mapping
       pgoff_t offset
       gfp_t gfp_mask

##### Arguments

`page`

  page to add

`mapping`

  the page's address_space

`offset`

  page index

`gfp_mask`

  page allocation mode

##### Description

This function is used to add newly allocated pagecache pages; the page is new, so we can just run `SetPageLocked` against it. The other page state flags were set by `rmqueue`.

This function does not add the page to the LRU. The caller must do that.

#### LINUX

Kernel Hackers Manual January 2008
unlock_page
9
2.6.24-rc6-git8

#### unlock_page

unlock a locked page

##### Synopsis

       void fastcall unlock_page
       struct page * page

##### Arguments

`page`

  the page

##### Description

Unlocks the page and wakes up sleepers in `___wait_on_page_locked`. Also wakes sleepers in `wait_on_page_writeback` because the wakeup mechananism between PageLocked pages and PageWriteback pages is shared. But that's OK - sleepers in `wait_on_page_writeback` just go back to sleep.

The first mb is necessary to safely close the critical section opened by the `TestSetPageLocked`, the second mb is necessary to enforce ordering between the clear_bit and the read of the waitqueue (to avoid SMP races with a parallel `wait_on_page_locked`).

#### LINUX

Kernel Hackers Manual January 2008
end_page_writeback
9
2.6.24-rc6-git8

#### end_page_writeback

end writeback against a page

##### Synopsis

       void end_page_writeback
       struct page * page

##### Arguments

`page`

  the page

#### LINUX

Kernel Hackers Manual January 2008
__lock_page
9
2.6.24-rc6-git8

#### __lock_page

get a lock on the page, assuming we need to sleep to get it

##### Synopsis

       void fastcall __lock_page
       struct page * page

##### Arguments

`page`

  the page to lock

##### Description

Ugly. Running `sync_page` in state TASK_UNINTERRUPTIBLE is scary. If some random driver's requestfn sets TASK_RUNNING, we could busywait. However chances are that on the second loop, the block layer's plug list is empty, so `sync_page` will then return in state TASK_UNINTERRUPTIBLE.

#### LINUX

Kernel Hackers Manual January 2008
find_get_page
9
2.6.24-rc6-git8

#### find_get_page

find and get a page reference

##### Synopsis

       struct page * find_get_page
       struct address_space * mapping
       pgoff_t offset

##### Arguments

`mapping`

  the address_space to search

`offset`

  the page index

##### Description

Is there a pagecache struct page at the given (mapping, offset) tuple? If yes, increment its refcount and return it; if no, return NULL.

#### LINUX

Kernel Hackers Manual January 2008
find_lock_page
9
2.6.24-rc6-git8

#### find_lock_page

locate, pin and lock a pagecache page

##### Synopsis

       struct page * find_lock_page
       struct address_space * mapping
       pgoff_t offset

##### Arguments

`mapping`

  the address_space to search

`offset`

  the page index

##### Description

Locates the desired pagecache page, locks it, increments its reference count and returns its address.

Returns zero if the page was not present. `find_lock_page` may sleep.

#### LINUX

Kernel Hackers Manual January 2008
find_or_create_page
9
2.6.24-rc6-git8

#### find_or_create_page

locate or add a pagecache page

##### Synopsis

       struct page * find_or_create_page
       struct address_space * mapping
       pgoff_t index
       gfp_t gfp_mask

##### Arguments

`mapping`

  the page's address_space

`index`

  the page's index into the mapping

`gfp_mask`

  page allocation mode

##### Description

Locates a page in the pagecache. If the page is not present, a new page is allocated using `gfp_mask` and is added to the pagecache and to the VM's LRU list. The returned page is locked and has its reference count incremented.

`find_or_create_page` may sleep, even if `gfp_flags` specifies an atomic allocation!

`find_or_create_page` returns the desired page's address, or zero on memory exhaustion.

#### LINUX

Kernel Hackers Manual January 2008
find_get_pages_contig
9
2.6.24-rc6-git8

#### find_get_pages_contig

gang contiguous pagecache lookup

##### Synopsis

       unsigned find_get_pages_contig
       struct address_space * mapping
       pgoff_t index
       unsigned int nr_pages
       struct page ** pages

##### Arguments

`mapping`

  The address_space to search

`index`

  The starting page index

`nr_pages`

  The maximum number of pages

`pages`

  Where the resulting pages are placed

##### Description

`find_get_pages_contig` works exactly like `find_get_pages`, except that the returned number of pages are guaranteed to be contiguous.

`find_get_pages_contig` returns the number of pages which were found.

#### LINUX

Kernel Hackers Manual January 2008
find_get_pages_tag
9
2.6.24-rc6-git8

#### find_get_pages_tag

find and return pages that match `tag`

##### Synopsis

       unsigned find_get_pages_tag
       struct address_space * mapping
       pgoff_t * index
       int tag
       unsigned int nr_pages
       struct page ** pages

##### Arguments

`mapping`

  the address_space to search

`index`

  the starting page index

`tag`

  the tag index

`nr_pages`

  the maximum number of pages

`pages`

  where the resulting pages are placed

##### Description

Like find_get_pages, except we only return pages which are tagged with `tag`. We update `index` to index the next page for the traversal.

#### LINUX

Kernel Hackers Manual January 2008
grab_cache_page_nowait
9
2.6.24-rc6-git8

#### grab_cache_page_nowait

returns locked page at given index in given cache

##### Synopsis

       struct page * grab_cache_page_nowait
       struct address_space * mapping
       pgoff_t index

##### Arguments

`mapping`

  target address_space

`index`

  the page index

##### Description

Same as `grab_cache_page`, but do not wait if the page is unavailable. This is intended for speculative data generators, where the data can be regenerated if the page couldn't be grabbed. This routine should be safe to call while holding the lock for another page.

Clear __GFP_FS when allocating the page to avoid recursion into the fs and deadlock against the caller's locked page.

#### LINUX

Kernel Hackers Manual January 2008
do_generic_mapping_read
9
2.6.24-rc6-git8

#### do_generic_mapping_read

generic file read routine

##### Synopsis

       void do_generic_mapping_read
       struct address_space * mapping
       struct file_ra_state * ra
       struct file * filp
       loff_t * ppos
       read_descriptor_t * desc
       read_actor_t actor

##### Arguments

`mapping`

  address_space to be read

`ra`

  file's readahead state

`filp`

  the file to read

`ppos`

  current file position

`desc`

  read_descriptor

`actor`

  read method

##### Description

This is a generic file read routine, and uses the mapping->a_ops->`readpage` function for the actual low-level stuff.

This is really ugly. But the goto's actually try to clarify some of the logic when it comes to error handling etc.

Note the struct file* is only passed for the use of readpage. It may be NULL.

#### LINUX

Kernel Hackers Manual January 2008
generic_file_aio_read
9
2.6.24-rc6-git8

#### generic_file_aio_read

generic filesystem read routine

##### Synopsis

       ssize_t generic_file_aio_read
       struct kiocb * iocb
       const struct iovec * iov
       unsigned long nr_segs
       loff_t pos

##### Arguments

`iocb`

  kernel I/O control block

`iov`

  io vector request

`nr_segs`

  number of segments in the iovec

`pos`

  current file position

##### Description

This is the `read` routine for all filesystems that can use the page cache directly.

#### LINUX

Kernel Hackers Manual January 2008
filemap_fault
9
2.6.24-rc6-git8

#### filemap_fault

read in file data for page fault handling

##### Synopsis

       int filemap_fault
       struct vm_area_struct * vma
       struct vm_fault * vmf

##### Arguments

`vma`

  vma in which the fault was taken

`vmf`

  struct vm_fault containing details of the fault

##### Description

`filemap_fault` is invoked via the vma operations vector for a mapped memory region to read in file data during a page fault.

The goto's are kind of ugly, but this streamlines the normal case of having it in the page cache, and handles the special cases reasonably without having a lot of duplicated code.

#### LINUX

Kernel Hackers Manual January 2008
read_cache_page
9
2.6.24-rc6-git8

#### read_cache_page

read into page cache, fill it if needed

##### Synopsis

       struct page * read_cache_page
       struct address_space * mapping
       pgoff_t index
       int (*filler)
         void *,struct page*
       void * data

##### Arguments

`mapping`

  the page's address_space

`index`

  the page index

`filler`

  function to perform the read

`data`

  destination for read data

##### Description

Read into the page cache. If a page already exists, and `PageUptodate` is not set, try to fill the page then wait for it to become unlocked.

If the page does not get brought uptodate, return -EIO.

#### LINUX

Kernel Hackers Manual January 2008
try_to_release_page
9
2.6.24-rc6-git8

#### try_to_release_page

release old fs-specific metadata on a page

##### Synopsis

       int try_to_release_page
       struct page * page
       gfp_t gfp_mask

##### Arguments

`page`

  the page which the kernel is trying to free

`gfp_mask`

  memory allocation flags (and I/O mode)

##### Description

The address_space is to try to release any data against the page (presumably at page->private). If the release was successful, return `1'. Otherwise return zero.

The `gfp_mask` argument specifies whether I/O may be performed to release this page (__GFP_IO), and whether the call may block (__GFP_WAIT).

##### Description

The address_space is to try to release any data against the page (presumably at page->private). If the release was successful, return `1'. Otherwise return zero.

The `gfp_mask` argument specifies whether I/O may be performed to release this page (__GFP_IO), and whether the call may block (__GFP_WAIT).

##### NOTE

`gfp_mask` may go away, and this function may become non-blocking.

#### LINUX

Kernel Hackers Manual January 2008
vm_insert_page
9
2.6.24-rc6-git8

#### vm_insert_page

insert single page into user vma

##### Synopsis

       int vm_insert_page
       struct vm_area_struct * vma
       unsigned long addr
       struct page * page

##### Arguments

`vma`

  user vma to map to

`addr`

  target user address of this page

`page`

  source kernel page

##### Description

This allows drivers to insert individual pages they've allocated into a user vma.

The page has to be a nice clean _individual_ kernel allocation. If you allocate a compound page, you need to have marked it as such (__GFP_COMP), or manually just split the page up yourself (see `split_page`).

NOTE! Traditionally this was done with `remap_pfn_range` which took an arbitrary page protection parameter. This doesn't allow that. Your vma protection will have to be set up correctly, which means that if you want a shared writable mapping, you'd better ask for a shared writable mapping!

The page does not need to be reserved.

#### LINUX

Kernel Hackers Manual January 2008
vm_insert_pfn
9
2.6.24-rc6-git8

#### vm_insert_pfn

insert single pfn into user vma

##### Synopsis

       int vm_insert_pfn
       struct vm_area_struct * vma
       unsigned long addr
       unsigned long pfn

##### Arguments

`vma`

  user vma to map to

`addr`

  target user address of this page

`pfn`

  source kernel pfn

##### Description

Similar to vm_inert_page, this allows drivers to insert individual pages they've allocated into a user vma. Same comments apply.

This function should only be called from a vm_ops->fault handler, and in that case the handler should return NULL.

#### LINUX

Kernel Hackers Manual January 2008
remap_pfn_range
9
2.6.24-rc6-git8

#### remap_pfn_range

remap kernel memory to userspace

##### Synopsis

       int remap_pfn_range
       struct vm_area_struct * vma
       unsigned long addr
       unsigned long pfn
       unsigned long size
       pgprot_t prot

##### Arguments

`vma`

  user vma to map to

`addr`

  target user address to start at

`pfn`

  physical address of kernel memory

`size`

  size of map area

`prot`

  page protection flags for this mapping

##### Note

this is only safe if the mm semaphore is held when called.

#### LINUX

Kernel Hackers Manual January 2008
unmap_mapping_range
9
2.6.24-rc6-git8

#### unmap_mapping_range

unmap the portion of all mmaps in the specified address_space corresponding to the specified page range in the underlying file.

##### Synopsis

       void unmap_mapping_range
       struct address_space * mapping
       loff_t const holebegin
       loff_t const holelen
       int even_cows

##### Arguments

`mapping`

  the address space containing mmaps to be unmapped.

`holebegin`

  byte in first page to unmap, relative to the start of the underlying file. This will be rounded down to a PAGE_SIZE boundary. Note that this is different from `vmtruncate`, which must keep the partial page. In contrast, we must get rid of partial pages.

`holelen`

  size of prospective hole in bytes. This will be rounded up to a PAGE_SIZE boundary. A holelen of zero truncates to the end of the file.

`even_cows`

  1 when truncating a file, unmap even private COWed pages; but 0 when invalidating pagecache, don't throw away private data.

#### LINUX

Kernel Hackers Manual January 2008
vmtruncate
9
2.6.24-rc6-git8

#### vmtruncate

unmap mappings freed by `truncate` syscall

##### Synopsis

       int vmtruncate
       struct inode * inode
       loff_t offset

##### Arguments

`inode`

  inode of the file used

`offset`

  file offset to start truncating

##### Description

NOTE! We have to be ready to update the memory sharing between the file and the memory map for a potential last incomplete page. Ugly, but necessary.

#### LINUX

Kernel Hackers Manual January 2008
vfree
9
2.6.24-rc6-git8

#### vfree

release memory allocated by `vmalloc`

##### Synopsis

       void vfree
       void * addr

##### Arguments

`addr`

  memory base address

##### Description

Free the virtually continuous memory area starting at `addr`, as obtained from `vmalloc`, `vmalloc_32` or `__vmalloc`. If `addr` is NULL, no operation is performed.

Must not be called in interrupt context.

#### LINUX

Kernel Hackers Manual January 2008
vunmap
9
2.6.24-rc6-git8

#### vunmap

release virtual mapping obtained by `vmap`

##### Synopsis

       void vunmap
       void * addr

##### Arguments

`addr`

  memory base address

##### Description

Free the virtually contiguous memory area starting at `addr`, which was created from the page array passed to `vmap`.

Must not be called in interrupt context.

#### LINUX

Kernel Hackers Manual January 2008
vmap
9
2.6.24-rc6-git8

#### vmap

map an array of pages into virtually contiguous space

##### Synopsis

       void * vmap
       struct page ** pages
       unsigned int count
       unsigned long flags
       pgprot_t prot

##### Arguments

`pages`

  array of page pointers

`count`

  number of pages to map

`flags`

  vm_area->flags

`prot`

  page protection for the mapping

##### Description

Maps `count` pages from `pages` into contiguous kernel virtual space.

#### LINUX

Kernel Hackers Manual January 2008
vmalloc
9
2.6.24-rc6-git8

#### vmalloc

allocate virtually contiguous memory

##### Synopsis

       void * vmalloc
       unsigned long size

##### Arguments

`size`

  allocation size Allocate enough pages to cover `size` from the page level allocator and map them into contiguous kernel virtual space.

##### Description

For tight control over page level allocator and protection flags use `__vmalloc` instead.

#### LINUX

Kernel Hackers Manual January 2008
vmalloc_user
9
2.6.24-rc6-git8

#### vmalloc_user

allocate zeroed virtually contiguous memory for userspace

##### Synopsis

       void * vmalloc_user
       unsigned long size

##### Arguments

`size`

  allocation size

##### Description

The resulting memory area is zeroed so it can be mapped to userspace without leaking data.

#### LINUX

Kernel Hackers Manual January 2008
vmalloc_node
9
2.6.24-rc6-git8

#### vmalloc_node

allocate memory on a specific node

##### Synopsis

       void * vmalloc_node
       unsigned long size
       int node

##### Arguments

`size`

  allocation size

`node`

  numa node

##### Description

Allocate enough pages to cover `size` from the page level allocator and map them into contiguous kernel virtual space.

For tight control over page level allocator and protection flags use `__vmalloc` instead.

#### LINUX

Kernel Hackers Manual January 2008
vmalloc_32
9
2.6.24-rc6-git8

#### vmalloc_32

allocate virtually contiguous memory (32bit addressable)

##### Synopsis

       void * vmalloc_32
       unsigned long size

##### Arguments

`size`

  allocation size

##### Description

Allocate enough 32bit PA addressable pages to cover `size` from the page level allocator and map them into contiguous kernel virtual space.

#### LINUX

Kernel Hackers Manual January 2008
vmalloc_32_user
9
2.6.24-rc6-git8

#### vmalloc_32_user

allocate zeroed virtually contiguous 32bit memory

##### Synopsis

       void * vmalloc_32_user
       unsigned long size

##### Arguments

`size`

  allocation size

##### Description

The resulting memory area is 32bit addressable and zeroed so it can be mapped to userspace without leaking data.

#### LINUX

Kernel Hackers Manual January 2008
remap_vmalloc_range
9
2.6.24-rc6-git8

#### remap_vmalloc_range

map vmalloc pages to userspace

##### Synopsis

       int remap_vmalloc_range
       struct vm_area_struct * vma
       void * addr
       unsigned long pgoff

##### Arguments

`vma`

  vma to cover (map full range of vma)

`addr`

  vmalloc memory

`pgoff`

  number of pages into addr before first page to map

##### Description

This function checks that addr is a valid vmalloc'ed area, and that it is big enough to cover the vma. Will return failure if that criteria isn't met.

Similar to `remap_pfn_range` (see mm/memory.c)

#### LINUX

Kernel Hackers Manual January 2008
alloc_vm_area
9
2.6.24-rc6-git8

#### alloc_vm_area

allocate a range of kernel address space

##### Synopsis

       struct vm_struct * alloc_vm_area
       size_t size

##### Arguments

`size`

  size of the area

##### Description

This function reserves a range of kernel address space, and allocates pagetables to map that range. No actual mappings are created. If the kernel address space is not shared between processes, it syncs the pagetable across all processes.

#### LINUX

Kernel Hackers Manual January 2008
find_next_best_node
9
2.6.24-rc6-git8

#### find_next_best_node

find the next node that should appear in a given node's fallback list

##### Synopsis

       int find_next_best_node
       int node
       nodemask_t * used_node_mask

##### Arguments

`node`

  node whose fallback list we're appending

`used_node_mask`

  nodemask_t of already used nodes

##### Description

We use a number of factors to determine which is the next node that should appear on a given node's fallback list. The node should not have appeared already in `node`'s fallback list, and it should be the next closest node according to the distance array (which contains arbitrary distance values from each node to each node in the system), and should also prefer nodes with no CPUs, since presumably they'll have very little allocation pressure on them otherwise. It returns -1 if no node is found.

#### LINUX

Kernel Hackers Manual January 2008
free_bootmem_with_active_regions
9
2.6.24-rc6-git8

#### free_bootmem_with_active_regions

Call free_bootmem_node for each active range

##### Synopsis

       void __init free_bootmem_with_active_regions
       int nid
       unsigned long max_low_pfn

##### Arguments

`nid`

  The node to free memory on. If MAX_NUMNODES, all nodes are freed.

`max_low_pfn`

  The highest PFN that will be passed to free_bootmem_node

##### Description

If an architecture guarantees that all ranges registered with `add_active_ranges` contain no holes and may be freed, this this function may be used instead of calling `free_bootmem` manually.

#### LINUX

Kernel Hackers Manual January 2008
sparse_memory_present_with_active_regions
9
2.6.24-rc6-git8

#### sparse_memory_present_with_active_regions

Call memory_present for each active range

##### Synopsis

       void __init sparse_memory_present_with_active_regions
       int nid

##### Arguments

`nid`

  The node to call memory_present for. If MAX_NUMNODES, all nodes will be used.

##### Description

If an architecture guarantees that all ranges registered with `add_active_ranges` contain no holes and may be freed, this function may be used instead of calling `memory_present` manually.

#### LINUX

Kernel Hackers Manual January 2008
push_node_boundaries
9
2.6.24-rc6-git8

#### push_node_boundaries

Push node boundaries to at least the requested boundary

##### Synopsis

       void __init push_node_boundaries
       unsigned int nid
       unsigned long start_pfn
       unsigned long end_pfn

##### Arguments

`nid`

  The nid of the node to push the boundary for

`start_pfn`

  The start pfn of the node

`end_pfn`

  The end pfn of the node

##### Description

In reserve-based hot-add, mem_map is allocated that is unused until hotadd time. Specifically, on x86_64, SRAT will report ranges that can potentially be hotplugged even though no physical memory exists. This function allows an arch to push out the node boundaries so mem_map is allocated that can be used later.

#### LINUX

Kernel Hackers Manual January 2008
get_pfn_range_for_nid
9
2.6.24-rc6-git8

#### get_pfn_range_for_nid

Return the start and end page frames for a node

##### Synopsis

       void __meminit get_pfn_range_for_nid
       unsigned int nid
       unsigned long * start_pfn
       unsigned long * end_pfn

##### Arguments

`nid`

  The nid to return the range for. If MAX_NUMNODES, the min and max PFN are returned.

`start_pfn`

  Passed by reference. On return, it will have the node start_pfn.

`end_pfn`

  Passed by reference. On return, it will have the node end_pfn.

##### Description

It returns the start and end page frame of a node based on information provided by an arch calling `add_active_range`. If called for a node with no available memory, a warning is printed and the start and end PFNs will be 0.

#### LINUX

Kernel Hackers Manual January 2008
absent_pages_in_range
9
2.6.24-rc6-git8

#### absent_pages_in_range

Return number of page frames in holes within a range

##### Synopsis

       unsigned long __init absent_pages_in_range
       unsigned long start_pfn
       unsigned long end_pfn

##### Arguments

`start_pfn`

  The start PFN to start searching for holes

`end_pfn`

  The end PFN to stop searching for holes

##### Description

It returns the number of pages frames in memory holes within a range.

#### LINUX

Kernel Hackers Manual January 2008
add_active_range
9
2.6.24-rc6-git8

#### add_active_range

Register a range of PFNs backed by physical memory

##### Synopsis

       void __init add_active_range
       unsigned int nid
       unsigned long start_pfn
       unsigned long end_pfn

##### Arguments

`nid`

  The node ID the range resides on

`start_pfn`

  The start PFN of the available physical memory

`end_pfn`

  The end PFN of the available physical memory

##### Description

These ranges are stored in an early_node_map[] and later used by `free_area_init_nodes` to calculate zone sizes and holes. If the range spans a memory hole, it is up to the architecture to ensure the memory is not freed by the bootmem allocator. If possible the range being registered will be merged with existing ranges.

#### LINUX

Kernel Hackers Manual January 2008
shrink_active_range
9
2.6.24-rc6-git8

#### shrink_active_range

Shrink an existing registered range of PFNs

##### Synopsis

       void __init shrink_active_range
       unsigned int nid
       unsigned long old_end_pfn
       unsigned long new_end_pfn

##### Arguments

`nid`

  The node id the range is on that should be shrunk

`old_end_pfn`

  The old end PFN of the range

`new_end_pfn`

  The new PFN of the range

##### Description

i386 with NUMA use `alloc_remap` to store a node_mem_map on a local node. The map is kept at the end physical page range that has already been registered with `add_active_range`. This function allows an arch to shrink an existing registered range.

#### LINUX

Kernel Hackers Manual January 2008
remove_all_active_ranges
9
2.6.24-rc6-git8

#### remove_all_active_ranges

Remove all currently registered regions

##### Synopsis

       void __init remove_all_active_ranges
        void

##### Arguments

`void`

  no arguments

##### Description

During discovery, it may be found that a table like SRAT is invalid and an alternative discovery method must be used. This function removes all currently registered regions.

#### LINUX

Kernel Hackers Manual January 2008
find_min_pfn_with_active_regions
9
2.6.24-rc6-git8

#### find_min_pfn_with_active_regions

Find the minimum PFN registered

##### Synopsis

       unsigned long __init find_min_pfn_with_active_regions
        void

##### Arguments

`void`

  no arguments

##### Description

It returns the minimum PFN based on information provided via `add_active_range`.

#### LINUX

Kernel Hackers Manual January 2008
find_max_pfn_with_active_regions
9
2.6.24-rc6-git8

#### find_max_pfn_with_active_regions

Find the maximum PFN registered

##### Synopsis

       unsigned long __init find_max_pfn_with_active_regions
        void

##### Arguments

`void`

  no arguments

##### Description

It returns the maximum PFN based on information provided via `add_active_range`.

#### LINUX

Kernel Hackers Manual January 2008
free_area_init_nodes
9
2.6.24-rc6-git8

#### free_area_init_nodes

Initialise all pg_data_t and zone data

##### Synopsis

       void __init free_area_init_nodes
       unsigned long * max_zone_pfn

##### Arguments

`max_zone_pfn`

  an array of max PFNs for each zone

##### Description

This will call `free_area_init_node` for each active node in the system. Using the page ranges provided by `add_active_range`, the size of each zone in each node and their holes is calculated. If the maximum PFN between two adjacent zones match, it is assumed that the zone is empty. For example, if arch_max_dma_pfn == arch_max_dma32_pfn, it is assumed that arch_max_dma32_pfn has no pages. It is also assumed that a zone starts where the previous one ended. For example, ZONE_DMA32 starts at arch_max_dma_pfn.

#### LINUX

Kernel Hackers Manual January 2008
set_dma_reserve
9
2.6.24-rc6-git8

#### set_dma_reserve

set the specified number of pages reserved in the first zone

##### Synopsis

       void __init set_dma_reserve
       unsigned long new_dma_reserve

##### Arguments

`new_dma_reserve`

  The number of pages to mark reserved

##### Description

The per-cpu batchsize and zone watermarks are determined by present_pages. In the DMA zone, a significant percentage may be consumed by kernel image and other unfreeable allocations which can skew the watermarks badly. This function may optionally be used to account for unfreeable pages in the first zone (e.g., ZONE_DMA). The effect will be lower watermarks and smaller per-cpu batchsize.

#### LINUX

Kernel Hackers Manual January 2008
setup_per_zone_pages_min
9
2.6.24-rc6-git8

#### setup_per_zone_pages_min

called when min_free_kbytes changes.

##### Synopsis

       void setup_per_zone_pages_min
        void

##### Arguments

`void`

  no arguments

##### Description

Ensures that the pages_{min,low,high} values for each zone are set correctly with respect to min_free_kbytes.

#### LINUX

Kernel Hackers Manual January 2008
get_pageblock_flags_group
9
2.6.24-rc6-git8

#### get_pageblock_flags_group

Return the requested group of flags for the pageblock_nr_pages block of pages

##### Synopsis

       unsigned long get_pageblock_flags_group
       struct page * page
       int start_bitidx
       int end_bitidx

##### Arguments

`page`

  The page within the block of interest

`start_bitidx`

  The first bit of interest to retrieve

`end_bitidx`

  The last bit of interest returns pageblock_bits flags

#### LINUX

Kernel Hackers Manual January 2008
set_pageblock_flags_group
9
2.6.24-rc6-git8

#### set_pageblock_flags_group

Set the requested group of flags for a pageblock_nr_pages block of pages

##### Synopsis

       void set_pageblock_flags_group
       struct page * page
       unsigned long flags
       int start_bitidx
       int end_bitidx

##### Arguments

`page`

  The page within the block of interest

`flags`

  The flags to set

`start_bitidx`

  The first bit of interest

`end_bitidx`

  The last bit of interest

#### LINUX

Kernel Hackers Manual January 2008
mempool_create
9
2.6.24-rc6-git8

#### mempool_create

create a memory pool

##### Synopsis

       mempool_t * mempool_create
       int min_nr
       mempool_alloc_t * alloc_fn
       mempool_free_t * free_fn
       void * pool_data

##### Arguments

`min_nr`

  the minimum number of elements guaranteed to be allocated for this pool.

`alloc_fn`

  user-defined element-allocation function.

`free_fn`

  user-defined element-freeing function.

`pool_data`

  optional private data available to the user-defined functions.

##### Description

this function creates and allocates a guaranteed size, preallocated memory pool. The pool can be used from the `mempool_alloc` and `mempool_free` functions. This function might sleep. Both the `alloc_fn` and the `free_fn` functions might sleep - as long as the `mempool_alloc` function is not called from IRQ contexts.

#### LINUX

Kernel Hackers Manual January 2008
mempool_resize
9
2.6.24-rc6-git8

#### mempool_resize

resize an existing memory pool

##### Synopsis

       int mempool_resize
       mempool_t * pool
       int new_min_nr
       gfp_t gfp_mask

##### Arguments

`pool`

  pointer to the memory pool which was allocated via `mempool_create`.

`new_min_nr`

  the new minimum number of elements guaranteed to be allocated for this pool.

`gfp_mask`

  the usual allocation bitmask.

##### Description

This function shrinks/grows the pool. In the case of growing, it cannot be guaranteed that the pool will be grown to the new size immediately, but new `mempool_free` calls will refill it.

Note, the caller must guarantee that no mempool_destroy is called while this function is running. `mempool_alloc` & `mempool_free` might be called (eg. from IRQ contexts) while this function executes.

#### LINUX

Kernel Hackers Manual January 2008
mempool_destroy
9
2.6.24-rc6-git8

#### mempool_destroy

deallocate a memory pool

##### Synopsis

       void mempool_destroy
       mempool_t * pool

##### Arguments

`pool`

  pointer to the memory pool which was allocated via `mempool_create`.

##### Description

this function only sleeps if the `free_fn` function sleeps. The caller has to guarantee that all elements have been returned to the pool (ie: freed) prior to calling `mempool_destroy`.

#### LINUX

Kernel Hackers Manual January 2008
mempool_alloc
9
2.6.24-rc6-git8

#### mempool_alloc

allocate an element from a specific memory pool

##### Synopsis

       void * mempool_alloc
       mempool_t * pool
       gfp_t gfp_mask

##### Arguments

`pool`

  pointer to the memory pool which was allocated via `mempool_create`.

`gfp_mask`

  the usual allocation bitmask.

##### Description

this function only sleeps if the `alloc_fn` function sleeps or returns NULL. Note that due to preallocation, this function *never* fails when called from process contexts. (it might fail if called from an IRQ context.)

#### LINUX

Kernel Hackers Manual January 2008
mempool_free
9
2.6.24-rc6-git8

#### mempool_free

return an element to the pool.

##### Synopsis

       void mempool_free
       void * element
       mempool_t * pool

##### Arguments

`element`

  pool element pointer.

`pool`

  pointer to the memory pool which was allocated via `mempool_create`.

##### Description

this function only sleeps if the `free_fn` function sleeps.

#### LINUX

Kernel Hackers Manual January 2008
balance_dirty_pages_ratelimited_nr
9
2.6.24-rc6-git8

#### balance_dirty_pages_ratelimited_nr

balance dirty memory state

##### Synopsis

       void balance_dirty_pages_ratelimited_nr
       struct address_space * mapping
       unsigned long nr_pages_dirtied

##### Arguments

`mapping`

  address_space which was dirtied

`nr_pages_dirtied`

  number of pages which the caller has just dirtied

##### Description

Processes which are dirtying memory should call in here once for each page which was newly dirtied. The function will periodically check the system's dirty state and will initiate writeback if needed.

On really big machines, get_writeback_state is expensive, so try to avoid calling it too often (ratelimiting). But once we're over the dirty memory limit we decrease the ratelimiting by a lot, to prevent individual processes from overshooting the limit by (ratelimit_pages) each.

#### LINUX

Kernel Hackers Manual January 2008
write_cache_pages
9
2.6.24-rc6-git8

#### write_cache_pages

walk the list of dirty pages of the given address space and write all of them.

##### Synopsis

       int write_cache_pages
       struct address_space * mapping
       struct writeback_control * wbc
       writepage_t writepage
       void * data

##### Arguments

`mapping`

  address space structure to write

`wbc`

  subtract the number of written pages from *`wbc`->nr_to_write

`writepage`

  function called for each page

`data`

  data passed to writepage function

##### Description

If a page is already under I/O, `write_cache_pages` skips it, even if it's dirty. This is desirable behaviour for memory-cleaning writeback, but it is INCORRECT for data-integrity system calls such as `fsync`. `fsync` and `msync` need to guarantee that all the data which was dirty at the time the call was made get new I/O started against them. If wbc->sync_mode is WB_SYNC_ALL then we were called for data integrity and we must wait for existing IO to complete.

#### LINUX

Kernel Hackers Manual January 2008
generic_writepages
9
2.6.24-rc6-git8

#### generic_writepages

walk the list of dirty pages of the given address space and `writepage` all of them.

##### Synopsis

       int generic_writepages
       struct address_space * mapping
       struct writeback_control * wbc

##### Arguments

`mapping`

  address space structure to write

`wbc`

  subtract the number of written pages from *`wbc`->nr_to_write

##### Description

This is a library function, which implements the `writepages` address_space_operation.

#### LINUX

Kernel Hackers Manual January 2008
write_one_page
9
2.6.24-rc6-git8

#### write_one_page

write out a single page and optionally wait on I/O

##### Synopsis

       int write_one_page
       struct page * page
       int wait

##### Arguments

`page`

  the page to write

`wait`

  if true, wait on writeout

##### Description

The page must be locked by the caller and will be unlocked upon return.

`write_one_page` returns a negative error code if I/O failed.

#### LINUX

Kernel Hackers Manual January 2008
truncate_inode_pages_range
9
2.6.24-rc6-git8

#### truncate_inode_pages_range

truncate range of pages specified by start and

##### Synopsis

       void truncate_inode_pages_range
       struct address_space * mapping
       loff_t lstart
       loff_t lend

##### Arguments

`mapping`

  mapping to truncate

`lstart`

  offset from which to truncate

`lend`

  offset to which to truncate

##### Description

Truncate the page cache, removing the pages that are between specified offsets (and zeroing out partial page (if lstart is not page aligned)).

Truncate takes two passes - the first pass is nonblocking. It will not block on page locks and it will not block on writeback. The second pass will wait. This is to prevent as much IO as possible in the affected region. The first pass will remove most pages, so the search cost of the second pass is low.

When looking at page->index outside the page lock we need to be careful to copy it into a local to avoid races (it could change at any time).

We pass down the cache-hot hint to the page freeing code. Even if the mapping is large, it is probably the case that the final pages are the most recently touched, and freeing happens in ascending file offset order.

##### Description

Truncate the page cache, removing the pages that are between specified offsets (and zeroing out partial page (if lstart is not page aligned)).

Truncate takes two passes - the first pass is nonblocking. It will not block on page locks and it will not block on writeback. The second pass will wait. This is to prevent as much IO as possible in the affected region. The first pass will remove most pages, so the search cost of the second pass is low.

When looking at page->index outside the page lock we need to be careful to copy it into a local to avoid races (it could change at any time).

We pass down the cache-hot hint to the page freeing code. Even if the mapping is large, it is probably the case that the final pages are the most recently touched, and freeing happens in ascending file offset order.

#### LINUX

Kernel Hackers Manual January 2008
truncate_inode_pages
9
2.6.24-rc6-git8

#### truncate_inode_pages

truncate *all* the pages from an offset

##### Synopsis

       void truncate_inode_pages
       struct address_space * mapping
       loff_t lstart

##### Arguments

`mapping`

  mapping to truncate

`lstart`

  offset from which to truncate

##### Description

Called under (and serialised by) inode->i_mutex.

#### LINUX

Kernel Hackers Manual January 2008
invalidate_mapping_pages
9
2.6.24-rc6-git8

#### invalidate_mapping_pages

Invalidate all the unlocked pages of one inode

##### Synopsis

       unsigned long invalidate_mapping_pages
       struct address_space * mapping
       pgoff_t start
       pgoff_t end

##### Arguments

`mapping`

  the address_space which holds the pages to invalidate

`start`

  the offset 'from' which to invalidate

`end`

  the offset 'to' which to invalidate (inclusive)

##### Description

This function only removes the unlocked pages, if you want to remove all the pages of one inode, you must call truncate_inode_pages.

`invalidate_mapping_pages` will not block on IO activity. It will not invalidate pages which are dirty, locked, under writeback or mapped into pagetables.

#### LINUX

Kernel Hackers Manual January 2008
invalidate_inode_pages2_range
9
2.6.24-rc6-git8

#### invalidate_inode_pages2_range

remove range of pages from an address_space

##### Synopsis

       int invalidate_inode_pages2_range
       struct address_space * mapping
       pgoff_t start
       pgoff_t end

##### Arguments

`mapping`

  the address_space

`start`

  the page offset 'from' which to invalidate

`end`

  the page offset 'to' which to invalidate (inclusive)

##### Description

Any pages which are found to be mapped into pagetables are unmapped prior to invalidation.

Returns -EIO if any pages could not be invalidated.

#### LINUX

Kernel Hackers Manual January 2008
invalidate_inode_pages2
9
2.6.24-rc6-git8

#### invalidate_inode_pages2

remove all pages from an address_space

##### Synopsis

       int invalidate_inode_pages2
       struct address_space * mapping

##### Arguments

`mapping`

  the address_space

##### Description

Any pages which are found to be mapped into pagetables are unmapped prior to invalidation.

Returns -EIO if any pages could not be invalidated.

## Kernel IPC facilities

### IPC utilities

#### LINUX

Kernel Hackers Manual January 2008
ipc_init
9
2.6.24-rc6-git8

#### ipc_init

initialise IPC subsystem

##### Synopsis

       int __init ipc_init
        void

##### Arguments

`void`

  no arguments

##### Description

The various system5 IPC resources (semaphores, messages and shared memory) are initialised

#### LINUX

Kernel Hackers Manual January 2008
ipc_init_ids
9
2.6.24-rc6-git8

#### ipc_init_ids

initialise IPC identifiers

##### Synopsis

       void ipc_init_ids
       struct ipc_ids * ids

##### Arguments

`ids`

  Identifier set

##### Description

Set up the sequence range to use for the ipc identifier range (limited below IPCMNI) then initialise the ids idr.

#### LINUX

Kernel Hackers Manual January 2008
ipc_init_proc_interface
9
2.6.24-rc6-git8

#### ipc_init_proc_interface

Create a proc interface for sysipc types using a seq_file interface.

##### Synopsis

       void __init ipc_init_proc_interface
       const char * path
       const char * header
       int ids
       int (*show)
         struct seq_file *, void *

##### Arguments

`path`

  Path in procfs

`header`

  Banner to be printed at the beginning of the file.

`ids`

  ipc id table to iterate.

`show`

  show routine.

#### LINUX

Kernel Hackers Manual January 2008
ipc_findkey
9
2.6.24-rc6-git8

#### ipc_findkey

find a key in an ipc identifier set

##### Synopsis

       struct kern_ipc_perm * ipc_findkey
       struct ipc_ids * ids
       key_t key

##### Arguments

`ids`

  Identifier set

`key`

  The key to find

##### Description

Requires ipc_ids.rw_mutex locked. Returns the LOCKED pointer to the ipc structure if found or NULL if not. If key is found ipc points to the owning ipc structure

#### LINUX

Kernel Hackers Manual January 2008
ipc_get_maxid
9
2.6.24-rc6-git8

#### ipc_get_maxid

get the last assigned id

##### Synopsis

       int ipc_get_maxid
       struct ipc_ids * ids

##### Arguments

`ids`

  IPC identifier set

##### Description

Called with ipc_ids.rw_mutex held.

#### LINUX

Kernel Hackers Manual January 2008
ipc_addid
9
2.6.24-rc6-git8

#### ipc_addid

add an IPC identifier

##### Synopsis

       int ipc_addid
       struct ipc_ids * ids
       struct kern_ipc_perm * new
       int size

##### Arguments

`ids`

  IPC identifier set

`new`

  new IPC permission set

`size`

  limit for the number of used ids

##### Description

Add an entry 'new' to the IPC ids idr. The permissions object is initialised and the first free entry is set up and the id assigned is returned. The 'new' entry is returned in a locked state on success. On failure the entry is not locked and a negative err-code is returned.

Called with ipc_ids.rw_mutex held as a writer.

#### LINUX

Kernel Hackers Manual January 2008
ipcget_new
9
2.6.24-rc6-git8

#### ipcget_new

create a new ipc object

##### Synopsis

       int ipcget_new
       struct ipc_namespace * ns
       struct ipc_ids * ids
       struct ipc_ops * ops
       struct ipc_params * params

##### Arguments

`ns`

  namespace

`ids`

  IPC identifer set

`ops`

  the actual creation routine to call

`params`

  its parameters

##### Description

This routine is called by sys_msgget, `sys_semget` and `sys_shmget` when the key is IPC_PRIVATE.

#### LINUX

Kernel Hackers Manual January 2008
ipc_check_perms
9
2.6.24-rc6-git8

#### ipc_check_perms

check security and permissions for an IPC

##### Synopsis

       int ipc_check_perms
       struct kern_ipc_perm * ipcp
       struct ipc_ops * ops
       struct ipc_params * params

##### Arguments

`ipcp`

  ipc permission set

`ops`

  the actual security routine to call

`params`

  its parameters

##### Description

This routine is called by `sys_msgget`, `sys_semget` and `sys_shmget` when the key is not IPC_PRIVATE and that key already exists in the ids IDR.

On success, the IPC id is returned.

It is called with ipc_ids.rw_mutex and ipcp->lock held.

#### LINUX

Kernel Hackers Manual January 2008
ipcget_public
9
2.6.24-rc6-git8

#### ipcget_public

get an ipc object or create a new one

##### Synopsis

       int ipcget_public
       struct ipc_namespace * ns
       struct ipc_ids * ids
       struct ipc_ops * ops
       struct ipc_params * params

##### Arguments

`ns`

  namespace

`ids`

  IPC identifer set

`ops`

  the actual creation routine to call

`params`

  its parameters

##### Description

This routine is called by sys_msgget, `sys_semget` and `sys_shmget` when the key is not IPC_PRIVATE. It adds a new entry if the key is not found and does some permission / security checkings if the key is found.

On success, the ipc id is returned.

#### LINUX

Kernel Hackers Manual January 2008
ipc_rmid
9
2.6.24-rc6-git8

#### ipc_rmid

remove an IPC identifier

##### Synopsis

       void ipc_rmid
       struct ipc_ids * ids
       struct kern_ipc_perm * ipcp

##### Arguments

`ids`

  IPC identifier set

`ipcp`

  ipc perm structure containing the identifier to remove

##### Description

ipc_ids.rw_mutex (as a writer) and the spinlock for this ID are held before this function is called, and remain locked on the exit.

#### LINUX

Kernel Hackers Manual January 2008
ipc_alloc
9
2.6.24-rc6-git8

#### ipc_alloc

allocate ipc space

##### Synopsis

       void* ipc_alloc
       int size

##### Arguments

`size`

  size desired

##### Description

Allocate memory from the appropriate pools and return a pointer to it. NULL is returned if the allocation fails

#### LINUX

Kernel Hackers Manual January 2008
ipc_free
9
2.6.24-rc6-git8

#### ipc_free

free ipc space

##### Synopsis

       void ipc_free
       void * ptr
       int size

##### Arguments

`ptr`

  pointer returned by ipc_alloc

`size`

  size of block

##### Description

Free a block created with `ipc_alloc`. The caller must know the size used in the allocation call.

#### LINUX

Kernel Hackers Manual January 2008
ipc_rcu_alloc
9
2.6.24-rc6-git8

#### ipc_rcu_alloc

allocate ipc and rcu space

##### Synopsis

       void* ipc_rcu_alloc
       int size

##### Arguments

`size`

  size desired

##### Description

Allocate memory for the rcu header structure + the object. Returns the pointer to the object. NULL is returned if the allocation fails.

#### LINUX

Kernel Hackers Manual January 2008
ipc_schedule_free
9
2.6.24-rc6-git8

#### ipc_schedule_free

free ipc + rcu space

##### Synopsis

       void ipc_schedule_free
       struct rcu_head * head

##### Arguments

`head`

  RCU callback structure for queued work

##### Description

Since RCU callback function is called in bh, we need to defer the vfree to `schedule_work`.

#### LINUX

Kernel Hackers Manual January 2008
ipc_immediate_free
9
2.6.24-rc6-git8

#### ipc_immediate_free

free ipc + rcu space

##### Synopsis

       void ipc_immediate_free
       struct rcu_head * head

##### Arguments

`head`

  RCU callback structure that contains pointer to be freed

##### Description

Free from the RCU callback context.

#### LINUX

Kernel Hackers Manual January 2008
ipcperms
9
2.6.24-rc6-git8

#### ipcperms

check IPC permissions

##### Synopsis

       int ipcperms
       struct kern_ipc_perm * ipcp
       short flag

##### Arguments

`ipcp`

  IPC permission set

`flag`

  desired permission set.

##### Description

Check user, group, other permissions for access to ipc resources. return 0 if allowed

#### LINUX

Kernel Hackers Manual January 2008
kernel_to_ipc64_perm
9
2.6.24-rc6-git8

#### kernel_to_ipc64_perm

convert kernel ipc permissions to user

##### Synopsis

       void kernel_to_ipc64_perm
       struct kern_ipc_perm * in
       struct ipc64_perm * out

##### Arguments

`in`

  kernel permissions

`out`

  new style IPC permissions

##### Description

Turn the kernel object `in` into a set of permissions descriptions for returning to userspace (`out`).

#### LINUX

Kernel Hackers Manual January 2008
ipc64_perm_to_ipc_perm
9
2.6.24-rc6-git8

#### ipc64_perm_to_ipc_perm

convert new ipc permissions to old

##### Synopsis

       void ipc64_perm_to_ipc_perm
       struct ipc64_perm * in
       struct ipc_perm * out

##### Arguments

`in`

  new style IPC permissions

`out`

  old style IPC permissions

##### Description

Turn the new style permissions object `in` into a compatibility object and store it into the `out` pointer.

#### LINUX

Kernel Hackers Manual January 2008
ipc_lock
9
2.6.24-rc6-git8

#### ipc_lock

Lock an ipc structure without rw_mutex held

##### Synopsis

       struct kern_ipc_perm * ipc_lock
       struct ipc_ids * ids
       int id

##### Arguments

`ids`

  IPC identifier set

`id`

  ipc id to look for

##### Description

Look for an id in the ipc ids idr and lock the associated ipc object.

The ipc object is locked on exit.

This is the routine that should be called when the rw_mutex is not already held, i.e. idr tree not protected: it protects the idr tree in read mode during the `idr_find`.

#### LINUX

Kernel Hackers Manual January 2008
ipc_lock_down
9
2.6.24-rc6-git8

#### ipc_lock_down

Lock an ipc structure with rw_sem held

##### Synopsis

       struct kern_ipc_perm * ipc_lock_down
       struct ipc_ids * ids
       int id

##### Arguments

`ids`

  IPC identifier set

`id`

  ipc id to look for

##### Description

Look for an id in the ipc ids idr and lock the associated ipc object.

The ipc object is locked on exit.

This is the routine that should be called when the rw_mutex is already held, i.e. idr tree protected.

#### LINUX

Kernel Hackers Manual January 2008
ipc_parse_version
9
2.6.24-rc6-git8

#### ipc_parse_version

IPC call version

##### Synopsis

       int ipc_parse_version
       int * cmd

##### Arguments

`cmd`

  pointer to command

##### Description

Return IPC_64 for new style IPC and IPC_OLD for old style IPC. The `cmd` value is turned from an encoding command and version into just the command code.

## FIFO Buffer

### kfifo interface

#### LINUX

Kernel Hackers Manual January 2008
__kfifo_reset
9
2.6.24-rc6-git8

#### __kfifo_reset

removes the entire FIFO contents, no locking version

##### Synopsis

       void __kfifo_reset
       struct kfifo * fifo

##### Arguments

`fifo`

  the fifo to be emptied.

#### LINUX

Kernel Hackers Manual January 2008
kfifo_reset
9
2.6.24-rc6-git8

#### kfifo_reset

removes the entire FIFO contents

##### Synopsis

       void kfifo_reset
       struct kfifo * fifo

##### Arguments

`fifo`

  the fifo to be emptied.

#### LINUX

Kernel Hackers Manual January 2008
kfifo_put
9
2.6.24-rc6-git8

#### kfifo_put

puts some data into the FIFO

##### Synopsis

       unsigned int kfifo_put
       struct kfifo * fifo
       unsigned char * buffer
       unsigned int len

##### Arguments

`fifo`

  the fifo to be used.

`buffer`

  the data to be added.

`len`

  the length of the data to be added.

##### Description

This function copies at most `len` bytes from the `buffer` into the FIFO depending on the free space, and returns the number of bytes copied.

#### LINUX

Kernel Hackers Manual January 2008
kfifo_get
9
2.6.24-rc6-git8

#### kfifo_get

gets some data from the FIFO

##### Synopsis

       unsigned int kfifo_get
       struct kfifo * fifo
       unsigned char * buffer
       unsigned int len

##### Arguments

`fifo`

  the fifo to be used.

`buffer`

  where the data must be copied.

`len`

  the size of the destination buffer.

##### Description

This function copies at most `len` bytes from the FIFO into the `buffer` and returns the number of copied bytes.

#### LINUX

Kernel Hackers Manual January 2008
__kfifo_len
9
2.6.24-rc6-git8

#### __kfifo_len

returns the number of bytes available in the FIFO, no locking version

##### Synopsis

       unsigned int __kfifo_len
       struct kfifo * fifo

##### Arguments

`fifo`

  the fifo to be used.

#### LINUX

Kernel Hackers Manual January 2008
kfifo_len
9
2.6.24-rc6-git8

#### kfifo_len

returns the number of bytes available in the FIFO

##### Synopsis

       unsigned int kfifo_len
       struct kfifo * fifo

##### Arguments

`fifo`

  the fifo to be used.

#### LINUX

Kernel Hackers Manual January 2008
kfifo_init
9
2.6.24-rc6-git8

#### kfifo_init

allocates a new FIFO using a preallocated buffer

##### Synopsis

       struct kfifo * kfifo_init
       unsigned char * buffer
       unsigned int size
       gfp_t gfp_mask
       spinlock_t * lock

##### Arguments

`buffer`

  the preallocated buffer to be used.

`size`

  the size of the internal buffer, this have to be a power of 2.

`gfp_mask`

  get_free_pages mask, passed to `kmalloc`

`lock`

  the lock to be used to protect the fifo buffer

##### Description

Do NOT pass the kfifo to `kfifo_free` after use! Simply free the &struct kfifo with `kfree`.

#### LINUX

Kernel Hackers Manual January 2008
kfifo_alloc
9
2.6.24-rc6-git8

#### kfifo_alloc

allocates a new FIFO and its internal buffer

##### Synopsis

       struct kfifo * kfifo_alloc
       unsigned int size
       gfp_t gfp_mask
       spinlock_t * lock

##### Arguments

`size`

  the size of the internal buffer to be allocated.

`gfp_mask`

  get_free_pages mask, passed to `kmalloc`

`lock`

  the lock to be used to protect the fifo buffer

##### Description

The size will be rounded-up to a power of 2.

#### LINUX

Kernel Hackers Manual January 2008
kfifo_free
9
2.6.24-rc6-git8

#### kfifo_free

frees the FIFO

##### Synopsis

       void kfifo_free
       struct kfifo * fifo

##### Arguments

`fifo`

  the fifo to be freed.

#### LINUX

Kernel Hackers Manual January 2008
__kfifo_put
9
2.6.24-rc6-git8

#### __kfifo_put

puts some data into the FIFO, no locking version

##### Synopsis

       unsigned int __kfifo_put
       struct kfifo * fifo
       unsigned char * buffer
       unsigned int len

##### Arguments

`fifo`

  the fifo to be used.

`buffer`

  the data to be added.

`len`

  the length of the data to be added.

##### Description

This function copies at most `len` bytes from the `buffer` into the FIFO depending on the free space, and returns the number of bytes copied.

Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these functions.

#### LINUX

Kernel Hackers Manual January 2008
__kfifo_get
9
2.6.24-rc6-git8

#### __kfifo_get

gets some data from the FIFO, no locking version

##### Synopsis

       unsigned int __kfifo_get
       struct kfifo * fifo
       unsigned char * buffer
       unsigned int len

##### Arguments

`fifo`

  the fifo to be used.

`buffer`

  where the data must be copied.

`len`

  the size of the destination buffer.

##### Description

This function copies at most `len` bytes from the FIFO into the `buffer` and returns the number of copied bytes.

Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these functions.

## relay interface support

Relay interface support is designed to provide an efficient mechanism for tools and facilities to relay large amounts of data from kernel space to user space.

### relay interface

#### LINUX

Kernel Hackers Manual January 2008
relay_buf_full
9
2.6.24-rc6-git8

#### relay_buf_full

boolean, is the channel buffer full?

##### Synopsis

       int relay_buf_full
       struct rchan_buf * buf

##### Arguments

`buf`

  channel buffer

##### Description

Returns 1 if the buffer is full, 0 otherwise.

#### LINUX

Kernel Hackers Manual January 2008
relay_reset
9
2.6.24-rc6-git8

#### relay_reset

reset the channel

##### Synopsis

       void relay_reset
       struct rchan * chan

##### Arguments

`chan`

  the channel

##### Description

This has the effect of erasing all data from all channel buffers and restarting the channel in its initial state. The buffers are not freed, so any mappings are still in effect.

NOTE. Care should be taken that the channel isn't actually being used by anything when this call is made.

#### LINUX

Kernel Hackers Manual January 2008
relay_open
9
2.6.24-rc6-git8

#### relay_open

create a new relay channel

##### Synopsis

       struct rchan * relay_open
       const char * base_filename
       struct dentry * parent
       size_t subbuf_size
       size_t n_subbufs
       struct rchan_callbacks * cb
       void * private_data

##### Arguments

`base_filename`

  base name of files to create

`parent`

  dentry of parent directory, `NULL` for root directory

`subbuf_size`

  size of sub-buffers

`n_subbufs`

  number of sub-buffers

`cb`

  client callback functions

`private_data`

  user-defined data

##### Description

Returns channel pointer if successful, `NULL` otherwise.

Creates a channel buffer for each cpu using the sizes and attributes specified. The created channel buffer files will be named base_filename0...base_filenameN-1. File permissions will be `S_IRUSR`.

#### LINUX

Kernel Hackers Manual January 2008
relay_switch_subbuf
9
2.6.24-rc6-git8

#### relay_switch_subbuf

switch to a new sub-buffer

##### Synopsis

       size_t relay_switch_subbuf
       struct rchan_buf * buf
       size_t length

##### Arguments

`buf`

  channel buffer

`length`

  size of current event

##### Description

Returns either the length passed in or 0 if full.

Performs sub-buffer-switch tasks such as invoking callbacks, updating padding counts, waking up readers, etc.

#### LINUX

Kernel Hackers Manual January 2008
relay_subbufs_consumed
9
2.6.24-rc6-git8

#### relay_subbufs_consumed

update the buffer's sub-buffers-consumed count

##### Synopsis

       void relay_subbufs_consumed
       struct rchan * chan
       unsigned int cpu
       size_t subbufs_consumed

##### Arguments

`chan`

  the channel

`cpu`

  the cpu associated with the channel buffer to update

`subbufs_consumed`

  number of sub-buffers to add to current buf's count

##### Description

Adds to the channel buffer's consumed sub-buffer count. subbufs_consumed should be the number of sub-buffers newly consumed, not the total consumed.

NOTE. Kernel clients don't need to call this function if the channel mode is 'overwrite'.

#### LINUX

Kernel Hackers Manual January 2008
relay_close
9
2.6.24-rc6-git8

#### relay_close

close the channel

##### Synopsis

       void relay_close
       struct rchan * chan

##### Arguments

`chan`

  the channel

##### Description

Closes all channel buffers and frees the channel.

#### LINUX

Kernel Hackers Manual January 2008
relay_flush
9
2.6.24-rc6-git8

#### relay_flush

close the channel

##### Synopsis

       void relay_flush
       struct rchan * chan

##### Arguments

`chan`

  the channel

##### Description

Flushes all channel buffers, i.e. forces buffer switch.

#### LINUX

Kernel Hackers Manual January 2008
relay_mmap_buf
9
2.6.24-rc6-git8

#### relay_mmap_buf

mmap channel buffer to process address space

##### Synopsis

       int relay_mmap_buf
       struct rchan_buf * buf
       struct vm_area_struct * vma

##### Arguments

`buf`

  relay channel buffer

`vma`

  vm_area_struct describing memory to be mapped

##### Description

Returns 0 if ok, negative on error

Caller should already have grabbed mmap_sem.

#### LINUX

Kernel Hackers Manual January 2008
relay_alloc_buf
9
2.6.24-rc6-git8

#### relay_alloc_buf

allocate a channel buffer

##### Synopsis

       void * relay_alloc_buf
       struct rchan_buf * buf
       size_t * size

##### Arguments

`buf`

  the buffer struct

`size`

  total size of the buffer

##### Description

Returns a pointer to the resulting buffer, `NULL` if unsuccessful. The passed in size will get page aligned, if it isn't already.

#### LINUX

Kernel Hackers Manual January 2008
relay_create_buf
9
2.6.24-rc6-git8

#### relay_create_buf

allocate and initialize a channel buffer

##### Synopsis

       struct rchan_buf * relay_create_buf
       struct rchan * chan

##### Arguments

`chan`

  the relay channel

##### Description

Returns channel buffer if successful, `NULL` otherwise.

#### LINUX

Kernel Hackers Manual January 2008
relay_destroy_channel
9
2.6.24-rc6-git8

#### relay_destroy_channel

free the channel struct

##### Synopsis

       void relay_destroy_channel
       struct kref * kref

##### Arguments

`kref`

  target kernel reference that contains the relay channel

##### Description

Should only be called from `kref_put`.

#### LINUX

Kernel Hackers Manual January 2008
relay_destroy_buf
9
2.6.24-rc6-git8

#### relay_destroy_buf

destroy an rchan_buf struct and associated buffer

##### Synopsis

       void relay_destroy_buf
       struct rchan_buf * buf

##### Arguments

`buf`

  the buffer struct

#### LINUX

Kernel Hackers Manual January 2008
relay_remove_buf
9
2.6.24-rc6-git8

#### relay_remove_buf

remove a channel buffer

##### Synopsis

       void relay_remove_buf
       struct kref * kref

##### Arguments

`kref`

  target kernel reference that contains the relay buffer

##### Description

Removes the file from the fileystem, which also frees the rchan_buf_struct and the channel buffer. Should only be called from `kref_put`.

#### LINUX

Kernel Hackers Manual January 2008
relay_buf_empty
9
2.6.24-rc6-git8

#### relay_buf_empty

boolean, is the channel buffer empty?

##### Synopsis

       int relay_buf_empty
       struct rchan_buf * buf

##### Arguments

`buf`

  channel buffer

##### Description

Returns 1 if the buffer is empty, 0 otherwise.

#### LINUX

Kernel Hackers Manual January 2008
wakeup_readers
9
2.6.24-rc6-git8

#### wakeup_readers

wake up readers waiting on a channel

##### Synopsis

       void wakeup_readers
       unsigned long data

##### Arguments

`data`

  contains the channel buffer

##### Description

This is the timer function used to defer reader waking.

#### LINUX

Kernel Hackers Manual January 2008
__relay_reset
9
2.6.24-rc6-git8

#### __relay_reset

reset a channel buffer

##### Synopsis

       void __relay_reset
       struct rchan_buf * buf
       unsigned int init

##### Arguments

`buf`

  the channel buffer

`init`

  1 if this is a first-time initialization

##### Description

See `relay_reset` for description of effect.

#### LINUX

Kernel Hackers Manual January 2008
relay_close_buf
9
2.6.24-rc6-git8

#### relay_close_buf

close a channel buffer

##### Synopsis

       void relay_close_buf
       struct rchan_buf * buf

##### Arguments

`buf`

  channel buffer

##### Description

Marks the buffer finalized and restores the default callbacks. The channel buffer and channel buffer data structure are then freed automatically when the last reference is given up.

#### LINUX

Kernel Hackers Manual January 2008
relay_hotcpu_callback
9
2.6.24-rc6-git8

#### relay_hotcpu_callback

CPU hotplug callback

##### Synopsis

       int __cpuinit relay_hotcpu_callback
       struct notifier_block * nb
       unsigned long action
       void * hcpu

##### Arguments

`nb`

  notifier block

`action`

  hotplug action to take

`hcpu`

  CPU number

##### Description

Returns the success/failure of the operation. (`NOTIFY_OK`, `NOTIFY_BAD`)

#### LINUX

Kernel Hackers Manual January 2008
relay_file_open
9
2.6.24-rc6-git8

#### relay_file_open

open file op for relay files

##### Synopsis

       int relay_file_open
       struct inode * inode
       struct file * filp

##### Arguments

`inode`

  the inode

`filp`

  the file

##### Description

Increments the channel buffer refcount.

#### LINUX

Kernel Hackers Manual January 2008
relay_file_mmap
9
2.6.24-rc6-git8

#### relay_file_mmap

mmap file op for relay files

##### Synopsis

       int relay_file_mmap
       struct file * filp
       struct vm_area_struct * vma

##### Arguments

`filp`

  the file

`vma`

  the vma describing what to map

##### Description

Calls upon `relay_mmap_buf` to map the file into user space.

#### LINUX

Kernel Hackers Manual January 2008
relay_file_poll
9
2.6.24-rc6-git8

#### relay_file_poll

poll file op for relay files

##### Synopsis

       unsigned int relay_file_poll
       struct file * filp
       poll_table * wait

##### Arguments

`filp`

  the file

`wait`

  poll table

##### Description

Poll implemention.

#### LINUX

Kernel Hackers Manual January 2008
relay_file_release
9
2.6.24-rc6-git8

#### relay_file_release

release file op for relay files

##### Synopsis

       int relay_file_release
       struct inode * inode
       struct file * filp

##### Arguments

`inode`

  the inode

`filp`

  the file

##### Description

Decrements the channel refcount, as the filesystem is no longer using it.

#### LINUX

Kernel Hackers Manual January 2008
relay_file_read_subbuf_avail
9
2.6.24-rc6-git8

#### relay_file_read_subbuf_avail

return bytes available in sub-buffer

##### Synopsis

       size_t relay_file_read_subbuf_avail
       size_t read_pos
       struct rchan_buf * buf

##### Arguments

`read_pos`

  file read position

`buf`

  relay channel buffer

#### LINUX

Kernel Hackers Manual January 2008
relay_file_read_start_pos
9
2.6.24-rc6-git8

#### relay_file_read_start_pos

find the first available byte to read

##### Synopsis

       size_t relay_file_read_start_pos
       size_t read_pos
       struct rchan_buf * buf

##### Arguments

`read_pos`

  file read position

`buf`

  relay channel buffer

##### Description

If the `read_pos` is in the middle of padding, return the position of the first actually available byte, otherwise return the original value.

#### LINUX

Kernel Hackers Manual January 2008
relay_file_read_end_pos
9
2.6.24-rc6-git8

#### relay_file_read_end_pos

return the new read position

##### Synopsis

       size_t relay_file_read_end_pos
       struct rchan_buf * buf
       size_t read_pos
       size_t count

##### Arguments

`buf`

  relay channel buffer

`read_pos`

  file read position

`count`

  number of bytes to be read

## Linux Networking

### Networking Base Types

#### LINUX

Kernel Hackers Manual January 2008
enum sock_type
9
2.6.24-rc6-git8

#### enum sock_type

Socket types

##### Synopsis

    enum sock_type {
      SOCK_STREAM,
      SOCK_DGRAM,
      SOCK_RAW,
      SOCK_RDM,
      SOCK_SEQPACKET,
      SOCK_DCCP,
      SOCK_PACKET
    };

##### Constants

SOCK_STREAM

  stream (connection) socket

SOCK_DGRAM

  datagram (conn.less) socket

SOCK_RAW

  raw socket

SOCK_RDM

  reliably-delivered message

SOCK_SEQPACKET

  sequential packet socket

SOCK_DCCP

  Datagram Congestion Control Protocol socket

SOCK_PACKET

  linux specific way of getting packets at the dev level. For writing rarp and other similar things on the user level.

##### Description

When adding some new socket type please grep ARCH_HAS_SOCKET_TYPE include/asm-* /socket.h, at least MIPS overrides this enum for binary compat reasons.

#### LINUX

Kernel Hackers Manual January 2008
struct socket
9
2.6.24-rc6-git8

#### struct socket

general BSD socket

##### Synopsis

    struct socket {
      socket_state state;
      unsigned long flags;
      const struct proto_ops * ops;
      struct fasync_struct * fasync_list;
      struct file * file;
      struct sock * sk;
      wait_queue_head_t wait;
      short type;
    };

##### Members

state

  socket state (`SS_CONNECTED`, etc)

flags

  socket flags (`SOCK_ASYNC_NOSPACE`, etc)

ops

  protocol specific socket operations

fasync_list

  Asynchronous wake up list

file

  File back pointer for gc

sk

  internal networking protocol agnostic socket representation

wait

  wait queue for several uses

type

  socket type (`SOCK_STREAM`, etc)

### Socket Buffer Functions

#### LINUX

Kernel Hackers Manual January 2008
struct sk_buff
9
2.6.24-rc6-git8

#### struct sk_buff

socket buffer

##### Synopsis

    struct sk_buff {
      struct sk_buff * next;
      struct sk_buff * prev;
      struct sock * sk;
      ktime_t tstamp;
      struct net_device * dev;
      struct dst_entry * dst;
      struct sec_path * sp;
      char cb[48];
      unsigned int len;
      unsigned int data_len;
      __u16 mac_len;
      __u16 hdr_len;
      union {unnamed_union};
      __u32 priority;
      __u8 local_df:1;
      __u8 cloned:1;
      __u8 ip_summed:2;
      __u8 nohdr:1;
      __u8 nfctinfo:3;
      __u8 pkt_type:3;
      __u8 fclone:2;
      __u8 ipvs_property:1;
      __u8 nf_trace:1;
      __be16 protocol;
      void (* destructor) (struct sk_buff *skb);
    #if defined(CONFIG_NF_CONNTRACK) || defined(CONFIG_NF_CONNTRACK_MODULE)
      struct nf_conntrack * nfct;
      struct sk_buff * nfct_reasm;
    #endif
    #ifdef CONFIG_BRIDGE_NETFILTER
      struct nf_bridge_info * nf_bridge;
    #endif
      int iif;
    #ifdef CONFIG_NETDEVICES_MULTIQUEUE
      __u16 queue_mapping;
    #endif
    #ifdef CONFIG_NET_SCHED
      __u16 tc_index;
    #ifdef CONFIG_NET_CLS_ACT
      __u16 tc_verd;
    #endif
    #endif
    #ifdef CONFIG_NET_DMA
      dma_cookie_t dma_cookie;
    #endif
    #ifdef CONFIG_NETWORK_SECMARK
      __u32 secmark;
    #endif
      __u32 mark;
      sk_buff_data_t transport_header;
      sk_buff_data_t network_header;
      sk_buff_data_t mac_header;
      sk_buff_data_t tail;
      sk_buff_data_t end;
      unsigned char * head;
      unsigned char * data;
      unsigned int truesize;
      atomic_t users;
    };

##### Members

next

  Next buffer in list

prev

  Previous buffer in list

sk

  Socket we are owned by

tstamp

  Time we arrived

dev

  Device we arrived on/are leaving by

dst

  destination entry

sp

  the security path, used for xfrm

cb[48]

  Control buffer. Free for use by every layer. Put private vars here

len

  Length of actual data

data_len

  Data length

mac_len

  Length of link layer header

hdr_len

  writable header length of cloned skb

{unnamed_union}

  anonymous

priority

  Packet queueing priority

local_df

  allow local fragmentation

cloned

  Head may be cloned (check refcnt to be sure)

ip_summed

  Driver fed us an IP checksum

nohdr

  Payload reference only, must not modify header

nfctinfo

  Relationship of this skb to the connection

pkt_type

  Packet class

fclone

  skbuff clone status

ipvs_property

  skbuff is owned by ipvs

nf_trace

  netfilter packet trace flag

protocol

  Packet protocol from driver

destructor

  Destruct function

nfct

  Associated connection, if any

nfct_reasm

  netfilter conntrack re-assembly pointer

nf_bridge

  Saved data about a bridged frame - see br_netfilter.c

iif

  ifindex of device we arrived on

queue_mapping

  Queue mapping for multiqueue devices

tc_index

  Traffic control index

tc_verd

  traffic control verdict

dma_cookie

  a cookie to one of several possible DMA operations done by skb DMA functions

secmark

  security marking

mark

  Generic packet mark

transport_header

  Transport layer header

network_header

  Network layer header

mac_header

  Link layer header

tail

  Tail pointer

end

  End pointer

head

  Head of buffer

data

  Data head pointer

truesize

  Buffer size

users

  User count - see {datagram,tcp}.c

#### LINUX

Kernel Hackers Manual January 2008
skb_queue_empty
9
2.6.24-rc6-git8

#### skb_queue_empty

check if a queue is empty

##### Synopsis

       int skb_queue_empty
       const struct sk_buff_head * list

##### Arguments

`list`

  queue head

##### Description

Returns true if the queue is empty, false otherwise.

#### LINUX

Kernel Hackers Manual January 2008
skb_get
9
2.6.24-rc6-git8

#### skb_get

reference buffer

##### Synopsis

       struct sk_buff * skb_get
       struct sk_buff * skb

##### Arguments

`skb`

  buffer to reference

##### Description

Makes another reference to a socket buffer and returns a pointer to the buffer.

#### LINUX

Kernel Hackers Manual January 2008
skb_cloned
9
2.6.24-rc6-git8

#### skb_cloned

is the buffer a clone

##### Synopsis

       int skb_cloned
       const struct sk_buff * skb

##### Arguments

`skb`

  buffer to check

##### Description

Returns true if the buffer was generated with `skb_clone` and is one of multiple shared copies of the buffer. Cloned buffers are shared data so must not be written to under normal circumstances.

#### LINUX

Kernel Hackers Manual January 2008
skb_header_cloned
9
2.6.24-rc6-git8

#### skb_header_cloned

is the header a clone

##### Synopsis

       int skb_header_cloned
       const struct sk_buff * skb

##### Arguments

`skb`

  buffer to check

##### Description

Returns true if modifying the header part of the buffer requires the data to be copied.

#### LINUX

Kernel Hackers Manual January 2008
skb_header_release
9
2.6.24-rc6-git8

#### skb_header_release

release reference to header

##### Synopsis

       void skb_header_release
       struct sk_buff * skb

##### Arguments

`skb`

  buffer to operate on

##### Description

Drop a reference to the header part of the buffer. This is done by acquiring a payload reference. You must not read from the header part of skb->data after this.

#### LINUX

Kernel Hackers Manual January 2008
skb_shared
9
2.6.24-rc6-git8

#### skb_shared

is the buffer shared

##### Synopsis

       int skb_shared
       const struct sk_buff * skb

##### Arguments

`skb`

  buffer to check

##### Description

Returns true if more than one person has a reference to this buffer.

#### LINUX

Kernel Hackers Manual January 2008
skb_share_check
9
2.6.24-rc6-git8

#### skb_share_check

check if buffer is shared and if so clone it

##### Synopsis

       struct sk_buff * skb_share_check
       struct sk_buff * skb
       gfp_t pri

##### Arguments

`skb`

  buffer to check

`pri`

  priority for memory allocation

##### Description

If the buffer is shared the buffer is cloned and the old copy drops a reference. A new clone with a single reference is returned. If the buffer is not shared the original buffer is returned. When being called from interrupt status or with spinlocks held pri must be GFP_ATOMIC.

NULL is returned on a memory allocation failure.

#### LINUX

Kernel Hackers Manual January 2008
skb_unshare
9
2.6.24-rc6-git8

#### skb_unshare

make a copy of a shared buffer

##### Synopsis

       struct sk_buff * skb_unshare
       struct sk_buff * skb
       gfp_t pri

##### Arguments

`skb`

  buffer to check

`pri`

  priority for memory allocation

##### Description

If the socket buffer is a clone then this function creates a new copy of the data, drops a reference count on the old copy and returns the new copy with the reference count at 1. If the buffer is not a clone the original buffer is returned. When called with a spinlock held or from interrupt state `pri` must be `GFP_ATOMIC`

`NULL` is returned on a memory allocation failure.

#### LINUX

Kernel Hackers Manual January 2008
skb_peek
9
2.6.24-rc6-git8

#### skb_peek

##### Synopsis

       struct sk_buff * skb_peek
       struct sk_buff_head * list_

##### Arguments

`list_`

  list to peek at

##### Description

Peek an &sk_buff. Unlike most other operations you _MUST_ be careful with this one. A peek leaves the buffer on the list and someone else may run off with it. You must hold the appropriate locks or have a private queue to do this.

Returns `NULL` for an empty list or a pointer to the head element. The reference count is not incremented and the reference is therefore volatile. Use with caution.

#### LINUX

Kernel Hackers Manual January 2008
skb_peek_tail
9
2.6.24-rc6-git8

#### skb_peek_tail

##### Synopsis

       struct sk_buff * skb_peek_tail
       struct sk_buff_head * list_

##### Arguments

`list_`

  list to peek at

##### Description

Peek an &sk_buff. Unlike most other operations you _MUST_ be careful with this one. A peek leaves the buffer on the list and someone else may run off with it. You must hold the appropriate locks or have a private queue to do this.

Returns `NULL` for an empty list or a pointer to the tail element. The reference count is not incremented and the reference is therefore volatile. Use with caution.

#### LINUX

Kernel Hackers Manual January 2008
skb_queue_len
9
2.6.24-rc6-git8

#### skb_queue_len

get queue length

##### Synopsis

       __u32 skb_queue_len
       const struct sk_buff_head * list_

##### Arguments

`list_`

  list to measure

##### Description

Return the length of an &sk_buff queue.

#### LINUX

Kernel Hackers Manual January 2008
__skb_queue_after
9
2.6.24-rc6-git8

#### __skb_queue_after

queue a buffer at the list head

##### Synopsis

       void __skb_queue_after
       struct sk_buff_head * list
       struct sk_buff * prev
       struct sk_buff * newsk

##### Arguments

`list`

  list to use

`prev`

  place after this buffer

`newsk`

  buffer to queue

##### Description

Queue a buffer int the middle of a list. This function takes no locks and you must therefore hold required locks before calling it.

A buffer cannot be placed on two lists at the same time.

#### LINUX

Kernel Hackers Manual January 2008
skb_put
9
2.6.24-rc6-git8

#### skb_put

add data to a buffer

##### Synopsis

       unsigned char * skb_put
       struct sk_buff * skb
       unsigned int len

##### Arguments

`skb`

  buffer to use

`len`

  amount of data to add

##### Description

This function extends the used data area of the buffer. If this would exceed the total buffer size the kernel will panic. A pointer to the first byte of the extra data is returned.

#### LINUX

Kernel Hackers Manual January 2008
skb_push
9
2.6.24-rc6-git8

#### skb_push

add data to the start of a buffer

##### Synopsis

       unsigned char * skb_push
       struct sk_buff * skb
       unsigned int len

##### Arguments

`skb`

  buffer to use

`len`

  amount of data to add

##### Description

This function extends the used data area of the buffer at the buffer start. If this would exceed the total buffer headroom the kernel will panic. A pointer to the first byte of the extra data is returned.

#### LINUX

Kernel Hackers Manual January 2008
skb_pull
9
2.6.24-rc6-git8

#### skb_pull

remove data from the start of a buffer

##### Synopsis

       unsigned char * skb_pull
       struct sk_buff * skb
       unsigned int len

##### Arguments

`skb`

  buffer to use

`len`

  amount of data to remove

##### Description

This function removes data from the start of a buffer, returning the memory to the headroom. A pointer to the next data in the buffer is returned. Once the data has been pulled future pushes will overwrite the old data.

#### LINUX

Kernel Hackers Manual January 2008
skb_headroom
9
2.6.24-rc6-git8

#### skb_headroom

bytes at buffer head

##### Synopsis

       unsigned int skb_headroom
       const struct sk_buff * skb

##### Arguments

`skb`

  buffer to check

##### Description

Return the number of bytes of free space at the head of an &sk_buff.

#### LINUX

Kernel Hackers Manual January 2008
skb_tailroom
9
2.6.24-rc6-git8

#### skb_tailroom

bytes at buffer end

##### Synopsis

       int skb_tailroom
       const struct sk_buff * skb

##### Arguments

`skb`

  buffer to check

##### Description

Return the number of bytes of free space at the tail of an sk_buff

#### LINUX

Kernel Hackers Manual January 2008
skb_reserve
9
2.6.24-rc6-git8

#### skb_reserve

adjust headroom

##### Synopsis

       void skb_reserve
       struct sk_buff * skb
       int len

##### Arguments

`skb`

  buffer to alter

`len`

  bytes to move

##### Description

Increase the headroom of an empty &sk_buff by reducing the tail room. This is only allowed for an empty buffer.

#### LINUX

Kernel Hackers Manual January 2008
skb_trim
9
2.6.24-rc6-git8

#### skb_trim

remove end from a buffer

##### Synopsis

       void skb_trim
       struct sk_buff * skb
       unsigned int len

##### Arguments

`skb`

  buffer to alter

`len`

  new length

##### Description

Cut the length of a buffer down by removing data from the tail. If the buffer is already under the length specified it is not modified. The skb must be linear.

#### LINUX

Kernel Hackers Manual January 2008
pskb_trim_unique
9
2.6.24-rc6-git8

#### pskb_trim_unique

remove end from a paged unique (not cloned) buffer

##### Synopsis

       void pskb_trim_unique
       struct sk_buff * skb
       unsigned int len

##### Arguments

`skb`

  buffer to alter

`len`

  new length

##### Description

This is identical to pskb_trim except that the caller knows that the skb is not cloned so we should never get an error due to out- of-memory.

#### LINUX

Kernel Hackers Manual January 2008
skb_orphan
9
2.6.24-rc6-git8

#### skb_orphan

orphan a buffer

##### Synopsis

       void skb_orphan
       struct sk_buff * skb

##### Arguments

`skb`

  buffer to orphan

##### Description

If a buffer currently has an owner then we call the owner's destructor function and make the `skb` unowned. The buffer continues to exist but is no longer charged to its former owner.

#### LINUX

Kernel Hackers Manual January 2008
__dev_alloc_skb
9
2.6.24-rc6-git8

#### __dev_alloc_skb

allocate an skbuff for receiving

##### Synopsis

       struct sk_buff * __dev_alloc_skb
       unsigned int length
       gfp_t gfp_mask

##### Arguments

`length`

  length to allocate

`gfp_mask`

  get_free_pages mask, passed to alloc_skb

##### Description

Allocate a new &sk_buff and assign it a usage count of one. The buffer has unspecified headroom built in. Users should allocate the headroom they think they need without accounting for the built in space. The built in space is used for optimisations.

`NULL` is returned if there is no free memory.

#### LINUX

Kernel Hackers Manual January 2008
dev_alloc_skb
9
2.6.24-rc6-git8

#### dev_alloc_skb

allocate an skbuff for receiving

##### Synopsis

       struct sk_buff * dev_alloc_skb
       unsigned int length

##### Arguments

`length`

  length to allocate

##### Description

Allocate a new &sk_buff and assign it a usage count of one. The buffer has unspecified headroom built in. Users should allocate the headroom they think they need without accounting for the built in space. The built in space is used for optimisations.

`NULL` is returned if there is no free memory. Although this function allocates memory it can be called from an interrupt.

#### LINUX

Kernel Hackers Manual January 2008
netdev_alloc_skb
9
2.6.24-rc6-git8

#### netdev_alloc_skb

allocate an skbuff for rx on a specific device

##### Synopsis

       struct sk_buff * netdev_alloc_skb
       struct net_device * dev
       unsigned int length

##### Arguments

`dev`

  network device to receive on

`length`

  length to allocate

##### Description

Allocate a new &sk_buff and assign it a usage count of one. The buffer has unspecified headroom built in. Users should allocate the headroom they think they need without accounting for the built in space. The built in space is used for optimisations.

`NULL` is returned if there is no free memory. Although this function allocates memory it can be called from an interrupt.

#### LINUX

Kernel Hackers Manual January 2008
skb_clone_writable
9
2.6.24-rc6-git8

#### skb_clone_writable

is the header of a clone writable

##### Synopsis

       int skb_clone_writable
       struct sk_buff * skb
       unsigned int len

##### Arguments

`skb`

  buffer to check

`len`

  length up to which to write

##### Description

Returns true if modifying the header part of the cloned buffer does not requires the data to be copied.

#### LINUX

Kernel Hackers Manual January 2008
skb_cow
9
2.6.24-rc6-git8

#### skb_cow

copy header of skb when it is required

##### Synopsis

       int skb_cow
       struct sk_buff * skb
       unsigned int headroom

##### Arguments

`skb`

  buffer to cow

`headroom`

  needed headroom

##### Description

If the skb passed lacks sufficient headroom or its data part is shared, data is reallocated. If reallocation fails, an error is returned and original skb is not changed.

The result is skb with writable area skb->head...skb->tail and at least `headroom` of space at head.

#### LINUX

Kernel Hackers Manual January 2008
skb_cow_head
9
2.6.24-rc6-git8

#### skb_cow_head

skb_cow but only making the head writable

##### Synopsis

       int skb_cow_head
       struct sk_buff * skb
       unsigned int headroom

##### Arguments

`skb`

  buffer to cow

`headroom`

  needed headroom

##### Description

This function is identical to skb_cow except that we replace the skb_cloned check by skb_header_cloned. It should be used when you only need to push on some header and do not need to modify the data.

#### LINUX

Kernel Hackers Manual January 2008
skb_padto
9
2.6.24-rc6-git8

#### skb_padto

pad an skbuff up to a minimal size

##### Synopsis

       int skb_padto
       struct sk_buff * skb
       unsigned int len

##### Arguments

`skb`

  buffer to pad

`len`

  minimal length

##### Description

Pads up a buffer to ensure the trailing bytes exist and are blanked. If the buffer already contains sufficient data it is untouched. Otherwise it is extended. Returns zero on success. The skb is freed on error.

#### LINUX

Kernel Hackers Manual January 2008
skb_linearize
9
2.6.24-rc6-git8

#### skb_linearize

convert paged skb to linear one

##### Synopsis

       int skb_linearize
       struct sk_buff * skb

##### Arguments

`skb`

  buffer to linarize

##### Description

If there is no free memory -ENOMEM is returned, otherwise zero is returned and the old skb data released.

#### LINUX

Kernel Hackers Manual January 2008
skb_linearize_cow
9
2.6.24-rc6-git8

#### skb_linearize_cow

make sure skb is linear and writable

##### Synopsis

       int skb_linearize_cow
       struct sk_buff * skb

##### Arguments

`skb`

  buffer to process

##### Description

If there is no free memory -ENOMEM is returned, otherwise zero is returned and the old skb data released.

#### LINUX

Kernel Hackers Manual January 2008
skb_postpull_rcsum
9
2.6.24-rc6-git8

#### skb_postpull_rcsum

update checksum for received skb after pull

##### Synopsis

       void skb_postpull_rcsum
       struct sk_buff * skb
       const void * start
       unsigned int len

##### Arguments

`skb`

  buffer to update

`start`

  start of data before pull

`len`

  length of data pulled

##### Description

After doing a pull on a received packet, you need to call this to update the CHECKSUM_COMPLETE checksum, or set ip_summed to CHECKSUM_NONE so that it can be recomputed from scratch.

#### LINUX

Kernel Hackers Manual January 2008
pskb_trim_rcsum
9
2.6.24-rc6-git8

#### pskb_trim_rcsum

trim received skb and update checksum

##### Synopsis

       int pskb_trim_rcsum
       struct sk_buff * skb
       unsigned int len

##### Arguments

`skb`

  buffer to trim

`len`

  new length

##### Description

This is exactly the same as pskb_trim except that it ensures the checksum of received packets are still valid after the operation.

#### LINUX

Kernel Hackers Manual January 2008
skb_get_timestamp
9
2.6.24-rc6-git8

#### skb_get_timestamp

get timestamp from a skb

##### Synopsis

       void skb_get_timestamp
       const struct sk_buff * skb
       struct timeval * stamp

##### Arguments

`skb`

  skb to get stamp from

`stamp`

  pointer to struct timeval to store stamp in

##### Description

Timestamps are stored in the skb as offsets to a base timestamp. This function converts the offset back to a struct timeval and stores it in stamp.

#### LINUX

Kernel Hackers Manual January 2008
skb_checksum_complete
9
2.6.24-rc6-git8

#### skb_checksum_complete

Calculate checksum of an entire packet

##### Synopsis

       __sum16 skb_checksum_complete
       struct sk_buff * skb

##### Arguments

`skb`

  packet to process

##### Description

This function calculates the checksum over the entire packet plus the value of skb->csum. The latter can be used to supply the checksum of a pseudo header as used by TCP/UDP. It returns the checksum.

For protocols that contain complete checksums such as ICMP/TCP/UDP, this function can be used to verify that checksum on received packets. In that case the function should return zero if the checksum is correct. In particular, this function will return zero if skb->ip_summed is CHECKSUM_UNNECESSARY which indicates that the hardware has already verified the correctness of the checksum.

#### LINUX

Kernel Hackers Manual January 2008
struct sock_common
9
2.6.24-rc6-git8

#### struct sock_common

minimal network layer representation of sockets

##### Synopsis

    struct sock_common {
      unsigned short skc_family;
      volatile unsigned char skc_state;
      unsigned char skc_reuse;
      int skc_bound_dev_if;
      struct hlist_node skc_node;
      struct hlist_node skc_bind_node;
      atomic_t skc_refcnt;
      unsigned int skc_hash;
      struct proto * skc_prot;
      struct net * skc_net;
    };

##### Members

skc_family

  network address family

skc_state

  Connection state

skc_reuse

  `SO_REUSEADDR` setting

skc_bound_dev_if

  bound device index if != 0

skc_node

  main hash linkage for various protocol lookup tables

skc_bind_node

  bind hash linkage for various protocol lookup tables

skc_refcnt

  reference count

skc_hash

  hash value used with various protocol lookup tables

skc_prot

  protocol handlers inside a network family

skc_net

  reference to the network namespace of this socket

##### Description

This is the minimal network layer representation of sockets, the header for struct sock and struct inet_timewait_sock.

#### LINUX

Kernel Hackers Manual January 2008
struct sock
9
2.6.24-rc6-git8

#### struct sock

network layer representation of sockets

##### Synopsis

    struct sock {
      struct sock_common __sk_common;
    #define sk_family		__sk_common.skc_family
    #define sk_state		__sk_common.skc_state
    #define sk_reuse		__sk_common.skc_reuse
    #define sk_bound_dev_if		__sk_common.skc_bound_dev_if
    #define sk_node			__sk_common.skc_node
    #define sk_bind_node		__sk_common.skc_bind_node
    #define sk_refcnt		__sk_common.skc_refcnt
    #define sk_hash			__sk_common.skc_hash
    #define sk_prot			__sk_common.skc_prot
    #define sk_net			__sk_common.skc_net
      unsigned char sk_shutdown:2;
      unsigned char sk_no_check:2;
      unsigned char sk_userlocks:4;
      unsigned char sk_protocol;
      unsigned short sk_type;
      int sk_rcvbuf;
      socket_lock_t sk_lock;
      struct sk_backlog;
      wait_queue_head_t * sk_sleep;
      struct dst_entry * sk_dst_cache;
      struct xfrm_policy * sk_policy[2];
      rwlock_t sk_dst_lock;
      atomic_t sk_rmem_alloc;
      atomic_t sk_wmem_alloc;
      atomic_t sk_omem_alloc;
      int sk_sndbuf;
      struct sk_buff_head sk_receive_queue;
      struct sk_buff_head sk_write_queue;
      struct sk_buff_head sk_async_wait_queue;
      int sk_wmem_queued;
      int sk_forward_alloc;
      gfp_t sk_allocation;
      int sk_route_caps;
      int sk_gso_type;
      int sk_rcvlowat;
      unsigned long sk_flags;
      unsigned long sk_lingertime;
      struct sk_buff_head sk_error_queue;
      struct proto * sk_prot_creator;
      rwlock_t sk_callback_lock;
      int sk_err;
      int sk_err_soft;
      unsigned short sk_ack_backlog;
      unsigned short sk_max_ack_backlog;
      __u32 sk_priority;
      struct ucred sk_peercred;
      long sk_rcvtimeo;
      long sk_sndtimeo;
      struct sk_filter * sk_filter;
      void * sk_protinfo;
      struct timer_list sk_timer;
      ktime_t sk_stamp;
      struct socket * sk_socket;
      void * sk_user_data;
      struct page * sk_sndmsg_page;
      struct sk_buff * sk_send_head;
      __u32 sk_sndmsg_off;
      int sk_write_pending;
      void * sk_security;
      void (* sk_state_change) (struct sock *sk);
      void (* sk_data_ready) (struct sock *sk, int bytes);
      void (* sk_write_space) (struct sock *sk);
      void (* sk_error_report) (struct sock *sk);
      int (* sk_backlog_rcv) (struct sock *sk,struct sk_buff *skb);
      void (* sk_destruct) (struct sock *sk);
    };

##### Members

__sk_common

  shared layout with inet_timewait_sock

sk_shutdown

  mask of `SEND_SHUTDOWN` and/or `RCV_SHUTDOWN`

sk_no_check

  `SO_NO_CHECK` setting, wether or not checkup packets

sk_userlocks

  `SO_SNDBUF` and `SO_RCVBUF` settings

sk_protocol

  which protocol this socket belongs in this network family

sk_type

  socket type (`SOCK_STREAM`, etc)

sk_rcvbuf

  size of receive buffer in bytes

sk_lock

  synchronizer

sk_backlog

  always used with the per-socket spinlock held

sk_sleep

  sock wait queue

sk_dst_cache

  destination cache

sk_policy[2]

  flow policy

sk_dst_lock

  destination cache lock

sk_rmem_alloc

  receive queue bytes committed

sk_wmem_alloc

  transmit queue bytes committed

sk_omem_alloc

  "o is option or other"

sk_sndbuf

  size of send buffer in bytes

sk_receive_queue

  incoming packets

sk_write_queue

  Packet sending queue

sk_async_wait_queue

  DMA copied packets

sk_wmem_queued

  persistent queue size

sk_forward_alloc

  space allocated forward

sk_allocation

  allocation mode

sk_route_caps

  route capabilities (e.g. `NETIF_F_TSO`)

sk_gso_type

  GSO type (e.g. `SKB_GSO_TCPV4`)

sk_rcvlowat

  `SO_RCVLOWAT` setting

sk_flags

  `SO_LINGER` (l_onoff), `SO_BROADCAST`, `SO_KEEPALIVE`, `SO_OOBINLINE` settings

sk_lingertime

  `SO_LINGER` l_linger setting

sk_error_queue

  rarely used

sk_prot_creator

  sk_prot of original sock creator (see ipv6_setsockopt, IPV6_ADDRFORM for instance)

sk_callback_lock

  used with the callbacks in the end of this struct

sk_err

  last error

sk_err_soft

  errors that don't cause failure but are the cause of a persistent failure not just 'timed out'

sk_ack_backlog

  current listen backlog

sk_max_ack_backlog

  listen backlog set in `listen`

sk_priority

  `SO_PRIORITY` setting

sk_peercred

  `SO_PEERCRED` setting

sk_rcvtimeo

  `SO_RCVTIMEO` setting

sk_sndtimeo

  `SO_SNDTIMEO` setting

sk_filter

  socket filtering instructions

sk_protinfo

  private area, net family specific, when not using slab

sk_timer

  sock cleanup timer

sk_stamp

  time stamp of last packet received

sk_socket

  Identd and reporting IO signals

sk_user_data

  RPC layer private data

sk_sndmsg_page

  cached page for sendmsg

sk_send_head

  front of stuff to transmit

sk_sndmsg_off

  cached offset for sendmsg

sk_write_pending

  a write to stream socket waits to start

sk_security

  used by security modules

sk_state_change

  callback to indicate change in the state of the sock

sk_data_ready

  callback to indicate there is data to be processed

sk_write_space

  callback to indicate there is bf sending space available

sk_error_report

  callback to indicate errors (e.g. `MSG_ERRQUEUE`)

sk_backlog_rcv

  callback to process the backlog

sk_destruct

  called at sock freeing time, i.e. when all refcnt == 0

#### LINUX

Kernel Hackers Manual January 2008
sk_filter
9
2.6.24-rc6-git8

#### sk_filter

run a packet through a socket filter

##### Synopsis

       int sk_filter
       struct sock * sk
       struct sk_buff * skb

##### Arguments

`sk`

  sock associated with &sk_buff

`skb`

  buffer to filter

##### Description

Run the filter code and then cut skb->data to correct size returned by sk_run_filter. If pkt_len is 0 we toss packet. If skb->len is smaller than pkt_len we keep whole skb->data. This is the socket level wrapper to sk_run_filter. It returns 0 if the packet should be accepted or -EPERM if the packet should be tossed.

#### LINUX

Kernel Hackers Manual January 2008
sk_filter_release
9
2.6.24-rc6-git8

#### sk_filter_release

##### Synopsis

       void sk_filter_release
       struct sk_filter * fp

##### Arguments

`fp`

  filter to remove

##### Description

Remove a filter from a socket and release its resources.

#### LINUX

Kernel Hackers Manual January 2008
sk_eat_skb
9
2.6.24-rc6-git8

#### sk_eat_skb

Release a skb if it is no longer needed

##### Synopsis

       void sk_eat_skb
       struct sock * sk
       struct sk_buff * skb
       int copied_early

##### Arguments

`sk`

  socket to eat this skb from

`skb`

  socket buffer to eat

`copied_early`

  flag indicating whether DMA operations copied this data early

##### Description

This routine must be called with interrupts disabled or with the socket locked so that the sk_buff queue operation is ok.

#### LINUX

Kernel Hackers Manual January 2008
move_addr_to_kernel
9
2.6.24-rc6-git8

#### move_addr_to_kernel

copy a socket address into kernel space

##### Synopsis

       int move_addr_to_kernel
       void __user * uaddr
       int ulen
       void * kaddr

##### Arguments

`uaddr`

  Address in user space

`ulen`

  Length in user space

`kaddr`

  Address in kernel space

##### Description

The address is copied into kernel space. If the provided address is too long an error code of -EINVAL is returned. If the copy gives invalid addresses -EFAULT is returned. On a success 0 is returned.

#### LINUX

Kernel Hackers Manual January 2008
move_addr_to_user
9
2.6.24-rc6-git8

#### move_addr_to_user

copy an address to user space

##### Synopsis

       int move_addr_to_user
       void * kaddr
       int klen
       void __user * uaddr
       int __user * ulen

##### Arguments

`kaddr`

  kernel space address

`klen`

  length of address in kernel

`uaddr`

  user space address

`ulen`

  pointer to user length field

##### Description

The value pointed to by ulen on entry is the buffer length available. This is overwritten with the buffer space used. -EINVAL is returned if an overlong buffer is specified or a negative buffer size. -EFAULT is returned if either the buffer or the length field are not accessible. After copying the data up to the limit the user specifies, the true length of the data is written over the length limit the user specified. Zero is returned for a success.

#### LINUX

Kernel Hackers Manual January 2008
sockfd_lookup
9
2.6.24-rc6-git8

#### sockfd_lookup

Go from a file number to its socket slot

##### Synopsis

       struct socket * sockfd_lookup
       int fd
       int * err

##### Arguments

`fd`

  file handle

`err`

  pointer to an error code return

##### Description

The file handle passed in is locked and the socket it is bound too is returned. If an error occurs the err pointer is overwritten with a negative errno code and NULL is returned. The function checks for both invalid handles and passing a handle which is not a socket.

On a success the socket object pointer is returned.

#### LINUX

Kernel Hackers Manual January 2008
sock_release
9
2.6.24-rc6-git8

#### sock_release

close a socket

##### Synopsis

       void sock_release
       struct socket * sock

##### Arguments

`sock`

  socket to close

##### Description

The socket is released from the protocol stack if it has a release callback, and the inode is then released if the socket is bound to an inode not a file.

#### LINUX

Kernel Hackers Manual January 2008
sock_register
9
2.6.24-rc6-git8

#### sock_register

add a socket protocol handler

##### Synopsis

       int sock_register
       const struct net_proto_family * ops

##### Arguments

`ops`

  description of protocol

##### Description

This function is called by a protocol handler that wants to advertise its address family, and have it linked into the socket interface. The value ops->family coresponds to the socket system call protocol family.

#### LINUX

Kernel Hackers Manual January 2008
sock_unregister
9
2.6.24-rc6-git8

#### sock_unregister

remove a protocol handler

##### Synopsis

       void sock_unregister
       int family

##### Arguments

`family`

  protocol family to remove

##### Description

This function is called by a protocol handler that wants to remove its address family, and have it unlinked from the new socket creation.

If protocol handler is a module, then it can use module reference counts to protect against new references. If protocol handler is not a module then it needs to provide its own protection in the ops->create routine.

#### LINUX

Kernel Hackers Manual January 2008
skb_over_panic
9
2.6.24-rc6-git8

#### skb_over_panic

private function

##### Synopsis

       void skb_over_panic
       struct sk_buff * skb
       int sz
       void * here

##### Arguments

`skb`

  buffer

`sz`

  size

`here`

  address

##### Description

Out of line support code for `skb_put`. Not user callable.

#### LINUX

Kernel Hackers Manual January 2008
skb_under_panic
9
2.6.24-rc6-git8

#### skb_under_panic

private function

##### Synopsis

       void skb_under_panic
       struct sk_buff * skb
       int sz
       void * here

##### Arguments

`skb`

  buffer

`sz`

  size

`here`

  address

##### Description

Out of line support code for `skb_push`. Not user callable.

#### LINUX

Kernel Hackers Manual January 2008
__alloc_skb
9
2.6.24-rc6-git8

#### __alloc_skb

allocate a network buffer

##### Synopsis

       struct sk_buff * __alloc_skb
       unsigned int size
       gfp_t gfp_mask
       int fclone
       int node

##### Arguments

`size`

  size to allocate

`gfp_mask`

  allocation mask

`fclone`

  allocate from fclone cache instead of head cache and allocate a cloned (child) skb

`node`

  numa node to allocate memory on

##### Description

Allocate a new &sk_buff. The returned buffer has no headroom and a tail room of size bytes. The object has a reference count of one. The return is the buffer. On a failure the return is `NULL`.

Buffers may only be allocated from interrupts using a `gfp_mask` of `GFP_ATOMIC`.

#### LINUX

Kernel Hackers Manual January 2008
__netdev_alloc_skb
9
2.6.24-rc6-git8

#### __netdev_alloc_skb

allocate an skbuff for rx on a specific device

##### Synopsis

       struct sk_buff * __netdev_alloc_skb
       struct net_device * dev
       unsigned int length
       gfp_t gfp_mask

##### Arguments

`dev`

  network device to receive on

`length`

  length to allocate

`gfp_mask`

  get_free_pages mask, passed to alloc_skb

##### Description

Allocate a new &sk_buff and assign it a usage count of one. The buffer has unspecified headroom built in. Users should allocate the headroom they think they need without accounting for the built in space. The built in space is used for optimisations.

`NULL` is returned if there is no free memory.

#### LINUX

Kernel Hackers Manual January 2008
__kfree_skb
9
2.6.24-rc6-git8

#### __kfree_skb

private function

##### Synopsis

       void __kfree_skb
       struct sk_buff * skb

##### Arguments

`skb`

  buffer

##### Description

Free an sk_buff. Release anything attached to the buffer. Clean the state. This is an internal helper function. Users should always call kfree_skb

#### LINUX

Kernel Hackers Manual January 2008
kfree_skb
9
2.6.24-rc6-git8

#### kfree_skb

free an sk_buff

##### Synopsis

       void kfree_skb
       struct sk_buff * skb

##### Arguments

`skb`

  buffer to free

##### Description

Drop a reference to the buffer and free it if the usage count has hit zero.

#### LINUX

Kernel Hackers Manual January 2008
skb_morph
9
2.6.24-rc6-git8

#### skb_morph

morph one skb into another

##### Synopsis

       struct sk_buff * skb_morph
       struct sk_buff * dst
       struct sk_buff * src

##### Arguments

`dst`

  the skb to receive the contents

`src`

  the skb to supply the contents

##### Description

This is identical to skb_clone except that the target skb is supplied by the user.

The target skb is returned upon exit.

#### LINUX

Kernel Hackers Manual January 2008
skb_clone
9
2.6.24-rc6-git8

#### skb_clone

duplicate an sk_buff

##### Synopsis

       struct sk_buff * skb_clone
       struct sk_buff * skb
       gfp_t gfp_mask

##### Arguments

`skb`

  buffer to clone

`gfp_mask`

  allocation priority

##### Description

Duplicate an &sk_buff. The new one is not owned by a socket. Both copies share the same packet data but not structure. The new buffer has a reference count of 1. If the allocation fails the function returns `NULL` otherwise the new buffer is returned.

If this function is called from an interrupt `gfp_mask` must be `GFP_ATOMIC`.

#### LINUX

Kernel Hackers Manual January 2008
skb_copy
9
2.6.24-rc6-git8

#### skb_copy

create private copy of an sk_buff

##### Synopsis

       struct sk_buff * skb_copy
       const struct sk_buff * skb
       gfp_t gfp_mask

##### Arguments

`skb`

  buffer to copy

`gfp_mask`

  allocation priority

##### Description

Make a copy of both an &sk_buff and its data. This is used when the caller wishes to modify the data and needs a private copy of the data to alter. Returns `NULL` on failure or the pointer to the buffer on success. The returned buffer has a reference count of 1.

As by-product this function converts non-linear &sk_buff to linear one, so that &sk_buff becomes completely private and caller is allowed to modify all the data of returned buffer. This means that this function is not recommended for use in circumstances when only header is going to be modified. Use `pskb_copy` instead.

#### LINUX

Kernel Hackers Manual January 2008
pskb_copy
9
2.6.24-rc6-git8

#### pskb_copy

create copy of an sk_buff with private head.

##### Synopsis

       struct sk_buff * pskb_copy
       struct sk_buff * skb
       gfp_t gfp_mask

##### Arguments

`skb`

  buffer to copy

`gfp_mask`

  allocation priority

##### Description

Make a copy of both an &sk_buff and part of its data, located in header. Fragmented data remain shared. This is used when the caller wishes to modify only header of &sk_buff and needs private copy of the header to alter. Returns `NULL` on failure or the pointer to the buffer on success. The returned buffer has a reference count of 1.

#### LINUX

Kernel Hackers Manual January 2008
pskb_expand_head
9
2.6.24-rc6-git8

#### pskb_expand_head

reallocate header of &sk_buff

##### Synopsis

       int pskb_expand_head
       struct sk_buff * skb
       int nhead
       int ntail
       gfp_t gfp_mask

##### Arguments

`skb`

  buffer to reallocate

`nhead`

  room to add at head

`ntail`

  room to add at tail

`gfp_mask`

  allocation priority

##### Description

Expands (or creates identical copy, if &nhead and &ntail are zero) header of skb. &sk_buff itself is not changed. &sk_buff MUST have reference count of 1. Returns zero in the case of success or error, if expansion failed. In the last case, &sk_buff is not changed.

All the pointers pointing into skb header may change and must be reloaded after call to this function.

#### LINUX

Kernel Hackers Manual January 2008
skb_copy_expand
9
2.6.24-rc6-git8

#### skb_copy_expand

copy and expand sk_buff

##### Synopsis

       struct sk_buff * skb_copy_expand
       const struct sk_buff * skb
       int newheadroom
       int newtailroom
       gfp_t gfp_mask

##### Arguments

`skb`

  buffer to copy

`newheadroom`

  new free bytes at head

`newtailroom`

  new free bytes at tail

`gfp_mask`

  allocation priority

##### Description

Make a copy of both an &sk_buff and its data and while doing so allocate additional space.

This is used when the caller wishes to modify the data and needs a private copy of the data to alter as well as more space for new fields. Returns `NULL` on failure or the pointer to the buffer on success. The returned buffer has a reference count of 1.

You must pass `GFP_ATOMIC` as the allocation priority if this function is called from an interrupt.

#### LINUX

Kernel Hackers Manual January 2008
skb_pad
9
2.6.24-rc6-git8

#### skb_pad

zero pad the tail of an skb

##### Synopsis

       int skb_pad
       struct sk_buff * skb
       int pad

##### Arguments

`skb`

  buffer to pad

`pad`

  space to pad

##### Description

Ensure that a buffer is followed by a padding area that is zero filled. Used by network drivers which may DMA or transfer data beyond the buffer end onto the wire.

May return error in out of memory cases. The skb is freed on error.

#### LINUX

Kernel Hackers Manual January 2008
__pskb_pull_tail
9
2.6.24-rc6-git8

#### __pskb_pull_tail

advance tail of skb header

##### Synopsis

       unsigned char * __pskb_pull_tail
       struct sk_buff * skb
       int delta

##### Arguments

`skb`

  buffer to reallocate

`delta`

  number of bytes to advance tail

##### Description

The function makes a sense only on a fragmented &sk_buff, it expands header moving its tail forward and copying necessary data from fragmented part.

&sk_buff MUST have reference count of 1.

Returns `NULL` (and &sk_buff does not change) if pull failed or value of new tail of skb in the case of success.

All the pointers pointing into skb header may change and must be reloaded after call to this function.

#### LINUX

Kernel Hackers Manual January 2008
skb_store_bits
9
2.6.24-rc6-git8

#### skb_store_bits

store bits from kernel buffer to skb

##### Synopsis

       int skb_store_bits
       struct sk_buff * skb
       int offset
       const void * from
       int len

##### Arguments

`skb`

  destination buffer

`offset`

  offset in destination

`from`

  source buffer

`len`

  number of bytes to copy

##### Description

Copy the specified number of bytes from the source buffer to the destination skb. This function handles all the messy bits of traversing fragment lists and such.

#### LINUX

Kernel Hackers Manual January 2008
skb_dequeue
9
2.6.24-rc6-git8

#### skb_dequeue

remove from the head of the queue

##### Synopsis

       struct sk_buff * skb_dequeue
       struct sk_buff_head * list

##### Arguments

`list`

  list to dequeue from

##### Description

Remove the head of the list. The list lock is taken so the function may be used safely with other locking list functions. The head item is returned or `NULL` if the list is empty.

#### LINUX

Kernel Hackers Manual January 2008
skb_dequeue_tail
9
2.6.24-rc6-git8

#### skb_dequeue_tail

remove from the tail of the queue

##### Synopsis

       struct sk_buff * skb_dequeue_tail
       struct sk_buff_head * list

##### Arguments

`list`

  list to dequeue from

##### Description

Remove the tail of the list. The list lock is taken so the function may be used safely with other locking list functions. The tail item is returned or `NULL` if the list is empty.

#### LINUX

Kernel Hackers Manual January 2008
skb_queue_purge
9
2.6.24-rc6-git8

#### skb_queue_purge

empty a list

##### Synopsis

       void skb_queue_purge
       struct sk_buff_head * list

##### Arguments

`list`

  list to empty

##### Description

Delete all buffers on an &sk_buff list. Each buffer is removed from the list and one reference dropped. This function takes the list lock and is atomic with respect to other list locking functions.

#### LINUX

Kernel Hackers Manual January 2008
skb_queue_head
9
2.6.24-rc6-git8

#### skb_queue_head

queue a buffer at the list head

##### Synopsis

       void skb_queue_head
       struct sk_buff_head * list
       struct sk_buff * newsk

##### Arguments

`list`

  list to use

`newsk`

  buffer to queue

##### Description

Queue a buffer at the start of the list. This function takes the list lock and can be used safely with other locking &sk_buff functions safely.

A buffer cannot be placed on two lists at the same time.

#### LINUX

Kernel Hackers Manual January 2008
skb_queue_tail
9
2.6.24-rc6-git8

#### skb_queue_tail

queue a buffer at the list tail

##### Synopsis

       void skb_queue_tail
       struct sk_buff_head * list
       struct sk_buff * newsk

##### Arguments

`list`

  list to use

`newsk`

  buffer to queue

##### Description

Queue a buffer at the tail of the list. This function takes the list lock and can be used safely with other locking &sk_buff functions safely.

A buffer cannot be placed on two lists at the same time.

#### LINUX

Kernel Hackers Manual January 2008
skb_unlink
9
2.6.24-rc6-git8

#### skb_unlink

remove a buffer from a list

##### Synopsis

       void skb_unlink
       struct sk_buff * skb
       struct sk_buff_head * list

##### Arguments

`skb`

  buffer to remove

`list`

  list to use

##### Description

Remove a packet from a list. The list locks are taken and this function is atomic with respect to other list locked calls

You must know what list the SKB is on.

#### LINUX

Kernel Hackers Manual January 2008
skb_append
9
2.6.24-rc6-git8

#### skb_append

append a buffer

##### Synopsis

       void skb_append
       struct sk_buff * old
       struct sk_buff * newsk
       struct sk_buff_head * list

##### Arguments

`old`

  buffer to insert after

`newsk`

  buffer to insert

`list`

  list to use

##### Description

Place a packet after a given packet in a list. The list locks are taken and this function is atomic with respect to other list locked calls. A buffer cannot be placed on two lists at the same time.

#### LINUX

Kernel Hackers Manual January 2008
skb_insert
9
2.6.24-rc6-git8

#### skb_insert

insert a buffer

##### Synopsis

       void skb_insert
       struct sk_buff * old
       struct sk_buff * newsk
       struct sk_buff_head * list

##### Arguments

`old`

  buffer to insert before

`newsk`

  buffer to insert

`list`

  list to use

##### Description

Place a packet before a given packet in a list. The list locks are taken and this function is atomic with respect to other list locked calls.

A buffer cannot be placed on two lists at the same time.

#### LINUX

Kernel Hackers Manual January 2008
skb_split
9
2.6.24-rc6-git8

#### skb_split

Split fragmented skb to two parts at length len.

##### Synopsis

       void skb_split
       struct sk_buff * skb
       struct sk_buff * skb1
       const u32 len

##### Arguments

`skb`

  the buffer to split

`skb1`

  the buffer to receive the second part

`len`

  new length for skb

#### LINUX

Kernel Hackers Manual January 2008
skb_prepare_seq_read
9
2.6.24-rc6-git8

#### skb_prepare_seq_read

Prepare a sequential read of skb data

##### Synopsis

       void skb_prepare_seq_read
       struct sk_buff * skb
       unsigned int from
       unsigned int to
       struct skb_seq_state * st

##### Arguments

`skb`

  the buffer to read

`from`

  lower offset of data to be read

`to`

  upper offset of data to be read

`st`

  state variable

##### Description

Initializes the specified state variable. Must be called before invoking `skb_seq_read` for the first time.

#### LINUX

Kernel Hackers Manual January 2008
skb_seq_read
9
2.6.24-rc6-git8

#### skb_seq_read

Sequentially read skb data

##### Synopsis

       unsigned int skb_seq_read
       unsigned int consumed
       const u8 ** data
       struct skb_seq_state * st

##### Arguments

`consumed`

  number of bytes consumed by the caller so far

`data`

  destination pointer for data to be returned

`st`

  state variable

##### Description

Reads a block of skb data at &consumed relative to the lower offset specified to `skb_prepare_seq_read`. Assigns the head of the data block to &data and returns the length of the block or 0 if the end of the skb data or the upper offset has been reached.

The caller is not required to consume all of the data returned, i.e. &consumed is typically set to the number of bytes already consumed and the next call to `skb_seq_read` will return the remaining part of the block.

##### Note

Fragment lists within fragments are not implemented at the moment, state->root_skb could be replaced with a stack for this purpose.

##### Note

Fragment lists within fragments are not implemented at the moment, state->root_skb could be replaced with a stack for this purpose.

#### LINUX

Kernel Hackers Manual January 2008
skb_abort_seq_read
9
2.6.24-rc6-git8

#### skb_abort_seq_read

Abort a sequential read of skb data

##### Synopsis

       void skb_abort_seq_read
       struct skb_seq_state * st

##### Arguments

`st`

  state variable

##### Description

Must be called if `skb_seq_read` was not called until it returned 0.

#### LINUX

Kernel Hackers Manual January 2008
skb_find_text
9
2.6.24-rc6-git8

#### skb_find_text

Find a text pattern in skb data

##### Synopsis

       unsigned int skb_find_text
       struct sk_buff * skb
       unsigned int from
       unsigned int to
       struct ts_config * config
       struct ts_state * state

##### Arguments

`skb`

  the buffer to look in

`from`

  search offset

`to`

  search limit

`config`

  textsearch configuration

`state`

  uninitialized textsearch state variable

##### Description

Finds a pattern in the skb data according to the specified textsearch configuration. Use `textsearch_next` to retrieve subsequent occurrences of the pattern. Returns the offset to the first occurrence or UINT_MAX if no match was found.

#### LINUX

Kernel Hackers Manual January 2008
skb_append_datato_frags
9
2.6.24-rc6-git8

#### skb_append_datato_frags

append the user data to a skb

##### Synopsis

       int skb_append_datato_frags
       struct sock * sk
       struct sk_buff * skb
       int (*getfrag)
         void *from, char *to, int offset, 					int len, int odd, struct sk_buff *skb
       void * from
       int length

##### Arguments

`sk`

  sock structure

`skb`

  skb structure to be appened with user data.

`getfrag`

  call back function to be used for getting the user data

`from`

  pointer to user message iov

`length`

  length of the iov message

##### Description

This procedure append the user data in the fragment part of the skb if any page alloc fails user this procedure returns -ENOMEM

#### LINUX

Kernel Hackers Manual January 2008
skb_pull_rcsum
9
2.6.24-rc6-git8

#### skb_pull_rcsum

pull skb and update receive checksum

##### Synopsis

       unsigned char * skb_pull_rcsum
       struct sk_buff * skb
       unsigned int len

##### Arguments

`skb`

  buffer to update

`len`

  length of data pulled

##### Description

This function performs an skb_pull on the packet and updates update the CHECKSUM_COMPLETE checksum. It should be used on receive path processing instead of skb_pull unless you know that the checksum difference is zero (e.g., a valid IP header) or you are setting ip_summed to CHECKSUM_NONE.

#### LINUX

Kernel Hackers Manual January 2008
skb_segment
9
2.6.24-rc6-git8

#### skb_segment

Perform protocol segmentation on skb.

##### Synopsis

       struct sk_buff * skb_segment
       struct sk_buff * skb
       int features

##### Arguments

`skb`

  buffer to segment

`features`

  features for the output path (see dev->features)

##### Description

This function performs segmentation on the given skb. It returns the segment at the given position. It returns NULL if there are no more segments to generate, or when an error is encountered.

#### LINUX

Kernel Hackers Manual January 2008
skb_cow_data
9
2.6.24-rc6-git8

#### skb_cow_data

Check that a socket buffer's data buffers are writable

##### Synopsis

       int skb_cow_data
       struct sk_buff * skb
       int tailbits
       struct sk_buff ** trailer

##### Arguments

`skb`

  The socket buffer to check.

`tailbits`

  Amount of trailing space to be added

`trailer`

  Returned pointer to the skb where the `tailbits` space begins

##### Description

Make sure that the data buffers attached to a socket buffer are writable. If they are not, private copies are made of the data buffers and the socket buffer is set to use these instead.

If `tailbits` is given, make sure that there is space to write `tailbits` bytes of data beyond current end of socket buffer. `trailer` will be set to point to the skb in which this space begins.

The number of scatterlist elements required to completely map the COW'd and extended socket buffer will be returned.

#### LINUX

Kernel Hackers Manual January 2008
sk_alloc
9
2.6.24-rc6-git8

#### sk_alloc

All socket objects are allocated here

##### Synopsis

       struct sock * sk_alloc
       struct net * net
       int family
       gfp_t priority
       struct proto * prot

##### Arguments

`net`

  the applicable net namespace

`family`

  protocol family

`priority`

  for allocation (`GFP_KERNEL`, `GFP_ATOMIC`, etc)

`prot`

  struct proto associated with this new sock instance

#### LINUX

Kernel Hackers Manual January 2008
sk_wait_data
9
2.6.24-rc6-git8

#### sk_wait_data

wait for data to arrive at sk_receive_queue

##### Synopsis

       int sk_wait_data
       struct sock * sk
       long * timeo

##### Arguments

`sk`

  sock to wait on

`timeo`

  for how long

##### Description

Now socket state including sk->sk_err is changed only under lock, hence we may omit checks after joining wait queue. We check receive queue before `schedule` only as optimization; it is very likely that `release_sock` added new data.

#### LINUX

Kernel Hackers Manual January 2008
skb_recv_datagram
9
2.6.24-rc6-git8

#### skb_recv_datagram

Receive a datagram skbuff

##### Synopsis

       struct sk_buff * skb_recv_datagram
       struct sock * sk
       unsigned flags
       int noblock
       int * err

##### Arguments

`sk`

  socket

`flags`

  MSG_ flags

`noblock`

  blocking operation?

`err`

  error code returned

##### Description

Get a datagram skbuff, understands the peeking, nonblocking wakeups and possible races. This replaces identical code in packet, raw and udp, as well as the IPX AX.25 and Appletalk. It also finally fixes the long standing peek and read race for datagram sockets. If you alter this routine remember it must be re-entrant.

This function will lock the socket if a skb is returned, so the caller needs to unlock the socket in that case (usually by calling skb_free_datagram)

* It does not lock socket since today. This function is * free of race conditions. This measure should/can improve * significantly datagram socket latencies at high loads, * when data copying to user space takes lots of time. * (BTW I've just killed the last `cli` in IP/IPv6/core/netlink/packet * 8) Great win.) * --ANK (980729)

The order of the tests when we find no data waiting are specified quite explicitly by POSIX 1003.1g, don't change them without having the standard around please.

#### LINUX

Kernel Hackers Manual January 2008
skb_kill_datagram
9
2.6.24-rc6-git8

#### skb_kill_datagram

Free a datagram skbuff forcibly

##### Synopsis

       void skb_kill_datagram
       struct sock * sk
       struct sk_buff * skb
       unsigned int flags

##### Arguments

`sk`

  socket

`skb`

  datagram skbuff

`flags`

  MSG_ flags

##### Description

This function frees a datagram skbuff that was received by skb_recv_datagram. The flags argument must match the one used for skb_recv_datagram.

If the MSG_PEEK flag is set, and the packet is still on the receive queue of the socket, it will be taken off the queue before it is freed.

This function currently only disables BH when acquiring the sk_receive_queue lock. Therefore it must not be used in a context where that lock is acquired in an IRQ context.

#### LINUX

Kernel Hackers Manual January 2008
skb_copy_datagram_iovec
9
2.6.24-rc6-git8

#### skb_copy_datagram_iovec

Copy a datagram to an iovec.

##### Synopsis

       int skb_copy_datagram_iovec
       const struct sk_buff * skb
       int offset
       struct iovec * to
       int len

##### Arguments

`skb`

  buffer to copy

`offset`

  offset in the buffer to start copying from

`to`

  io vector to copy to

`len`

  amount of data to copy from buffer to iovec

##### Note

the iovec is modified during the copy.

#### LINUX

Kernel Hackers Manual January 2008
skb_copy_and_csum_datagram_iovec
9
2.6.24-rc6-git8

#### skb_copy_and_csum_datagram_iovec

Copy and checkum skb to user iovec.

##### Synopsis

       int skb_copy_and_csum_datagram_iovec
       struct sk_buff * skb
       int hlen
       struct iovec * iov

##### Arguments

`skb`

  skbuff

`hlen`

  hardware length

`iov`

  io vector

##### Description

Caller _must_ check that skb will fit to this iovec.

##### Returns

0 - success. -EINVAL - checksum failure. -EFAULT - fault during copy. Beware, in this case iovec can be modified!

#### LINUX

Kernel Hackers Manual January 2008
datagram_poll
9
2.6.24-rc6-git8

#### datagram_poll

generic datagram poll

##### Synopsis

       unsigned int datagram_poll
       struct file * file
       struct socket * sock
       poll_table * wait

##### Arguments

`file`

  file struct

`sock`

  socket

`wait`

  poll table

##### Datagram poll

Again totally generic. This also handles sequenced packet sockets providing the socket receive queue is only ever holding data ready to receive.

##### Note

when you _don't_ use this routine for this protocol, and you use a different write policy from `sock_writeable` then please supply your own write_space callback.

#### LINUX

Kernel Hackers Manual January 2008
sk_stream_write_space
9
2.6.24-rc6-git8

#### sk_stream_write_space

stream socket write_space callback.

##### Synopsis

       void sk_stream_write_space
       struct sock * sk

##### Arguments

`sk`

  socket

##### FIXME

write proper description

#### LINUX

Kernel Hackers Manual January 2008
sk_stream_wait_connect
9
2.6.24-rc6-git8

#### sk_stream_wait_connect

Wait for a socket to get into the connected state

##### Synopsis

       int sk_stream_wait_connect
       struct sock * sk
       long * timeo_p

##### Arguments

`sk`

  sock to wait on

`timeo_p`

  for how long to wait

##### Description

Must be called with the socket locked.

#### LINUX

Kernel Hackers Manual January 2008
sk_stream_wait_memory
9
2.6.24-rc6-git8

#### sk_stream_wait_memory

Wait for more memory for a socket

##### Synopsis

       int sk_stream_wait_memory
       struct sock * sk
       long * timeo_p

##### Arguments

`sk`

  socket to wait for memory

`timeo_p`

  for how long

### Socket Filter

#### LINUX

Kernel Hackers Manual January 2008
sk_run_filter
9
2.6.24-rc6-git8

#### sk_run_filter

run a filter on a socket

##### Synopsis

       unsigned int sk_run_filter
       struct sk_buff * skb
       struct sock_filter * filter
       int flen

##### Arguments

`skb`

  buffer to run the filter on

`filter`

  filter to apply

`flen`

  length of filter

##### Description

Decode and apply filter instructions to the skb->data. Return length to keep, 0 for none. skb is the data we are filtering, filter is the array of filter instructions, and len is the number of filter blocks in the array.

#### LINUX

Kernel Hackers Manual January 2008
sk_chk_filter
9
2.6.24-rc6-git8

#### sk_chk_filter

verify socket filter code

##### Synopsis

       int sk_chk_filter
       struct sock_filter * filter
       int flen

##### Arguments

`filter`

  filter to verify

`flen`

  length of filter

##### Description

Check the user's filter code. If we let some ugly filter code slip through kaboom! The filter must contain no references or jumps that are out of range, no illegal instructions, and must end with a RET instruction.

All jumps are forward as they are not signed.

Returns 0 if the rule set is legal or -EINVAL if not.

### Generic Network Statistics

#### LINUX

Kernel Hackers Manual January 2008
struct gnet_stats_basic
9
2.6.24-rc6-git8

#### struct gnet_stats_basic

byte/packet throughput statistics

##### Synopsis

    struct gnet_stats_basic {
      __u64 bytes;
      __u32 packets;
    };

##### Members

bytes

  number of seen bytes

packets

  number of seen packets

#### LINUX

Kernel Hackers Manual January 2008
struct gnet_stats_rate_est
9
2.6.24-rc6-git8

#### struct gnet_stats_rate_est

rate estimator

##### Synopsis

    struct gnet_stats_rate_est {
      __u32 bps;
      __u32 pps;
    };

##### Members

bps

  current byte rate

pps

  current packet rate

#### LINUX

Kernel Hackers Manual January 2008
struct gnet_stats_queue
9
2.6.24-rc6-git8

#### struct gnet_stats_queue

queuing statistics

##### Synopsis

    struct gnet_stats_queue {
      __u32 qlen;
      __u32 backlog;
      __u32 drops;
      __u32 requeues;
      __u32 overlimits;
    };

##### Members

qlen

  queue length

backlog

  backlog size of queue

drops

  number of dropped packets

requeues

  number of requeues

overlimits

  number of enqueues over the limit

#### LINUX

Kernel Hackers Manual January 2008
struct gnet_estimator
9
2.6.24-rc6-git8

#### struct gnet_estimator

rate estimator configuration

##### Synopsis

    struct gnet_estimator {
      signed char interval;
      unsigned char ewma_log;
    };

##### Members

interval

  sampling period

ewma_log

  the log of measurement window weight

#### LINUX

Kernel Hackers Manual January 2008
gnet_stats_start_copy_compat
9
2.6.24-rc6-git8

#### gnet_stats_start_copy_compat

start dumping procedure in compatibility mode

##### Synopsis

       int gnet_stats_start_copy_compat
       struct sk_buff * skb
       int type
       int tc_stats_type
       int xstats_type
       spinlock_t * lock
       struct gnet_dump * d

##### Arguments

`skb`

  socket buffer to put statistics TLVs into

`type`

  TLV type for top level statistic TLV

`tc_stats_type`

  TLV type for backward compatibility struct tc_stats TLV

`xstats_type`

  TLV type for backward compatibility xstats TLV

`lock`

  statistics lock

`d`

  dumping handle

##### Description

Initializes the dumping handle, grabs the statistic lock and appends an empty TLV header to the socket buffer for use a container for all other statistic TLVS.

The dumping handle is marked to be in backward compatibility mode telling all `gnet_stats_copy_XXX` functions to fill a local copy of struct tc_stats.

Returns 0 on success or -1 if the room in the socket buffer was not sufficient.

#### LINUX

Kernel Hackers Manual January 2008
gnet_stats_start_copy
9
2.6.24-rc6-git8

#### gnet_stats_start_copy

start dumping procedure in compatibility mode

##### Synopsis

       int gnet_stats_start_copy
       struct sk_buff * skb
       int type
       spinlock_t * lock
       struct gnet_dump * d

##### Arguments

`skb`

  socket buffer to put statistics TLVs into

`type`

  TLV type for top level statistic TLV

`lock`

  statistics lock

`d`

  dumping handle

##### Description

Initializes the dumping handle, grabs the statistic lock and appends an empty TLV header to the socket buffer for use a container for all other statistic TLVS.

Returns 0 on success or -1 if the room in the socket buffer was not sufficient.

#### LINUX

Kernel Hackers Manual January 2008
gnet_stats_copy_basic
9
2.6.24-rc6-git8

#### gnet_stats_copy_basic

copy basic statistics into statistic TLV

##### Synopsis

       int gnet_stats_copy_basic
       struct gnet_dump * d
       struct gnet_stats_basic * b

##### Arguments

`d`

  dumping handle

`b`

  basic statistics

##### Description

Appends the basic statistics to the top level TLV created by `gnet_stats_start_copy`.

Returns 0 on success or -1 with the statistic lock released if the room in the socket buffer was not sufficient.

#### LINUX

Kernel Hackers Manual January 2008
gnet_stats_copy_rate_est
9
2.6.24-rc6-git8

#### gnet_stats_copy_rate_est

copy rate estimator statistics into statistics TLV

##### Synopsis

       int gnet_stats_copy_rate_est
       struct gnet_dump * d
       struct gnet_stats_rate_est * r

##### Arguments

`d`

  dumping handle

`r`

  rate estimator statistics

##### Description

Appends the rate estimator statistics to the top level TLV created by `gnet_stats_start_copy`.

Returns 0 on success or -1 with the statistic lock released if the room in the socket buffer was not sufficient.

#### LINUX

Kernel Hackers Manual January 2008
gnet_stats_copy_queue
9
2.6.24-rc6-git8

#### gnet_stats_copy_queue

copy queue statistics into statistics TLV

##### Synopsis

       int gnet_stats_copy_queue
       struct gnet_dump * d
       struct gnet_stats_queue * q

##### Arguments

`d`

  dumping handle

`q`

  queue statistics

##### Description

Appends the queue statistics to the top level TLV created by `gnet_stats_start_copy`.

Returns 0 on success or -1 with the statistic lock released if the room in the socket buffer was not sufficient.

#### LINUX

Kernel Hackers Manual January 2008
gnet_stats_copy_app
9
2.6.24-rc6-git8

#### gnet_stats_copy_app

copy application specific statistics into statistics TLV

##### Synopsis

       int gnet_stats_copy_app
       struct gnet_dump * d
       void * st
       int len

##### Arguments

`d`

  dumping handle

`st`

  application specific statistics data

`len`

  length of data

##### Description

Appends the application sepecific statistics to the top level TLV created by `gnet_stats_start_copy` and remembers the data for XSTATS if the dumping handle is in backward compatibility mode.

Returns 0 on success or -1 with the statistic lock released if the room in the socket buffer was not sufficient.

#### LINUX

Kernel Hackers Manual January 2008
gnet_stats_finish_copy
9
2.6.24-rc6-git8

#### gnet_stats_finish_copy

finish dumping procedure

##### Synopsis

       int gnet_stats_finish_copy
       struct gnet_dump * d

##### Arguments

`d`

  dumping handle

##### Description

Corrects the length of the top level TLV to include all TLVs added by `gnet_stats_copy_XXX` calls. Adds the backward compatibility TLVs if `gnet_stats_start_copy_compat` was used and releases the statistics lock.

Returns 0 on success or -1 with the statistic lock released if the room in the socket buffer was not sufficient.

#### LINUX

Kernel Hackers Manual January 2008
gen_new_estimator
9
2.6.24-rc6-git8

#### gen_new_estimator

create a new rate estimator

##### Synopsis

       int gen_new_estimator
       struct gnet_stats_basic * bstats
       struct gnet_stats_rate_est * rate_est
       spinlock_t * stats_lock
       struct rtattr * opt

##### Arguments

`bstats`

  basic statistics

`rate_est`

  rate estimator statistics

`stats_lock`

  statistics lock

`opt`

  rate estimator configuration TLV

##### Description

Creates a new rate estimator with &bstats as source and &rate_est as destination. A new timer with the interval specified in the configuration TLV is created. Upon each interval, the latest statistics will be read from &bstats and the estimated rate will be stored in &rate_est with the statistics lock grabed during this period.

Returns 0 on success or a negative error code.

##### NOTE

Called under rtnl_mutex

#### LINUX

Kernel Hackers Manual January 2008
gen_kill_estimator
9
2.6.24-rc6-git8

#### gen_kill_estimator

remove a rate estimator

##### Synopsis

       void gen_kill_estimator
       struct gnet_stats_basic * bstats
       struct gnet_stats_rate_est * rate_est

##### Arguments

`bstats`

  basic statistics

`rate_est`

  rate estimator statistics

##### Description

Removes the rate estimator specified by &bstats and &rate_est and deletes the timer.

##### NOTE

Called under rtnl_mutex

#### LINUX

Kernel Hackers Manual January 2008
gen_replace_estimator
9
2.6.24-rc6-git8

#### gen_replace_estimator

replace rate estimator configruation

##### Synopsis

       int gen_replace_estimator
       struct gnet_stats_basic * bstats
       struct gnet_stats_rate_est * rate_est
       spinlock_t * stats_lock
       struct rtattr * opt

##### Arguments

`bstats`

  basic statistics

`rate_est`

  rate estimator statistics

`stats_lock`

  statistics lock

`opt`

  rate estimator configuration TLV

##### Description

Replaces the configuration of a rate estimator by calling `gen_kill_estimator` and `gen_new_estimator`.

Returns 0 on success or a negative error code.

### SUN RPC subsystem

#### LINUX

Kernel Hackers Manual January 2008
xdr_encode_opaque_fixed
9
2.6.24-rc6-git8

#### xdr_encode_opaque_fixed

Encode fixed length opaque data

##### Synopsis

       __be32 * xdr_encode_opaque_fixed
       __be32 * p
       const void * ptr
       unsigned int nbytes

##### Arguments

`p`

  pointer to current position in XDR buffer.

`ptr`

  pointer to data to encode (or NULL)

`nbytes`

  size of data.

##### Description

Copy the array of data of length nbytes at ptr to the XDR buffer at position p, then align to the next 32-bit boundary by padding with zero bytes (see RFC1832).

##### Note

if ptr is NULL, only the padding is performed.

Returns the updated current XDR buffer position

#### LINUX

Kernel Hackers Manual January 2008
xdr_encode_opaque
9
2.6.24-rc6-git8

#### xdr_encode_opaque

Encode variable length opaque data

##### Synopsis

       __be32 * xdr_encode_opaque
       __be32 * p
       const void * ptr
       unsigned int nbytes

##### Arguments

`p`

  pointer to current position in XDR buffer.

`ptr`

  pointer to data to encode (or NULL)

`nbytes`

  size of data.

##### Description

Returns the updated current XDR buffer position

#### LINUX

Kernel Hackers Manual January 2008
xdr_init_encode
9
2.6.24-rc6-git8

#### xdr_init_encode

Initialize a struct xdr_stream for sending data.

##### Synopsis

       void xdr_init_encode
       struct xdr_stream * xdr
       struct xdr_buf * buf
       __be32 * p

##### Arguments

`xdr`

  pointer to xdr_stream struct

`buf`

  pointer to XDR buffer in which to encode data

`p`

  current pointer inside XDR buffer

##### Note

at the moment the RPC client only passes the length of our scratch buffer in the xdr_buf's header kvec. Previously this meant we needed to call `xdr_adjust_iovec` after encoding the data. With the new scheme, the xdr_stream manages the details of the buffer length, and takes care of adjusting the kvec length for us.

#### LINUX

Kernel Hackers Manual January 2008
xdr_reserve_space
9
2.6.24-rc6-git8

#### xdr_reserve_space

Reserve buffer space for sending

##### Synopsis

       __be32 * xdr_reserve_space
       struct xdr_stream * xdr
       size_t nbytes

##### Arguments

`xdr`

  pointer to xdr_stream

`nbytes`

  number of bytes to reserve

##### Description

Checks that we have enough buffer space to encode 'nbytes' more bytes of data. If so, update the total xdr_buf length, and adjust the length of the current kvec.

#### LINUX

Kernel Hackers Manual January 2008
xdr_write_pages
9
2.6.24-rc6-git8

#### xdr_write_pages

Insert a list of pages into an XDR buffer for sending

##### Synopsis

       void xdr_write_pages
       struct xdr_stream * xdr
       struct page ** pages
       unsigned int base
       unsigned int len

##### Arguments

`xdr`

  pointer to xdr_stream

`pages`

  list of pages

`base`

  offset of first byte

`len`

  length of data in bytes

#### LINUX

Kernel Hackers Manual January 2008
xdr_init_decode
9
2.6.24-rc6-git8

#### xdr_init_decode

Initialize an xdr_stream for decoding data.

##### Synopsis

       void xdr_init_decode
       struct xdr_stream * xdr
       struct xdr_buf * buf
       __be32 * p

##### Arguments

`xdr`

  pointer to xdr_stream struct

`buf`

  pointer to XDR buffer from which to decode data

`p`

  current pointer inside XDR buffer

#### LINUX

Kernel Hackers Manual January 2008
xdr_inline_decode
9
2.6.24-rc6-git8

#### xdr_inline_decode

Retrieve non-page XDR data to decode

##### Synopsis

       __be32 * xdr_inline_decode
       struct xdr_stream * xdr
       size_t nbytes

##### Arguments

`xdr`

  pointer to xdr_stream struct

`nbytes`

  number of bytes of data to decode

##### Description

Check if the input buffer is long enough to enable us to decode 'nbytes' more bytes of data starting at the current position. If so return the current pointer, then update the current pointer position.

#### LINUX

Kernel Hackers Manual January 2008
xdr_read_pages
9
2.6.24-rc6-git8

#### xdr_read_pages

Ensure page-based XDR data to decode is aligned at current pointer position

##### Synopsis

       void xdr_read_pages
       struct xdr_stream * xdr
       unsigned int len

##### Arguments

`xdr`

  pointer to xdr_stream struct

`len`

  number of bytes of page data

##### Description

Moves data beyond the current pointer position from the XDR head[] buffer into the page list. Any data that lies beyond current position + len bytes is moved into the XDR tail[].

#### LINUX

Kernel Hackers Manual January 2008
xdr_enter_page
9
2.6.24-rc6-git8

#### xdr_enter_page

decode data from the XDR page

##### Synopsis

       void xdr_enter_page
       struct xdr_stream * xdr
       unsigned int len

##### Arguments

`xdr`

  pointer to xdr_stream struct

`len`

  number of bytes of page data

##### Description

Moves data beyond the current pointer position from the XDR head[] buffer into the page list. Any data that lies beyond current position + len bytes is moved into the XDR tail[]. The current pointer is then repositioned at the beginning of the first XDR page.

#### LINUX

Kernel Hackers Manual January 2008
svc_print_addr
9
2.6.24-rc6-git8

#### svc_print_addr

Format rq_addr field for printing

##### Synopsis

       char * svc_print_addr
       struct svc_rqst * rqstp
       char * buf
       size_t len

##### Arguments

`rqstp`

  svc_rqst struct containing address to print

`buf`

  target buffer for formatted address

`len`

  length of target buffer

#### LINUX

Kernel Hackers Manual January 2008
svc_reserve
9
2.6.24-rc6-git8

#### svc_reserve

change the space reserved for the reply to a request.

##### Synopsis

       void svc_reserve
       struct svc_rqst * rqstp
       int space

##### Arguments

`rqstp`

  The request in question

`space`

  new max space to reserve

##### Description

Each request reserves some space on the output queue of the socket to make sure the reply fits. This function reduces that reserved space to be the amount of space used already, plus `space`.

#### LINUX

Kernel Hackers Manual January 2008
svc_makesock
9
2.6.24-rc6-git8

#### svc_makesock

Make a socket for nfsd and lockd

##### Synopsis

       int svc_makesock
       struct svc_serv * serv
       int protocol
       unsigned short port
       int flags

##### Arguments

`serv`

  RPC server structure

`protocol`

  transport protocol to use

`port`

  port to use

`flags`

  requested socket characteristics

#### LINUX

Kernel Hackers Manual January 2008
rpc_wake_up
9
2.6.24-rc6-git8

#### rpc_wake_up

wake up all rpc_tasks

##### Synopsis

       void rpc_wake_up
       struct rpc_wait_queue * queue

##### Arguments

`queue`

  rpc_wait_queue on which the tasks are sleeping

##### Description

Grabs queue->lock

#### LINUX

Kernel Hackers Manual January 2008
rpc_wake_up_status
9
2.6.24-rc6-git8

#### rpc_wake_up_status

wake up all rpc_tasks and set their status value.

##### Synopsis

       void rpc_wake_up_status
       struct rpc_wait_queue * queue
       int status

##### Arguments

`queue`

  rpc_wait_queue on which the tasks are sleeping

`status`

  status value to set

##### Description

Grabs queue->lock

#### LINUX

Kernel Hackers Manual January 2008
rpc_malloc
9
2.6.24-rc6-git8

#### rpc_malloc

allocate an RPC buffer

##### Synopsis

       void * rpc_malloc
       struct rpc_task * task
       size_t size

##### Arguments

`task`

  RPC task that will use this buffer

`size`

  requested byte size

##### Description

To prevent rpciod from hanging, this allocator never sleeps, returning NULL if the request cannot be serviced immediately. The caller can arrange to sleep in a way that is safe for rpciod.

Most requests are 'small' (under 2KiB) and can be serviced from a mempool, ensuring that NFS reads and writes can always proceed, and that there is good locality of reference for these buffers.

In order to avoid memory starvation triggering more writebacks of NFS requests, we avoid using GFP_KERNEL.

#### LINUX

Kernel Hackers Manual January 2008
rpc_free
9
2.6.24-rc6-git8

#### rpc_free

free buffer allocated via rpc_malloc

##### Synopsis

       void rpc_free
       void * buffer

##### Arguments

`buffer`

  buffer to free

## Network device support

### Driver Support

#### LINUX

Kernel Hackers Manual January 2008
dev_add_pack
9
2.6.24-rc6-git8

#### dev_add_pack

add packet handler

##### Synopsis

       void dev_add_pack
       struct packet_type * pt

##### Arguments

`pt`

  packet type declaration

##### Description

Add a protocol handler to the networking stack. The passed &packet_type is linked into kernel lists and may not be freed until it has been removed from the kernel lists.

This call does not sleep therefore it can not guarantee all CPU's that are in middle of receiving packets will see the new packet type (until the next received packet).

#### LINUX

Kernel Hackers Manual January 2008
__dev_remove_pack
9
2.6.24-rc6-git8

#### __dev_remove_pack

remove packet handler

##### Synopsis

       void __dev_remove_pack
       struct packet_type * pt

##### Arguments

`pt`

  packet type declaration

##### Description

Remove a protocol handler that was previously added to the kernel protocol handlers by `dev_add_pack`. The passed &packet_type is removed from the kernel lists and can be freed or reused once this function returns.

The packet type might still be in use by receivers and must not be freed until after all the CPU's have gone through a quiescent state.

#### LINUX

Kernel Hackers Manual January 2008
dev_remove_pack
9
2.6.24-rc6-git8

#### dev_remove_pack

remove packet handler

##### Synopsis

       void dev_remove_pack
       struct packet_type * pt

##### Arguments

`pt`

  packet type declaration

##### Description

Remove a protocol handler that was previously added to the kernel protocol handlers by `dev_add_pack`. The passed &packet_type is removed from the kernel lists and can be freed or reused once this function returns.

This call sleeps to guarantee that no CPU is looking at the packet type after return.

#### LINUX

Kernel Hackers Manual January 2008
netdev_boot_setup_check
9
2.6.24-rc6-git8

#### netdev_boot_setup_check

check boot time settings

##### Synopsis

       int netdev_boot_setup_check
       struct net_device * dev

##### Arguments

`dev`

  the netdevice

##### Description

Check boot time settings for the device. The found settings are set for the device to be used later in the device probing. Returns 0 if no settings found, 1 if they are.

#### LINUX

Kernel Hackers Manual January 2008
__dev_get_by_name
9
2.6.24-rc6-git8

#### __dev_get_by_name

find a device by its name

##### Synopsis

       struct net_device * __dev_get_by_name
       struct net * net
       const char * name

##### Arguments

`net`

  the applicable net namespace

`name`

  name to find

##### Description

Find an interface by name. Must be called under RTNL semaphore or `dev_base_lock`. If the name is found a pointer to the device is returned. If the name is not found then `NULL` is returned. The reference counters are not incremented so the caller must be careful with locks.

#### LINUX

Kernel Hackers Manual January 2008
dev_get_by_name
9
2.6.24-rc6-git8

#### dev_get_by_name

find a device by its name

##### Synopsis

       struct net_device * dev_get_by_name
       struct net * net
       const char * name

##### Arguments

`net`

  the applicable net namespace

`name`

  name to find

##### Description

Find an interface by name. This can be called from any context and does its own locking. The returned handle has the usage count incremented and the caller must use `dev_put` to release it when it is no longer needed. `NULL` is returned if no matching device is found.

#### LINUX

Kernel Hackers Manual January 2008
__dev_get_by_index
9
2.6.24-rc6-git8

#### __dev_get_by_index

find a device by its ifindex

##### Synopsis

       struct net_device * __dev_get_by_index
       struct net * net
       int ifindex

##### Arguments

`net`

  the applicable net namespace

`ifindex`

  index of device

##### Description

Search for an interface by index. Returns `NULL` if the device is not found or a pointer to the device. The device has not had its reference counter increased so the caller must be careful about locking. The caller must hold either the RTNL semaphore or `dev_base_lock`.

#### LINUX

Kernel Hackers Manual January 2008
dev_get_by_index
9
2.6.24-rc6-git8

#### dev_get_by_index

find a device by its ifindex

##### Synopsis

       struct net_device * dev_get_by_index
       struct net * net
       int ifindex

##### Arguments

`net`

  the applicable net namespace

`ifindex`

  index of device

##### Description

Search for an interface by index. Returns NULL if the device is not found or a pointer to the device. The device returned has had a reference added and the pointer is safe until the user calls dev_put to indicate they have finished with it.

#### LINUX

Kernel Hackers Manual January 2008
dev_getbyhwaddr
9
2.6.24-rc6-git8

#### dev_getbyhwaddr

find a device by its hardware address

##### Synopsis

       struct net_device * dev_getbyhwaddr
       struct net * net
       unsigned short type
       char * ha

##### Arguments

`net`

  the applicable net namespace

`type`

  media type of device

`ha`

  hardware address

##### Description

Search for an interface by MAC address. Returns NULL if the device is not found or a pointer to the device. The caller must hold the rtnl semaphore. The returned device has not had its ref count increased and the caller must therefore be careful about locking

##### BUGS

If the API was consistent this would be __dev_get_by_hwaddr

#### LINUX

Kernel Hackers Manual January 2008
dev_get_by_flags
9
2.6.24-rc6-git8

#### dev_get_by_flags

find any device with given flags

##### Synopsis

       struct net_device * dev_get_by_flags
       struct net * net
       unsigned short if_flags
       unsigned short mask

##### Arguments

`net`

  the applicable net namespace

`if_flags`

  IFF_* values

`mask`

  bitmask of bits in if_flags to check

##### Description

Search for any interface with the given flags. Returns NULL if a device is not found or a pointer to the device. The device returned has had a reference added and the pointer is safe until the user calls dev_put to indicate they have finished with it.

#### LINUX

Kernel Hackers Manual January 2008
dev_valid_name
9
2.6.24-rc6-git8

#### dev_valid_name

check if name is okay for network device

##### Synopsis

       int dev_valid_name
       const char * name

##### Arguments

`name`

  name string

##### Description

Network device names need to be valid file names to to allow sysfs to work. We also disallow any kind of whitespace.

#### LINUX

Kernel Hackers Manual January 2008
dev_alloc_name
9
2.6.24-rc6-git8

#### dev_alloc_name

allocate a name for a device

##### Synopsis

       int dev_alloc_name
       struct net_device * dev
       const char * name

##### Arguments

`dev`

  device

`name`

  name format string

##### Description

Passed a format string - eg lt`d` it will try and find a suitable id. It scans list of devices to build up a free map, then chooses the first empty slot. The caller must hold the dev_base or rtnl lock while allocating the name and adding the device in order to avoid duplicates. Limited to bits_per_byte * page size devices (ie 32K on most platforms). Returns the number of the unit assigned or a negative errno code.

#### LINUX

Kernel Hackers Manual January 2008
netdev_features_change
9
2.6.24-rc6-git8

#### netdev_features_change

device changes features

##### Synopsis

       void netdev_features_change
       struct net_device * dev

##### Arguments

`dev`

  device to cause notification

##### Description

Called to indicate a device has changed features.

#### LINUX

Kernel Hackers Manual January 2008
netdev_state_change
9
2.6.24-rc6-git8

#### netdev_state_change

device changes state

##### Synopsis

       void netdev_state_change
       struct net_device * dev

##### Arguments

`dev`

  device to cause notification

##### Description

Called to indicate a device has changed state. This function calls the notifier chains for netdev_chain and sends a NEWLINK message to the routing socket.

#### LINUX

Kernel Hackers Manual January 2008
dev_load
9
2.6.24-rc6-git8

#### dev_load

load a network module

##### Synopsis

       void dev_load
       struct net * net
       const char * name

##### Arguments

`net`

  the applicable net namespace

`name`

  name of interface

##### Description

If a network interface is not present and the process has suitable privileges this function loads the module. If module loading is not available in this kernel then it becomes a nop.

#### LINUX

Kernel Hackers Manual January 2008
dev_open
9
2.6.24-rc6-git8

#### dev_open

prepare an interface for use.

##### Synopsis

       int dev_open
       struct net_device * dev

##### Arguments

`dev`

  device to open

##### Description

Takes a device from down to up state. The device's private open function is invoked and then the multicast lists are loaded. Finally the device is moved into the up state and a `NETDEV_UP` message is sent to the netdev notifier chain.

Calling this function on an active interface is a nop. On a failure a negative errno code is returned.

#### LINUX

Kernel Hackers Manual January 2008
dev_close
9
2.6.24-rc6-git8

#### dev_close

shutdown an interface.

##### Synopsis

       int dev_close
       struct net_device * dev

##### Arguments

`dev`

  device to shutdown

##### Description

This function moves an active device into down state. A `NETDEV_GOING_DOWN` is sent to the netdev notifier chain. The device is then deactivated and finally a `NETDEV_DOWN` is sent to the notifier chain.

#### LINUX

Kernel Hackers Manual January 2008
register_netdevice_notifier
9
2.6.24-rc6-git8

#### register_netdevice_notifier

register a network notifier block

##### Synopsis

       int register_netdevice_notifier
       struct notifier_block * nb

##### Arguments

`nb`

  notifier

##### Description

Register a notifier to be called when network device events occur. The notifier passed is linked into the kernel structures and must not be reused until it has been unregistered. A negative errno code is returned on a failure.

When registered all registration and up events are replayed to the new notifier to allow device to have a race free view of the network device list.

#### LINUX

Kernel Hackers Manual January 2008
unregister_netdevice_notifier
9
2.6.24-rc6-git8

#### unregister_netdevice_notifier

unregister a network notifier block

##### Synopsis

       int unregister_netdevice_notifier
       struct notifier_block * nb

##### Arguments

`nb`

  notifier

##### Description

Unregister a notifier previously registered by `register_netdevice_notifier`. The notifier is unlinked into the kernel structures and may then be reused. A negative errno code is returned on a failure.

#### LINUX

Kernel Hackers Manual January 2008
netif_device_detach
9
2.6.24-rc6-git8

#### netif_device_detach

mark device as removed

##### Synopsis

       void netif_device_detach
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Mark device as removed from system and therefore no longer available.

#### LINUX

Kernel Hackers Manual January 2008
netif_device_attach
9
2.6.24-rc6-git8

#### netif_device_attach

mark device as attached

##### Synopsis

       void netif_device_attach
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Mark device as attached from system and restart if needed.

#### LINUX

Kernel Hackers Manual January 2008
skb_gso_segment
9
2.6.24-rc6-git8

#### skb_gso_segment

Perform segmentation on skb.

##### Synopsis

       struct sk_buff * skb_gso_segment
       struct sk_buff * skb
       int features

##### Arguments

`skb`

  buffer to segment

`features`

  features for the output path (see dev->features)

##### Description

This function segments the given skb and returns a list of segments.

It may return NULL if the skb requires no segmentation. This is only possible when GSO is used for verifying header integrity.

#### LINUX

Kernel Hackers Manual January 2008
dev_queue_xmit
9
2.6.24-rc6-git8

#### dev_queue_xmit

transmit a buffer

##### Synopsis

       int dev_queue_xmit
       struct sk_buff * skb

##### Arguments

`skb`

  buffer to transmit

##### Description

Queue a buffer for transmission to a network device. The caller must have set the device and priority and built the buffer before calling this function. The function can be called from an interrupt.

A negative errno code is returned on a failure. A success does not guarantee the frame will be transmitted as it may be dropped due to congestion or traffic shaping.

----------------------------------------------------------------------------------- I notice this method can also return errors from the queue disciplines, including NET_XMIT_DROP, which is a positive value. So, errors can also be positive.

Regardless of the return value, the skb is consumed, so it is currently difficult to retry a send to this method. (You can bump the ref count before sending to hold a reference for retry if you are careful.)

When calling this method, interrupts MUST be enabled. This is because the BH enable code must have IRQs enabled so that it will not deadlock. --BLG

#### LINUX

Kernel Hackers Manual January 2008
netif_rx
9
2.6.24-rc6-git8

#### netif_rx

post buffer to the network code

##### Synopsis

       int netif_rx
       struct sk_buff * skb

##### Arguments

`skb`

  buffer to post

##### Description

This function receives a packet from a device driver and queues it for the upper (protocol) levels to process. It always succeeds. The buffer may be dropped during processing for congestion control or by the protocol layers.

##### return values

NET_RX_SUCCESS (no congestion) NET_RX_DROP (packet was dropped)

#### LINUX

Kernel Hackers Manual January 2008
netif_receive_skb
9
2.6.24-rc6-git8

#### netif_receive_skb

process receive buffer from network

##### Synopsis

       int netif_receive_skb
       struct sk_buff * skb

##### Arguments

`skb`

  buffer to process

##### Description

`netif_receive_skb` is the main receive data processing function. It always succeeds. The buffer may be dropped during processing for congestion control or by the protocol layers.

This function may only be called from softirq context and interrupts should be enabled.

Return values (usually ignored):

##### NET_RX_SUCCESS

no congestion

##### NET_RX_DROP

packet was dropped

#### LINUX

Kernel Hackers Manual January 2008
__napi_schedule
9
2.6.24-rc6-git8

#### __napi_schedule

schedule for receive

##### Synopsis

       void fastcall __napi_schedule
       struct napi_struct * n

##### Arguments

`n`

  entry to schedule

##### Description

The entry's receive function will be scheduled to run

#### LINUX

Kernel Hackers Manual January 2008
register_gifconf
9
2.6.24-rc6-git8

#### register_gifconf

register a SIOCGIF handler

##### Synopsis

       int register_gifconf
       unsigned int family
       gifconf_func_t * gifconf

##### Arguments

`family`

  Address family

`gifconf`

  Function handler

##### Description

Register protocol dependent address dumping routines. The handler that is passed must not be freed or reused until it has been replaced by another handler.

#### LINUX

Kernel Hackers Manual January 2008
netdev_set_master
9
2.6.24-rc6-git8

#### netdev_set_master

set up master/slave pair

##### Synopsis

       int netdev_set_master
       struct net_device * slave
       struct net_device * master

##### Arguments

`slave`

  slave device

`master`

  new master device

##### Description

Changes the master device of the slave. Pass `NULL` to break the bonding. The caller must hold the RTNL semaphore. On a failure a negative errno code is returned. On success the reference counts are adjusted, `RTM_NEWLINK` is sent to the routing socket and the function returns zero.

#### LINUX

Kernel Hackers Manual January 2008
dev_set_promiscuity
9
2.6.24-rc6-git8

#### dev_set_promiscuity

update promiscuity count on a device

##### Synopsis

       void dev_set_promiscuity
       struct net_device * dev
       int inc

##### Arguments

`dev`

  device

`inc`

  modifier

##### Description

Add or remove promiscuity from a device. While the count in the device remains above zero the interface remains promiscuous. Once it hits zero the device reverts back to normal filtering operation. A negative inc value is used to drop promiscuity on the device.

#### LINUX

Kernel Hackers Manual January 2008
dev_set_allmulti
9
2.6.24-rc6-git8

#### dev_set_allmulti

update allmulti count on a device

##### Synopsis

       void dev_set_allmulti
       struct net_device * dev
       int inc

##### Arguments

`dev`

  device

`inc`

  modifier

##### Description

Add or remove reception of all multicast frames to a device. While the count in the device remains above zero the interface remains listening to all interfaces. Once it hits zero the device reverts back to normal filtering operation. A negative `inc` value is used to drop the counter when releasing a resource needing all multicasts.

#### LINUX

Kernel Hackers Manual January 2008
dev_unicast_delete
9
2.6.24-rc6-git8

#### dev_unicast_delete

Release secondary unicast address.

##### Synopsis

       int dev_unicast_delete
       struct net_device * dev
       void * addr
       int alen

##### Arguments

`dev`

  device

`addr`

  address to delete

`alen`

  length of `addr`

##### Description

Release reference to a secondary unicast address and remove it from the device if the reference count drops to zero.

The caller must hold the rtnl_mutex.

#### LINUX

Kernel Hackers Manual January 2008
dev_unicast_add
9
2.6.24-rc6-git8

#### dev_unicast_add

add a secondary unicast address

##### Synopsis

       int dev_unicast_add
       struct net_device * dev
       void * addr
       int alen

##### Arguments

`dev`

  device

`addr`

  address to delete

`alen`

  length of `addr`

##### Description

Add a secondary unicast address to the device or increase the reference count if it already exists.

The caller must hold the rtnl_mutex.

#### LINUX

Kernel Hackers Manual January 2008
register_netdevice
9
2.6.24-rc6-git8

#### register_netdevice

register a network device

##### Synopsis

       int register_netdevice
       struct net_device * dev

##### Arguments

`dev`

  device to register

##### Description

Take a completed network device structure and add it to the kernel interfaces. A `NETDEV_REGISTER` message is sent to the netdev notifier chain. 0 is returned on success. A negative errno code is returned on a failure to set up the device, or if the name is a duplicate.

Callers must hold the rtnl semaphore. You may want `register_netdev` instead of this.

##### BUGS

The locking appears insufficient to guarantee two parallel registers will not get the same name.

#### LINUX

Kernel Hackers Manual January 2008
register_netdev
9
2.6.24-rc6-git8

#### register_netdev

register a network device

##### Synopsis

       int register_netdev
       struct net_device * dev

##### Arguments

`dev`

  device to register

##### Description

Take a completed network device structure and add it to the kernel interfaces. A `NETDEV_REGISTER` message is sent to the netdev notifier chain. 0 is returned on success. A negative errno code is returned on a failure to set up the device, or if the name is a duplicate.

This is a wrapper around register_netdevice that takes the rtnl semaphore and expands the device name if you passed a format string to alloc_netdev.

#### LINUX

Kernel Hackers Manual January 2008
alloc_netdev_mq
9
2.6.24-rc6-git8

#### alloc_netdev_mq

allocate network device

##### Synopsis

       struct net_device * alloc_netdev_mq
       int sizeof_priv
       const char * name
       void (*setup)
         struct net_device *
       unsigned int queue_count

##### Arguments

`sizeof_priv`

  size of private data to allocate space for

`name`

  device name format string

`setup`

  callback to initialize device

`queue_count`

  the number of subqueues to allocate

##### Description

Allocates a struct net_device with private data area for driver use and performs basic initialization. Also allocates subquue structs for each queue on the device at the end of the netdevice.

#### LINUX

Kernel Hackers Manual January 2008
free_netdev
9
2.6.24-rc6-git8

#### free_netdev

free network device

##### Synopsis

       void free_netdev
       struct net_device * dev

##### Arguments

`dev`

  device

##### Description

This function does the last stage of destroying an allocated device interface. The reference to the device object is released. If this is the last reference then it will be freed.

#### LINUX

Kernel Hackers Manual January 2008
unregister_netdevice
9
2.6.24-rc6-git8

#### unregister_netdevice

remove device from the kernel

##### Synopsis

       void unregister_netdevice
       struct net_device * dev

##### Arguments

`dev`

  device

##### Description

This function shuts down a device interface and removes it from the kernel tables.

Callers must hold the rtnl semaphore. You may want `unregister_netdev` instead of this.

#### LINUX

Kernel Hackers Manual January 2008
unregister_netdev
9
2.6.24-rc6-git8

#### unregister_netdev

remove device from the kernel

##### Synopsis

       void unregister_netdev
       struct net_device * dev

##### Arguments

`dev`

  device

##### Description

This function shuts down a device interface and removes it from the kernel tables.

This is just a wrapper for unregister_netdevice that takes the rtnl semaphore. In general you want to use this and not unregister_netdevice.

#### LINUX

Kernel Hackers Manual January 2008
netdev_compute_features
9
2.6.24-rc6-git8

#### netdev_compute_features

compute conjunction of two feature sets

##### Synopsis

       int netdev_compute_features
       unsigned long all
       unsigned long one

##### Arguments

`all`

  first feature set

`one`

  second feature set

##### Description

Computes a new feature set after adding a device with feature set `one` to the master device with current feature set `all`. Returns the new feature set.

#### LINUX

Kernel Hackers Manual January 2008
eth_header
9
2.6.24-rc6-git8

#### eth_header

create the Ethernet header

##### Synopsis

       int eth_header
       struct sk_buff * skb
       struct net_device * dev
       unsigned short type
       const void * daddr
       const void * saddr
       unsigned len

##### Arguments

`skb`

  buffer to alter

`dev`

  source device

`type`

  Ethernet type field

`daddr`

  destination address (NULL leave destination address)

`saddr`

  source address (NULL use device source address)

`len`

  packet length (<= skb->len)

##### Description

Set the protocol type. For a packet of type ETH_P_802_3 we put the length in here instead. It is up to the 802.2 layer to carry protocol information.

#### LINUX

Kernel Hackers Manual January 2008
eth_rebuild_header
9
2.6.24-rc6-git8

#### eth_rebuild_header

rebuild the Ethernet MAC header.

##### Synopsis

       int eth_rebuild_header
       struct sk_buff * skb

##### Arguments

`skb`

  socket buffer to update

##### Description

This is called after an ARP or IPV6 ndisc it's resolution on this sk_buff. We now let protocol (ARP) fill in the other fields.

This routine CANNOT use cached dst->neigh! Really, it is used only when dst->neigh is wrong.

#### LINUX

Kernel Hackers Manual January 2008
eth_type_trans
9
2.6.24-rc6-git8

#### eth_type_trans

determine the packet's protocol ID.

##### Synopsis

       __be16 eth_type_trans
       struct sk_buff * skb
       struct net_device * dev

##### Arguments

`skb`

  received socket data

`dev`

  receiving network device

##### Description

The rule here is that we assume 802.3 if the type field is short enough to be a length. This is normal practice and works for any 'now in use' protocol.

#### LINUX

Kernel Hackers Manual January 2008
eth_header_parse
9
2.6.24-rc6-git8

#### eth_header_parse

extract hardware address from packet

##### Synopsis

       int eth_header_parse
       const struct sk_buff * skb
       unsigned char * haddr

##### Arguments

`skb`

  packet to extract header from

`haddr`

  destination buffer

#### LINUX

Kernel Hackers Manual January 2008
eth_header_cache
9
2.6.24-rc6-git8

#### eth_header_cache

fill cache entry from neighbour

##### Synopsis

       int eth_header_cache
       const struct neighbour * neigh
       struct hh_cache * hh

##### Arguments

`neigh`

  source neighbour

`hh`

  destination cache entry Create an Ethernet header template from the neighbour.

#### LINUX

Kernel Hackers Manual January 2008
eth_header_cache_update
9
2.6.24-rc6-git8

#### eth_header_cache_update

update cache entry

##### Synopsis

       void eth_header_cache_update
       struct hh_cache * hh
       const struct net_device * dev
       const unsigned char * haddr

##### Arguments

`hh`

  destination cache entry

`dev`

  network device

`haddr`

  new hardware address

##### Description

Called by Address Resolution module to notify changes in address.

#### LINUX

Kernel Hackers Manual January 2008
ether_setup
9
2.6.24-rc6-git8

#### ether_setup

setup Ethernet network device

##### Synopsis

       void ether_setup
       struct net_device * dev

##### Arguments

`dev`

  network device Fill in the fields of the device structure with Ethernet-generic values.

#### LINUX

Kernel Hackers Manual January 2008
alloc_etherdev_mq
9
2.6.24-rc6-git8

#### alloc_etherdev_mq

Allocates and sets up an Ethernet device

##### Synopsis

       struct net_device * alloc_etherdev_mq
       int sizeof_priv
       unsigned int queue_count

##### Arguments

`sizeof_priv`

  Size of additional driver-private structure to be allocated for this Ethernet device

`queue_count`

  The number of queues this device has.

##### Description

Fill in the fields of the device structure with Ethernet-generic values. Basically does everything except registering the device.

Constructs a new net device, complete with a private data area of size (sizeof_priv). A 32-byte (not bit) alignment is enforced for this private data area.

#### LINUX

Kernel Hackers Manual January 2008
netif_carrier_on
9
2.6.24-rc6-git8

#### netif_carrier_on

set carrier

##### Synopsis

       void netif_carrier_on
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Device has detected that carrier.

#### LINUX

Kernel Hackers Manual January 2008
netif_carrier_off
9
2.6.24-rc6-git8

#### netif_carrier_off

clear carrier

##### Synopsis

       void netif_carrier_off
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Device has detected loss of carrier.

#### LINUX

Kernel Hackers Manual January 2008
is_zero_ether_addr
9
2.6.24-rc6-git8

#### is_zero_ether_addr

Determine if give Ethernet address is all zeros.

##### Synopsis

       int is_zero_ether_addr
       const u8 * addr

##### Arguments

`addr`

  Pointer to a six-byte array containing the Ethernet address

##### Description

Return true if the address is all zeroes.

#### LINUX

Kernel Hackers Manual January 2008
is_multicast_ether_addr
9
2.6.24-rc6-git8

#### is_multicast_ether_addr

Determine if the Ethernet address is a multicast.

##### Synopsis

       int is_multicast_ether_addr
       const u8 * addr

##### Arguments

`addr`

  Pointer to a six-byte array containing the Ethernet address

##### Description

Return true if the address is a multicast address. By definition the broadcast address is also a multicast address.

#### LINUX

Kernel Hackers Manual January 2008
is_local_ether_addr
9
2.6.24-rc6-git8

#### is_local_ether_addr

Determine if the Ethernet address is locally-assigned

##### Synopsis

       int is_local_ether_addr
       const u8 * addr

##### Arguments

`addr`

  Pointer to a six-byte array containing the Ethernet address

##### Description

Return true if the address is a local address.

##### Description

Return true if the address is a local address.

#### LINUX

Kernel Hackers Manual January 2008
is_broadcast_ether_addr
9
2.6.24-rc6-git8

#### is_broadcast_ether_addr

Determine if the Ethernet address is broadcast

##### Synopsis

       int is_broadcast_ether_addr
       const u8 * addr

##### Arguments

`addr`

  Pointer to a six-byte array containing the Ethernet address

##### Description

Return true if the address is the broadcast address.

#### LINUX

Kernel Hackers Manual January 2008
is_valid_ether_addr
9
2.6.24-rc6-git8

#### is_valid_ether_addr

Determine if the given Ethernet address is valid

##### Synopsis

       int is_valid_ether_addr
       const u8 * addr

##### Arguments

`addr`

  Pointer to a six-byte array containing the Ethernet address

##### Description

Check that the Ethernet address (MAC) is not 00:00:00:00:00:00, is not a multicast address, and is not FF:FF:FF:FF:FF:FF.

Return true if the address is valid.

#### LINUX

Kernel Hackers Manual January 2008
random_ether_addr
9
2.6.24-rc6-git8

#### random_ether_addr

Generate software assigned random Ethernet address

##### Synopsis

       void random_ether_addr
       u8 * addr

##### Arguments

`addr`

  Pointer to a six-byte array containing the Ethernet address

##### Description

Generate a random Ethernet address (MAC) that is not multicast and has the local assigned bit set.

#### LINUX

Kernel Hackers Manual January 2008
compare_ether_addr
9
2.6.24-rc6-git8

#### compare_ether_addr

Compare two Ethernet addresses

##### Synopsis

       unsigned compare_ether_addr
       const u8 * addr1
       const u8 * addr2

##### Arguments

`addr1`

  Pointer to a six-byte array containing the Ethernet address

`addr2`

  Pointer other six-byte array containing the Ethernet address

##### Description

Compare two ethernet addresses, returns 0 if equal

#### LINUX

Kernel Hackers Manual January 2008
napi_schedule_prep
9
2.6.24-rc6-git8

#### napi_schedule_prep

check if napi can be scheduled

##### Synopsis

       int napi_schedule_prep
       struct napi_struct * n

##### Arguments

`n`

  napi context

##### Description

Test if NAPI routine is already running, and if not mark it as running. This is used as a condition variable insure only one NAPI poll instance runs

#### LINUX

Kernel Hackers Manual January 2008
napi_schedule
9
2.6.24-rc6-git8

#### napi_schedule

schedule NAPI poll

##### Synopsis

       void napi_schedule
       struct napi_struct * n

##### Arguments

`n`

  napi context

##### Description

Schedule NAPI poll routine to be called if it is not already running.

#### LINUX

Kernel Hackers Manual January 2008
__napi_complete
9
2.6.24-rc6-git8

#### __napi_complete

NAPI processing complete

##### Synopsis

       void __napi_complete
       struct napi_struct * n

##### Arguments

`n`

  napi context

##### Description

Mark NAPI processing as complete.

#### LINUX

Kernel Hackers Manual January 2008
napi_disable
9
2.6.24-rc6-git8

#### napi_disable

prevent NAPI from scheduling

##### Synopsis

       void napi_disable
       struct napi_struct * n

##### Arguments

`n`

  napi context

##### Description

Stop NAPI from being scheduled on this context. Waits till any outstanding processing completes.

#### LINUX

Kernel Hackers Manual January 2008
napi_enable
9
2.6.24-rc6-git8

#### napi_enable

enable NAPI scheduling

##### Synopsis

       void napi_enable
       struct napi_struct * n

##### Arguments

`n`

  napi context

##### Description

Resume NAPI from being scheduled on this context. Must be paired with napi_disable.

#### LINUX

Kernel Hackers Manual January 2008
napi_synchronize
9
2.6.24-rc6-git8

#### napi_synchronize

wait until NAPI is not running

##### Synopsis

       void napi_synchronize
       const struct napi_struct * n

##### Arguments

`n`

  napi context

##### Description

Wait until NAPI is done being scheduled on this context. Waits till any outstanding processing completes but does not disable future activations.

#### LINUX

Kernel Hackers Manual January 2008
netdev_priv
9
2.6.24-rc6-git8

#### netdev_priv

access network device private data

##### Synopsis

       void * netdev_priv
       const struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Get network device private data

#### LINUX

Kernel Hackers Manual January 2008
netif_napi_add
9
2.6.24-rc6-git8

#### netif_napi_add

initialize a napi context

##### Synopsis

       void netif_napi_add
       struct net_device * dev
       struct napi_struct * napi
       int (*poll)
         struct napi_struct *, int
       int weight

##### Arguments

`dev`

  network device

`napi`

  napi context

`poll`

  polling function

`weight`

  default weight

##### Description

`netif_napi_add` must be used to initialize a napi context prior to calling *any* of the other napi related functions.

#### LINUX

Kernel Hackers Manual January 2008
netif_start_queue
9
2.6.24-rc6-git8

#### netif_start_queue

allow transmit

##### Synopsis

       void netif_start_queue
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Allow upper layers to call the device hard_start_xmit routine.

#### LINUX

Kernel Hackers Manual January 2008
netif_wake_queue
9
2.6.24-rc6-git8

#### netif_wake_queue

restart transmit

##### Synopsis

       void netif_wake_queue
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Allow upper layers to call the device hard_start_xmit routine. Used for flow control when transmit resources are available.

#### LINUX

Kernel Hackers Manual January 2008
netif_stop_queue
9
2.6.24-rc6-git8

#### netif_stop_queue

stop transmitted packets

##### Synopsis

       void netif_stop_queue
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Stop upper layers calling the device hard_start_xmit routine. Used for flow control when transmit resources are unavailable.

#### LINUX

Kernel Hackers Manual January 2008
netif_queue_stopped
9
2.6.24-rc6-git8

#### netif_queue_stopped

test if transmit queue is flowblocked

##### Synopsis

       int netif_queue_stopped
       const struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Test if transmit queue on device is currently unable to send.

#### LINUX

Kernel Hackers Manual January 2008
netif_running
9
2.6.24-rc6-git8

#### netif_running

test if up

##### Synopsis

       int netif_running
       const struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Test if the device has been brought up.

#### LINUX

Kernel Hackers Manual January 2008
netif_start_subqueue
9
2.6.24-rc6-git8

#### netif_start_subqueue

allow sending packets on subqueue

##### Synopsis

       void netif_start_subqueue
       struct net_device * dev
       u16 queue_index

##### Arguments

`dev`

  network device

`queue_index`

  sub queue index

##### Description

Start individual transmit queue of a device with multiple transmit queues.

#### LINUX

Kernel Hackers Manual January 2008
netif_stop_subqueue
9
2.6.24-rc6-git8

#### netif_stop_subqueue

stop sending packets on subqueue

##### Synopsis

       void netif_stop_subqueue
       struct net_device * dev
       u16 queue_index

##### Arguments

`dev`

  network device

`queue_index`

  sub queue index

##### Description

Stop individual transmit queue of a device with multiple transmit queues.

#### LINUX

Kernel Hackers Manual January 2008
__netif_subqueue_stopped
9
2.6.24-rc6-git8

#### __netif_subqueue_stopped

test status of subqueue

##### Synopsis

       int __netif_subqueue_stopped
       const struct net_device * dev
       u16 queue_index

##### Arguments

`dev`

  network device

`queue_index`

  sub queue index

##### Description

Check individual transmit queue of a device with multiple transmit queues.

#### LINUX

Kernel Hackers Manual January 2008
netif_wake_subqueue
9
2.6.24-rc6-git8

#### netif_wake_subqueue

allow sending packets on subqueue

##### Synopsis

       void netif_wake_subqueue
       struct net_device * dev
       u16 queue_index

##### Arguments

`dev`

  network device

`queue_index`

  sub queue index

##### Description

Resume individual transmit queue of a device with multiple transmit queues.

#### LINUX

Kernel Hackers Manual January 2008
netif_is_multiqueue
9
2.6.24-rc6-git8

#### netif_is_multiqueue

test if device has multiple transmit queues

##### Synopsis

       int netif_is_multiqueue
       const struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Check if device has multiple transmit queues Always falls if NETDEVICE_MULTIQUEUE is not configured

#### LINUX

Kernel Hackers Manual January 2008
dev_put
9
2.6.24-rc6-git8

#### dev_put

release reference to device

##### Synopsis

       void dev_put
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Release reference to device to allow it to be freed.

#### LINUX

Kernel Hackers Manual January 2008
dev_hold
9
2.6.24-rc6-git8

#### dev_hold

get reference to device

##### Synopsis

       void dev_hold
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Hold reference to device to keep it from being freed.

#### LINUX

Kernel Hackers Manual January 2008
netif_carrier_ok
9
2.6.24-rc6-git8

#### netif_carrier_ok

test if carrier present

##### Synopsis

       int netif_carrier_ok
       const struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Check if carrier is present on device

#### LINUX

Kernel Hackers Manual January 2008
netif_dormant_on
9
2.6.24-rc6-git8

#### netif_dormant_on

mark device as dormant.

##### Synopsis

       void netif_dormant_on
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Mark device as dormant (as per RFC2863).

The dormant state indicates that the relevant interface is not actually in a condition to pass packets (i.e., it is not 'up') but is in a pending state, waiting for some external event. For on- demand interfaces, this new state identifies the situation where the interface is waiting for events to place it in the up state.

#### LINUX

Kernel Hackers Manual January 2008
netif_dormant_off
9
2.6.24-rc6-git8

#### netif_dormant_off

set device as not dormant.

##### Synopsis

       void netif_dormant_off
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Device is not in dormant state.

#### LINUX

Kernel Hackers Manual January 2008
netif_dormant
9
2.6.24-rc6-git8

#### netif_dormant

test if carrier present

##### Synopsis

       int netif_dormant
       const struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Check if carrier is present on device

#### LINUX

Kernel Hackers Manual January 2008
netif_oper_up
9
2.6.24-rc6-git8

#### netif_oper_up

test if device is operational

##### Synopsis

       int netif_oper_up
       const struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Check if carrier is operational

#### LINUX

Kernel Hackers Manual January 2008
netif_device_present
9
2.6.24-rc6-git8

#### netif_device_present

is device available or removed

##### Synopsis

       int netif_device_present
       struct net_device * dev

##### Arguments

`dev`

  network device

##### Description

Check if device has not been removed from system.

#### LINUX

Kernel Hackers Manual January 2008
__netif_tx_lock
9
2.6.24-rc6-git8

#### __netif_tx_lock

grab network device transmit lock

##### Synopsis

       void __netif_tx_lock
       struct net_device * dev
       int cpu

##### Arguments

`dev`

  network device

`cpu`

  cpu number of lock owner

##### Description

Get network device transmit lock

### PHY Support

#### LINUX

Kernel Hackers Manual January 2008
phy_print_status
9
2.6.24-rc6-git8

#### phy_print_status

Convenience function to print out the current phy status

##### Synopsis

       void phy_print_status
       struct phy_device * phydev

##### Arguments

`phydev`

  the phy_device struct

#### LINUX

Kernel Hackers Manual January 2008
phy_read
9
2.6.24-rc6-git8

#### phy_read

Convenience function for reading a given PHY register

##### Synopsis

       int phy_read
       struct phy_device * phydev
       u16 regnum

##### Arguments

`phydev`

  the phy_device struct

`regnum`

  register number to read

##### NOTE

MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.

#### LINUX

Kernel Hackers Manual January 2008
phy_write
9
2.6.24-rc6-git8

#### phy_write

Convenience function for writing a given PHY register

##### Synopsis

       int phy_write
       struct phy_device * phydev
       u16 regnum
       u16 val

##### Arguments

`phydev`

  the phy_device struct

`regnum`

  register number to write

`val`

  value to write to `regnum`

##### NOTE

MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.

#### LINUX

Kernel Hackers Manual January 2008
phy_sanitize_settings
9
2.6.24-rc6-git8

#### phy_sanitize_settings

make sure the PHY is set to supported speed and duplex

##### Synopsis

       void phy_sanitize_settings
       struct phy_device * phydev

##### Arguments

`phydev`

  the target phy_device struct

##### Description

Make sure the PHY is set to supported speeds and duplexes. Drop down by one in this order: 1000/FULL, 1000/HALF, 100/FULL, 100/HALF, 10/FULL, 10/HALF.

#### LINUX

Kernel Hackers Manual January 2008
phy_ethtool_sset
9
2.6.24-rc6-git8

#### phy_ethtool_sset

generic ethtool sset function, handles all the details

##### Synopsis

       int phy_ethtool_sset
       struct phy_device * phydev
       struct ethtool_cmd * cmd

##### Arguments

`phydev`

  target phy_device struct

`cmd`

  ethtool_cmd

##### A few notes about parameter checking

- We don't set port or transceiver, so we don't care what they were set to. - `phy_start_aneg` will make sure forced settings are sane, and choose the next best ones from the ones selected, so we don't care if ethtool tries to give us bad values.

#### LINUX

Kernel Hackers Manual January 2008
phy_mii_ioctl
9
2.6.24-rc6-git8

#### phy_mii_ioctl

generic PHY MII ioctl interface

##### Synopsis

       int phy_mii_ioctl
       struct phy_device * phydev
       struct mii_ioctl_data * mii_data
       int cmd

##### Arguments

`phydev`

  the phy_device struct

`mii_data`

  MII ioctl data

`cmd`

  ioctl cmd to execute

##### Description

Note that this function is currently incompatible with the PHYCONTROL layer. It changes registers without regard to current state. Use at own risk.

#### LINUX

Kernel Hackers Manual January 2008
phy_start_aneg
9
2.6.24-rc6-git8

#### phy_start_aneg

start auto-negotiation for this PHY device

##### Synopsis

       int phy_start_aneg
       struct phy_device * phydev

##### Arguments

`phydev`

  the phy_device struct

##### Description

Sanitizes the settings (if we're not autonegotiating them), and then calls the driver's config_aneg function. If the PHYCONTROL Layer is operating, we change the state to reflect the beginning of Auto-negotiation or forcing.

#### LINUX

Kernel Hackers Manual January 2008
phy_enable_interrupts
9
2.6.24-rc6-git8

#### phy_enable_interrupts

Enable the interrupts from the PHY side

##### Synopsis

       int phy_enable_interrupts
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

#### LINUX

Kernel Hackers Manual January 2008
phy_disable_interrupts
9
2.6.24-rc6-git8

#### phy_disable_interrupts

Disable the PHY interrupts from the PHY side

##### Synopsis

       int phy_disable_interrupts
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

#### LINUX

Kernel Hackers Manual January 2008
phy_start_interrupts
9
2.6.24-rc6-git8

#### phy_start_interrupts

request and enable interrupts for a PHY device

##### Synopsis

       int phy_start_interrupts
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

##### Description

Request the interrupt for the given PHY. If this fails, then we set irq to PHY_POLL. Otherwise, we enable the interrupts in the PHY. This should only be called with a valid IRQ number. Returns 0 on success or < 0 on error.

#### LINUX

Kernel Hackers Manual January 2008
phy_stop_interrupts
9
2.6.24-rc6-git8

#### phy_stop_interrupts

disable interrupts from a PHY device

##### Synopsis

       int phy_stop_interrupts
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

#### LINUX

Kernel Hackers Manual January 2008
phy_stop
9
2.6.24-rc6-git8

#### phy_stop

Bring down the PHY link, and stop checking the status

##### Synopsis

       void phy_stop
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

#### LINUX

Kernel Hackers Manual January 2008
phy_start
9
2.6.24-rc6-git8

#### phy_start

start or restart a PHY device

##### Synopsis

       void phy_start
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

##### Description

Indicates the attached device's readiness to handle PHY-related work. Used during startup to start the PHY, and after a call to `phy_stop` to resume operation. Also used to indicate the MDIO bus has cleared an error condition.

#### LINUX

Kernel Hackers Manual January 2008
phy_clear_interrupt
9
2.6.24-rc6-git8

#### phy_clear_interrupt

Ack the phy device's interrupt

##### Synopsis

       int phy_clear_interrupt
       struct phy_device * phydev

##### Arguments

`phydev`

  the phy_device struct

##### Description

If the `phydev` driver has an ack_interrupt function, call it to ack and clear the phy device's interrupt.

Returns 0 on success on < 0 on error.

#### LINUX

Kernel Hackers Manual January 2008
phy_config_interrupt
9
2.6.24-rc6-git8

#### phy_config_interrupt

configure the PHY device for the requested interrupts

##### Synopsis

       int phy_config_interrupt
       struct phy_device * phydev
       u32 interrupts

##### Arguments

`phydev`

  the phy_device struct

`interrupts`

  interrupt flags to configure for this `phydev`

##### Description

Returns 0 on success on < 0 on error.

#### LINUX

Kernel Hackers Manual January 2008
phy_aneg_done
9
2.6.24-rc6-git8

#### phy_aneg_done

return auto-negotiation status

##### Synopsis

       int phy_aneg_done
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

##### Description

Reads the status register and returns 0 either if auto-negotiation is incomplete, or if there was an error. Returns BMSR_ANEGCOMPLETE if auto-negotiation is done.

#### LINUX

Kernel Hackers Manual January 2008
phy_find_setting
9
2.6.24-rc6-git8

#### phy_find_setting

find a PHY settings array entry that matches speed & duplex

##### Synopsis

       int phy_find_setting
       int speed
       int duplex

##### Arguments

`speed`

  speed to match

`duplex`

  duplex to match

##### Description

Searches the settings array for the setting which matches the desired speed and duplex, and returns the index of that setting. Returns the index of the last setting if none of the others match.

#### LINUX

Kernel Hackers Manual January 2008
phy_find_valid
9
2.6.24-rc6-git8

#### phy_find_valid

find a PHY setting that matches the requested features mask

##### Synopsis

       int phy_find_valid
       int idx
       u32 features

##### Arguments

`idx`

  The first index in settings[] to search

`features`

  A mask of the valid settings

##### Description

Returns the index of the first valid setting less than or equal to the one pointed to by idx, as determined by the mask in features. Returns the index of the last setting if nothing else matches.

#### LINUX

Kernel Hackers Manual January 2008
phy_start_machine
9
2.6.24-rc6-git8

#### phy_start_machine

start PHY state machine tracking

##### Synopsis

       void phy_start_machine
       struct phy_device * phydev
       void (*handler)
         struct net_device *

##### Arguments

`phydev`

  the phy_device struct

`handler`

  callback function for state change notifications

##### Description

The PHY infrastructure can run a state machine which tracks whether the PHY is starting up, negotiating, etc. This function starts the timer which tracks the state of the PHY. If you want to be notified when the state changes, pass in the callback `handler`, otherwise, pass NULL. If you want to maintain your own state machine, do not call this function.

#### LINUX

Kernel Hackers Manual January 2008
phy_stop_machine
9
2.6.24-rc6-git8

#### phy_stop_machine

stop the PHY state machine tracking

##### Synopsis

       void phy_stop_machine
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

##### Description

Stops the state machine timer, sets the state to UP (unless it wasn't up yet). This function must be called BEFORE phy_detach.

#### LINUX

Kernel Hackers Manual January 2008
phy_force_reduction
9
2.6.24-rc6-git8

#### phy_force_reduction

reduce PHY speed/duplex settings by one step

##### Synopsis

       void phy_force_reduction
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

##### Description

Reduces the speed/duplex settings by one notch, in this order-- 1000/FULL, 1000/HALF, 100/FULL, 100/HALF, 10/FULL, 10/HALF. The function bottoms out at 10/HALF.

#### LINUX

Kernel Hackers Manual January 2008
phy_error
9
2.6.24-rc6-git8

#### phy_error

enter HALTED state for this PHY device

##### Synopsis

       void phy_error
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

##### Description

Moves the PHY to the HALTED state in response to a read or write error, and tells the controller the link is down. Must not be called from interrupt context, or while the phydev->lock is held.

#### LINUX

Kernel Hackers Manual January 2008
phy_interrupt
9
2.6.24-rc6-git8

#### phy_interrupt

PHY interrupt handler

##### Synopsis

       irqreturn_t phy_interrupt
       int irq
       void * phy_dat

##### Arguments

`irq`

  interrupt line

`phy_dat`

  phy_device pointer

##### Description

When a PHY interrupt occurs, the handler disables interrupts, and schedules a work task to clear the interrupt.

#### LINUX

Kernel Hackers Manual January 2008
phy_change
9
2.6.24-rc6-git8

#### phy_change

Scheduled by the phy_interrupt/timer to handle PHY changes

##### Synopsis

       void phy_change
       struct work_struct * work

##### Arguments

`work`

  work_struct that describes the work to be done

#### LINUX

Kernel Hackers Manual January 2008
phy_connect
9
2.6.24-rc6-git8

#### phy_connect

connect an ethernet device to a PHY device

##### Synopsis

       struct phy_device * phy_connect
       struct net_device * dev
       const char * phy_id
       void (*handler)
         struct net_device *
       u32 flags
       phy_interface_t interface

##### Arguments

`dev`

  the network device to connect

`phy_id`

  the PHY device to connect

`handler`

  callback function for state change notifications

`flags`

  PHY device's dev_flags

`interface`

  PHY device's interface

##### Description

Convenience function for connecting ethernet devices to PHY devices. The default behavior is for the PHY infrastructure to handle everything, and only notify the connected driver when the link status changes. If you don't want, or can't use the provided functionality, you may choose to call only the subset of functions which provide the desired functionality.

#### LINUX

Kernel Hackers Manual January 2008
phy_disconnect
9
2.6.24-rc6-git8

#### phy_disconnect

disable interrupts, stop state machine, and detach a PHY device

##### Synopsis

       void phy_disconnect
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

#### LINUX

Kernel Hackers Manual January 2008
phy_attach
9
2.6.24-rc6-git8

#### phy_attach

attach a network device to a particular PHY device

##### Synopsis

       struct phy_device * phy_attach
       struct net_device * dev
       const char * phy_id
       u32 flags
       phy_interface_t interface

##### Arguments

`dev`

  network device to attach

`phy_id`

  PHY device to attach

`flags`

  PHY device's dev_flags

`interface`

  PHY device's interface

##### Description

Called by drivers to attach to a particular PHY device. The phy_device is found, and properly hooked up to the phy_driver. If no driver is attached, then the genphy_driver is used. The phy_device is given a ptr to the attaching device, and given a callback for link status change. The phy_device is returned to the attaching driver.

#### LINUX

Kernel Hackers Manual January 2008
phy_detach
9
2.6.24-rc6-git8

#### phy_detach

detach a PHY device from its network device

##### Synopsis

       void phy_detach
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

#### LINUX

Kernel Hackers Manual January 2008
genphy_config_advert
9
2.6.24-rc6-git8

#### genphy_config_advert

sanitize and advertise auto-negotation parameters

##### Synopsis

       int genphy_config_advert
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

##### Description

Writes MII_ADVERTISE with the appropriate values, after sanitizing the values to make sure we only advertise what is supported.

#### LINUX

Kernel Hackers Manual January 2008
genphy_config_aneg
9
2.6.24-rc6-git8

#### genphy_config_aneg

restart auto-negotiation or write BMCR

##### Synopsis

       int genphy_config_aneg
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

##### Description

If auto-negotiation is enabled, we configure the advertising, and then restart auto-negotiation. If it is not enabled, then we write the BMCR.

#### LINUX

Kernel Hackers Manual January 2008
genphy_update_link
9
2.6.24-rc6-git8

#### genphy_update_link

update link status in `phydev`

##### Synopsis

       int genphy_update_link
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

##### Description

Update the value in phydev->link to reflect the current link value. In order to do this, we need to read the status register twice, keeping the second value.

#### LINUX

Kernel Hackers Manual January 2008
genphy_read_status
9
2.6.24-rc6-git8

#### genphy_read_status

check the link status and update current link state

##### Synopsis

       int genphy_read_status
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

##### Description

Check the link, then figure out the current state by comparing what we advertise with what the link partner advertises. Start by checking the gigabit possibilities, then move on to 10/100.

#### LINUX

Kernel Hackers Manual January 2008
phy_driver_register
9
2.6.24-rc6-git8

#### phy_driver_register

register a phy_driver with the PHY layer

##### Synopsis

       int phy_driver_register
       struct phy_driver * new_driver

##### Arguments

`new_driver`

  new phy_driver to register

#### LINUX

Kernel Hackers Manual January 2008
get_phy_device
9
2.6.24-rc6-git8

#### get_phy_device

reads the specified PHY device and returns its `phy_device` struct

##### Synopsis

       struct phy_device * get_phy_device
       struct mii_bus * bus
       int addr

##### Arguments

`bus`

  the target MII bus

`addr`

  PHY address on the MII bus

##### Description

Reads the ID registers of the PHY at `addr` on the `bus`, then allocates and returns the phy_device to represent it.

#### LINUX

Kernel Hackers Manual January 2008
phy_prepare_link
9
2.6.24-rc6-git8

#### phy_prepare_link

prepares the PHY layer to monitor link status

##### Synopsis

       void phy_prepare_link
       struct phy_device * phydev
       void (*handler)
         struct net_device *

##### Arguments

`phydev`

  target phy_device struct

`handler`

  callback function for link status change notifications

##### Description

Tells the PHY infrastructure to handle the gory details on monitoring link status (whether through polling or an interrupt), and to call back to the connected device driver when the link status changes. If you want to monitor your own link state, don't call this function.

#### LINUX

Kernel Hackers Manual January 2008
genphy_setup_forced
9
2.6.24-rc6-git8

#### genphy_setup_forced

configures/forces speed/duplex from `phydev`

##### Synopsis

       int genphy_setup_forced
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

##### Description

Configures MII_BMCR to force speed/duplex to the values in phydev. Assumes that the values are valid. Please see `phy_sanitize_settings`.

#### LINUX

Kernel Hackers Manual January 2008
genphy_restart_aneg
9
2.6.24-rc6-git8

#### genphy_restart_aneg

Enable and Restart Autonegotiation

##### Synopsis

       int genphy_restart_aneg
       struct phy_device * phydev

##### Arguments

`phydev`

  target phy_device struct

#### LINUX

Kernel Hackers Manual January 2008
phy_probe
9
2.6.24-rc6-git8

#### phy_probe

probe and init a PHY device

##### Synopsis

       int phy_probe
       struct device * dev

##### Arguments

`dev`

  device to probe and init

##### Description

Take care of setting up the phy_device structure, set the state to READY (the driver's init function should set it to STARTING if needed).

#### LINUX

Kernel Hackers Manual January 2008
mdiobus_register
9
2.6.24-rc6-git8

#### mdiobus_register

bring up all the PHYs on a given bus and attach them to bus

##### Synopsis

       int mdiobus_register
       struct mii_bus * bus

##### Arguments

`bus`

  target mii_bus

##### Description

Called by a bus driver to bring up all the PHYs on a given bus, and attach them to the bus.

Returns 0 on success or < 0 on error.

#### LINUX

Kernel Hackers Manual January 2008
mdio_bus_match
9
2.6.24-rc6-git8

#### mdio_bus_match

determine if given PHY driver supports the given PHY device

##### Synopsis

       int mdio_bus_match
       struct device * dev
       struct device_driver * drv

##### Arguments

`dev`

  target PHY device

`drv`

  given PHY driver

##### Description

Given a PHY device, and a PHY driver, return 1 if the driver supports the device. Otherwise, return 0.

### Synchronous PPP

#### LINUX

Kernel Hackers Manual January 2008
sppp_close
9
2.6.24-rc6-git8

#### sppp_close

close down a synchronous PPP or Cisco HDLC link

##### Synopsis

       int sppp_close
       struct net_device * dev

##### Arguments

`dev`

  The network device to drop the link of

##### Description

This drops the logical interface to the channel. It is not done politely as we assume we will also be dropping DTR. Any timeouts are killed.

#### LINUX

Kernel Hackers Manual January 2008
sppp_open
9
2.6.24-rc6-git8

#### sppp_open

open a synchronous PPP or Cisco HDLC link

##### Synopsis

       int sppp_open
       struct net_device * dev

##### Arguments

`dev`

  Network device to activate

##### Description

Close down any existing synchronous session and commence from scratch. In the PPP case this means negotiating LCP/IPCP and friends, while for Cisco HDLC we simply need to start sending keepalives

#### LINUX

Kernel Hackers Manual January 2008
sppp_reopen
9
2.6.24-rc6-git8

#### sppp_reopen

notify of physical link loss

##### Synopsis

       int sppp_reopen
       struct net_device * dev

##### Arguments

`dev`

  Device that lost the link

##### Description

This function informs the synchronous protocol code that the underlying link died (for example a carrier drop on X.21)

We increment the magic numbers to ensure that if the other end failed to notice we will correctly start a new session. It happens do to the nature of telco circuits is that you can lose carrier on one endonly.

Having done this we go back to negotiating. This function may be called from an interrupt context.

#### LINUX

Kernel Hackers Manual January 2008
sppp_do_ioctl
9
2.6.24-rc6-git8

#### sppp_do_ioctl

Ioctl handler for ppp/hdlc

##### Synopsis

       int sppp_do_ioctl
       struct net_device * dev
       struct ifreq * ifr
       int cmd

##### Arguments

`dev`

  Device subject to ioctl

`ifr`

  Interface request block from the user

`cmd`

  Command that is being issued

##### Description

This function handles the ioctls that may be issued by the user to control the settings of a PPP/HDLC link. It does both busy and security checks. This function is intended to be wrapped by callers who wish to add additional ioctl calls of their own.

#### LINUX

Kernel Hackers Manual January 2008
sppp_attach
9
2.6.24-rc6-git8

#### sppp_attach

attach synchronous PPP/HDLC to a device

##### Synopsis

       void sppp_attach
       struct ppp_device * pd

##### Arguments

`pd`

  PPP device to initialise

##### Description

This initialises the PPP/HDLC support on an interface. At the time of calling the dev element must point to the network device that this interface is attached to. The interface should not yet be registered.

#### LINUX

Kernel Hackers Manual January 2008
sppp_detach
9
2.6.24-rc6-git8

#### sppp_detach

release PPP resources from a device

##### Synopsis

       void sppp_detach
       struct net_device * dev

##### Arguments

`dev`

  Network device to release

##### Description

Stop and free up any PPP/HDLC resources used by this interface. This must be called before the device is freed.

## Module Support

### Module Loading

#### LINUX

Kernel Hackers Manual January 2008
request_module
9
2.6.24-rc6-git8

#### request_module

try to load a kernel module

##### Synopsis

       int request_module
       const char * fmt
        ...

##### Arguments

`fmt`

  printf style format string for the name of the module

`...`

  variable arguments

##### Description

Load a module using the user mode module loader. The function returns zero on success or a negative errno code on failure. Note that a successful module load does not mean the module did not then unload and exit on an error of its own. Callers must check that the service they requested is now available not blindly invoke it.

If module auto-loading support is disabled then this function becomes a no-operation.

#### LINUX

Kernel Hackers Manual January 2008
call_usermodehelper_setup
9
2.6.24-rc6-git8

#### call_usermodehelper_setup

prepare to call a usermode helper

##### Synopsis

       struct subprocess_info * call_usermodehelper_setup
       char * path
       char ** argv
       char ** envp

##### Arguments

`path`

  path to usermode executable

`argv`

  arg vector for process

`envp`

  environment for process

##### Description

Returns either `NULL` on allocation failure, or a subprocess_info structure. This should be passed to call_usermodehelper_exec to exec the process and free the structure.

#### LINUX

Kernel Hackers Manual January 2008
call_usermodehelper_setkeys
9
2.6.24-rc6-git8

#### call_usermodehelper_setkeys

set the session keys for usermode helper

##### Synopsis

       void call_usermodehelper_setkeys
       struct subprocess_info * info
       struct key * session_keyring

##### Arguments

`info`

  a subprocess_info returned by call_usermodehelper_setup

`session_keyring`

  the session keyring for the process

#### LINUX

Kernel Hackers Manual January 2008
call_usermodehelper_setcleanup
9
2.6.24-rc6-git8

#### call_usermodehelper_setcleanup

set a cleanup function

##### Synopsis

       void call_usermodehelper_setcleanup
       struct subprocess_info * info
       void (*cleanup)
         char **argv, char **envp

##### Arguments

`info`

  a subprocess_info returned by call_usermodehelper_setup

`cleanup`

  a cleanup function

##### Description

The cleanup function is just befor ethe subprocess_info is about to be freed. This can be used for freeing the argv and envp. The Function must be runnable in either a process context or the context in which call_usermodehelper_exec is called.

#### LINUX

Kernel Hackers Manual January 2008
call_usermodehelper_stdinpipe
9
2.6.24-rc6-git8

#### call_usermodehelper_stdinpipe

set up a pipe to be used for stdin

##### Synopsis

       int call_usermodehelper_stdinpipe
       struct subprocess_info * sub_info
       struct file ** filp

##### Arguments

`sub_info`

  a subprocess_info returned by call_usermodehelper_setup

`filp`

  set to the write-end of a pipe

##### Description

This constructs a pipe, and sets the read end to be the stdin of the subprocess, and returns the write-end in *`filp`.

#### LINUX

Kernel Hackers Manual January 2008
call_usermodehelper_exec
9
2.6.24-rc6-git8

#### call_usermodehelper_exec

start a usermode application

##### Synopsis

       int call_usermodehelper_exec
       struct subprocess_info * sub_info
       enum umh_wait wait

##### Arguments

`sub_info`

  information about the subprocessa

`wait`

  wait for the application to finish and return status. when -1 don't wait at all, but you get no useful error back when the program couldn't be exec'ed. This makes it safe to call from interrupt context.

##### Description

Runs a user-space application. The application is started asynchronously if wait is not set, and runs as a child of keventd. (ie. it runs with full root capabilities).

#### LINUX

Kernel Hackers Manual January 2008
call_usermodehelper_pipe
9
2.6.24-rc6-git8

#### call_usermodehelper_pipe

call a usermode helper process with a pipe stdin

##### Synopsis

       int call_usermodehelper_pipe
       char * path
       char ** argv
       char ** envp
       struct file ** filp

##### Arguments

`path`

  path to usermode executable

`argv`

  arg vector for process

`envp`

  environment for process

`filp`

  set to the write-end of a pipe

##### Description

This is a simple wrapper which executes a usermode-helper function with a pipe as stdin. It is implemented entirely in terms of lower-level call_usermodehelper_* functions.

### Inter Module support

Refer to the file kernel/module.c for more information.

## Hardware Interfaces

### Interrupt Handling

#### LINUX

Kernel Hackers Manual January 2008
synchronize_irq
9
2.6.24-rc6-git8

#### synchronize_irq

wait for pending IRQ handlers (on other CPUs)

##### Synopsis

       void synchronize_irq
       unsigned int irq

##### Arguments

`irq`

  interrupt number to wait for

##### Description

This function waits for any pending IRQ handlers for this interrupt to complete before returning. If you use this function while holding a resource the IRQ handler may need you will deadlock.

This function may be called - with care - from IRQ context.

#### LINUX

Kernel Hackers Manual January 2008
disable_irq_nosync
9
2.6.24-rc6-git8

#### disable_irq_nosync

disable an irq without waiting

##### Synopsis

       void disable_irq_nosync
       unsigned int irq

##### Arguments

`irq`

  Interrupt to disable

##### Description

Disable the selected interrupt line. Disables and Enables are nested. Unlike `disable_irq`, this function does not ensure existing instances of the IRQ handler have completed before returning.

This function may be called from IRQ context.

#### LINUX

Kernel Hackers Manual January 2008
disable_irq
9
2.6.24-rc6-git8

#### disable_irq

disable an irq and wait for completion

##### Synopsis

       void disable_irq
       unsigned int irq

##### Arguments

`irq`

  Interrupt to disable

##### Description

Disable the selected interrupt line. Enables and Disables are nested. This function waits for any pending IRQ handlers for this interrupt to complete before returning. If you use this function while holding a resource the IRQ handler may need you will deadlock.

This function may be called - with care - from IRQ context.

#### LINUX

Kernel Hackers Manual January 2008
enable_irq
9
2.6.24-rc6-git8

#### enable_irq

enable handling of an irq

##### Synopsis

       void enable_irq
       unsigned int irq

##### Arguments

`irq`

  Interrupt to enable

##### Description

Undoes the effect of one call to `disable_irq`. If this matches the last disable, processing of interrupts on this IRQ line is re-enabled.

This function may be called from IRQ context.

#### LINUX

Kernel Hackers Manual January 2008
set_irq_wake
9
2.6.24-rc6-git8

#### set_irq_wake

control irq power management wakeup

##### Synopsis

       int set_irq_wake
       unsigned int irq
       unsigned int on

##### Arguments

`irq`

  interrupt to control

`on`

  enable/disable power management wakeup

##### Description

Enable/disable power management wakeup mode, which is disabled by default. Enables and disables must match, just as they match for non-wakeup mode support.

Wakeup mode lets this IRQ wake the system from sleep states like suspend to RAM.

#### LINUX

Kernel Hackers Manual January 2008
free_irq
9
2.6.24-rc6-git8

#### free_irq

free an interrupt

##### Synopsis

       void free_irq
       unsigned int irq
       void * dev_id

##### Arguments

`irq`

  Interrupt line to free

`dev_id`

  Device identity to free

##### Description

Remove an interrupt handler. The handler is removed and if the interrupt line is no longer in use by any driver it is disabled. On a shared IRQ the caller must ensure the interrupt is disabled on the card it drives before calling this function. The function does not return until any executing interrupts for this IRQ have completed.

This function must not be called from interrupt context.

#### LINUX

Kernel Hackers Manual January 2008
request_irq
9
2.6.24-rc6-git8

#### request_irq

allocate an interrupt line

##### Synopsis

       int request_irq
       unsigned int irq
       irq_handler_t handler
       unsigned long irqflags
       const char * devname
       void * dev_id

##### Arguments

`irq`

  Interrupt line to allocate

`handler`

  Function to be called when the IRQ occurs

`irqflags`

  Interrupt type flags

`devname`

  An ascii name for the claiming device

`dev_id`

  A cookie passed back to the handler function

##### Description

This call allocates interrupt resources and enables the interrupt line and IRQ handling. From the point this call is made your handler function may be invoked. Since your handler function must clear any interrupt the board raises, you must take care both to initialise your hardware and to set up the interrupt handler in the right order.

Dev_id must be globally unique. Normally the address of the device data structure is used as the cookie. Since the handler receives this value it makes sense to use it.

If your interrupt is shared you must pass a non NULL dev_id as this is required when freeing the interrupt.

##### Flags

IRQF_SHARED Interrupt is shared IRQF_DISABLED Disable local interrupts while processing IRQF_SAMPLE_RANDOM The interrupt can be used for entropy

### DMA Channels

#### LINUX

Kernel Hackers Manual January 2008
request_dma
9
2.6.24-rc6-git8

#### request_dma

request and reserve a system DMA channel

##### Synopsis

       int request_dma
       unsigned int dmanr
       const char * device_id

##### Arguments

`dmanr`

  DMA channel number

`device_id`

  reserving device ID string, used in /proc/dma

#### LINUX

Kernel Hackers Manual January 2008
free_dma
9
2.6.24-rc6-git8

#### free_dma

free a reserved system DMA channel

##### Synopsis

       void free_dma
       unsigned int dmanr

##### Arguments

`dmanr`

  DMA channel number

### Resources Management

#### LINUX

Kernel Hackers Manual January 2008
insert_resource
9
2.6.24-rc6-git8

#### insert_resource

Inserts a resource in the resource tree

##### Synopsis

       int insert_resource
       struct resource * parent
       struct resource * new

##### Arguments

`parent`

  parent of the new resource

`new`

  new resource to insert

##### Description

Returns 0 on success, -EBUSY if the resource can't be inserted.

This function is equivalent to request_resource when no conflict happens. If a conflict happens, and the conflicting resources entirely fit within the range of the new resource, then the new resource is inserted and the conflicting resources become children of the new resource.

#### LINUX

Kernel Hackers Manual January 2008
request_resource
9
2.6.24-rc6-git8

#### request_resource

request and reserve an I/O or memory resource

##### Synopsis

       int request_resource
       struct resource * root
       struct resource * new

##### Arguments

`root`

  root resource descriptor

`new`

  resource descriptor desired by caller

##### Description

Returns 0 for success, negative error code on error.

#### LINUX

Kernel Hackers Manual January 2008
release_resource
9
2.6.24-rc6-git8

#### release_resource

release a previously reserved resource

##### Synopsis

       int release_resource
       struct resource * old

##### Arguments

`old`

  resource pointer

#### LINUX

Kernel Hackers Manual January 2008
allocate_resource
9
2.6.24-rc6-git8

#### allocate_resource

allocate empty slot in the resource tree given range & alignment

##### Synopsis

       int allocate_resource
       struct resource * root
       struct resource * new
       resource_size_t size
       resource_size_t min
       resource_size_t max
       resource_size_t align
       void (*alignf)
         void *, struct resource *, 				     resource_size_t, resource_size_t
       void * alignf_data

##### Arguments

`root`

  root resource descriptor

`new`

  resource descriptor desired by caller

`size`

  requested resource region size

`min`

  minimum size to allocate

`max`

  maximum size to allocate

`align`

  alignment requested, in bytes

`alignf`

  alignment function, optional, called if not NULL

`alignf_data`

  arbitrary data to pass to the `alignf` function

#### LINUX

Kernel Hackers Manual January 2008
adjust_resource
9
2.6.24-rc6-git8

#### adjust_resource

modify a resource's start and size

##### Synopsis

       int adjust_resource
       struct resource * res
       resource_size_t start
       resource_size_t size

##### Arguments

`res`

  resource to modify

`start`

  new start value

`size`

  new size

##### Description

Given an existing resource, change its start and size to match the arguments. Returns 0 on success, -EBUSY if it can't fit. Existing children of the resource are assumed to be immutable.

#### LINUX

Kernel Hackers Manual January 2008
__request_region
9
2.6.24-rc6-git8

#### __request_region

create a new busy resource region

##### Synopsis

       struct resource * __request_region
       struct resource * parent
       resource_size_t start
       resource_size_t n
       const char * name

##### Arguments

`parent`

  parent resource descriptor

`start`

  resource start address

`n`

  resource region size

`name`

  reserving caller's ID string

#### LINUX

Kernel Hackers Manual January 2008
__check_region
9
2.6.24-rc6-git8

#### __check_region

check if a resource region is busy or free

##### Synopsis

       int __check_region
       struct resource * parent
       resource_size_t start
       resource_size_t n

##### Arguments

`parent`

  parent resource descriptor

`start`

  resource start address

`n`

  resource region size

##### Description

Returns 0 if the region is free at the moment it is checked, returns `-EBUSY` if the region is busy.

##### NOTE

This function is deprecated because its use is racy. Even if it returns 0, a subsequent call to `request_region` may fail because another driver etc. just allocated the region. Do NOT use it. It will be removed from the kernel.

#### LINUX

Kernel Hackers Manual January 2008
__release_region
9
2.6.24-rc6-git8

#### __release_region

release a previously reserved resource region

##### Synopsis

       void __release_region
       struct resource * parent
       resource_size_t start
       resource_size_t n

##### Arguments

`parent`

  parent resource descriptor

`start`

  resource start address

`n`

  resource region size

##### Description

The described resource region must match a currently busy region.

### MTRR Handling

#### LINUX

Kernel Hackers Manual January 2008
mtrr_add
9
2.6.24-rc6-git8

#### mtrr_add

Add a memory type region

##### Synopsis

       int mtrr_add
       unsigned long base
       unsigned long size
       unsigned int type
       char increment

##### Arguments

`base`

  Physical base address of region

`size`

  Physical size of region

`type`

  Type of MTRR desired

`increment`

  If this is true do usage counting on the region

##### Description

Memory type region registers control the caching on newer Intel and non Intel processors. This function allows drivers to request an MTRR is added. The details and hardware specifics of each processor's implementation are hidden from the caller, but nevertheless the caller should expect to need to provide a power of two size on an equivalent power of two boundary.

If the region cannot be added either because all regions are in use or the CPU cannot support it a negative value is returned. On success the register number for this entry is returned, but should be treated as a cookie only.

On a multiprocessor machine the changes are made to all processors. This is required on x86 by the Intel processors.

The available types are

`MTRR_TYPE_UNCACHABLE` - No caching

`MTRR_TYPE_WRBACK` - Write data back in bursts whenever

`MTRR_TYPE_WRCOMB` - Write data back soon but allow bursts

`MTRR_TYPE_WRTHROUGH` - Cache reads but not writes

##### BUGS

Needs a quiet flag for the cases where drivers do not mind failures and do not wish system log messages to be sent.

#### LINUX

Kernel Hackers Manual January 2008
mtrr_del
9
2.6.24-rc6-git8

#### mtrr_del

delete a memory type region

##### Synopsis

       int mtrr_del
       int reg
       unsigned long base
       unsigned long size

##### Arguments

`reg`

  Register returned by mtrr_add

`base`

  Physical base address

`size`

  Size of region

##### Description

If register is supplied then base and size are ignored. This is how drivers should call it.

Releases an MTRR region. If the usage count drops to zero the register is freed and the region returns to default state. On success the register is returned, on failure a negative error code.

### PCI Support Library

#### LINUX

Kernel Hackers Manual January 2008
pci_bus_max_busnr
9
2.6.24-rc6-git8

#### pci_bus_max_busnr

returns maximum PCI bus number of given bus' children

##### Synopsis

       unsigned char pci_bus_max_busnr
       struct pci_bus * bus

##### Arguments

`bus`

  pointer to PCI bus structure to search

##### Description

Given a PCI bus, returns the highest PCI bus number present in the set including the given PCI bus and its list of child PCI buses.

#### LINUX

Kernel Hackers Manual January 2008
pci_find_capability
9
2.6.24-rc6-git8

#### pci_find_capability

query for devices' capabilities

##### Synopsis

       int pci_find_capability
       struct pci_dev * dev
       int cap

##### Arguments

`dev`

  PCI device to query

`cap`

  capability code

##### Description

Tell if a device supports a given PCI capability. Returns the address of the requested capability structure within the device's PCI configuration space or 0 in case the device does not support it. Possible values for `cap`:

`PCI_CAP_ID_PM` Power Management `PCI_CAP_ID_AGP` Accelerated Graphics Port `PCI_CAP_ID_VPD` Vital Product Data `PCI_CAP_ID_SLOTID` Slot Identification `PCI_CAP_ID_MSI` Message Signalled Interrupts `PCI_CAP_ID_CHSWP` CompactPCI HotSwap `PCI_CAP_ID_PCIX` PCI-X `PCI_CAP_ID_EXP` PCI Express

#### LINUX

Kernel Hackers Manual January 2008
pci_bus_find_capability
9
2.6.24-rc6-git8

#### pci_bus_find_capability

query for devices' capabilities

##### Synopsis

       int pci_bus_find_capability
       struct pci_bus * bus
       unsigned int devfn
       int cap

##### Arguments

`bus`

  the PCI bus to query

`devfn`

  PCI device to query

`cap`

  capability code

##### Description

Like `pci_find_capability` but works for pci devices that do not have a pci_dev structure set up yet.

Returns the address of the requested capability structure within the device's PCI configuration space or 0 in case the device does not support it.

#### LINUX

Kernel Hackers Manual January 2008
pci_find_ext_capability
9
2.6.24-rc6-git8

#### pci_find_ext_capability

Find an extended capability

##### Synopsis

       int pci_find_ext_capability
       struct pci_dev * dev
       int cap

##### Arguments

`dev`

  PCI device to query

`cap`

  capability code

##### Description

Returns the address of the requested extended capability structure within the device's PCI configuration space or 0 if the device does not support it. Possible values for `cap`:

`PCI_EXT_CAP_ID_ERR` Advanced Error Reporting `PCI_EXT_CAP_ID_VC` Virtual Channel `PCI_EXT_CAP_ID_DSN` Device Serial Number `PCI_EXT_CAP_ID_PWR` Power Budgeting

#### LINUX

Kernel Hackers Manual January 2008
pci_find_next_ht_capability
9
2.6.24-rc6-git8

#### pci_find_next_ht_capability

query a device's Hypertransport capabilities

##### Synopsis

       int pci_find_next_ht_capability
       struct pci_dev * dev
       int pos
       int ht_cap

##### Arguments

`dev`

  PCI device to query

`pos`

  Position from which to continue searching

`ht_cap`

  Hypertransport capability code

##### Description

To be used in conjunction with `pci_find_ht_capability` to search for all capabilities matching `ht_cap`. `pos` should always be a value returned from `pci_find_ht_capability`.

NB. To be 100% safe against broken PCI devices, the caller should take steps to avoid an infinite loop.

#### LINUX

Kernel Hackers Manual January 2008
pci_find_ht_capability
9
2.6.24-rc6-git8

#### pci_find_ht_capability

query a device's Hypertransport capabilities

##### Synopsis

       int pci_find_ht_capability
       struct pci_dev * dev
       int ht_cap

##### Arguments

`dev`

  PCI device to query

`ht_cap`

  Hypertransport capability code

##### Description

Tell if a device supports a given Hypertransport capability. Returns an address within the device's PCI configuration space or 0 in case the device does not support the request capability. The address points to the PCI capability, of type PCI_CAP_ID_HT, which has a Hypertransport capability matching `ht_cap`.

#### LINUX

Kernel Hackers Manual January 2008
pci_find_parent_resource
9
2.6.24-rc6-git8

#### pci_find_parent_resource

return resource region of parent bus of given region

##### Synopsis

       struct resource * pci_find_parent_resource
       const struct pci_dev * dev
       struct resource * res

##### Arguments

`dev`

  PCI device structure contains resources to be searched

`res`

  child resource record for which parent is sought

##### Description

For given resource region of given device, return the resource region of parent bus the given region is contained in or where it should be allocated from.

#### LINUX

Kernel Hackers Manual January 2008
pci_restore_bars
9
2.6.24-rc6-git8

#### pci_restore_bars

restore a devices BAR values (e.g. after wake-up)

##### Synopsis

       void pci_restore_bars
       struct pci_dev * dev

##### Arguments

`dev`

  PCI device to have its BARs restored

##### Description

Restore the BAR values for a given device, so as to make it accessible by its driver.

#### LINUX

Kernel Hackers Manual January 2008
pci_set_power_state
9
2.6.24-rc6-git8

#### pci_set_power_state

Set the power state of a PCI device

##### Synopsis

       int pci_set_power_state
       struct pci_dev * dev
       pci_power_t state

##### Arguments

`dev`

  PCI device to be suspended

`state`

  PCI power state (D0, D1, D2, D3hot, D3cold) we're entering

##### Description

Transition a device to a new power state, using the Power Management Capabilities in the device's config space.

##### RETURN VALUE

-EINVAL if trying to enter a lower state than we're already in. 0 if we're already in the requested state. -EIO if device does not support PCI PM. 0 if we can successfully change the power state.

#### LINUX

Kernel Hackers Manual January 2008
pci_choose_state
9
2.6.24-rc6-git8

#### pci_choose_state

Choose the power state of a PCI device

##### Synopsis

       pci_power_t pci_choose_state
       struct pci_dev * dev
       pm_message_t state

##### Arguments

`dev`

  PCI device to be suspended

`state`

  target sleep state for the whole system. This is the value that is passed to `suspend` function.

##### Description

Returns PCI power state suitable for given device and given system message.

#### LINUX

Kernel Hackers Manual January 2008
pci_save_state
9
2.6.24-rc6-git8

#### pci_save_state

save the PCI configuration space of a device before suspending

##### Synopsis

       int pci_save_state
       struct pci_dev * dev

##### Arguments

`dev`

  - PCI device that we're dealing with

#### LINUX

Kernel Hackers Manual January 2008
pci_restore_state
9
2.6.24-rc6-git8

#### pci_restore_state

Restore the saved state of a PCI device

##### Synopsis

       int pci_restore_state
       struct pci_dev * dev

##### Arguments

`dev`

  - PCI device that we're dealing with

#### LINUX

Kernel Hackers Manual January 2008
pci_reenable_device
9
2.6.24-rc6-git8

#### pci_reenable_device

Resume abandoned device

##### Synopsis

       int pci_reenable_device
       struct pci_dev * dev

##### Arguments

`dev`

  PCI device to be resumed

##### Description

Note this function is a backend of pci_default_resume and is not supposed to be called by normal code, write proper resume handler and use it instead.

#### LINUX

Kernel Hackers Manual January 2008
pci_enable_device_bars
9
2.6.24-rc6-git8

#### pci_enable_device_bars

Initialize some of a device for use

##### Synopsis

       int pci_enable_device_bars
       struct pci_dev * dev
       int bars

##### Arguments

`dev`

  PCI device to be initialized

`bars`

  bitmask of BAR's that must be configured

##### Description

Initialize device before it's used by a driver. Ask low-level code to enable selected I/O and memory resources. Wake up the device if it was suspended. Beware, this function can fail.

#### LINUX

Kernel Hackers Manual January 2008
pci_enable_device
9
2.6.24-rc6-git8

#### pci_enable_device

Initialize device before it's used by a driver.

##### Synopsis

       int pci_enable_device
       struct pci_dev * dev

##### Arguments

`dev`

  PCI device to be initialized

##### Description

Initialize device before it's used by a driver. Ask low-level code to enable I/O and memory. Wake up the device if it was suspended. Beware, this function can fail.

Note we don't actually enable the device many times if we call this function repeatedly (we just increment the count).

#### LINUX

Kernel Hackers Manual January 2008
pcim_enable_device
9
2.6.24-rc6-git8

#### pcim_enable_device

Managed `pci_enable_device`

##### Synopsis

       int pcim_enable_device
       struct pci_dev * pdev

##### Arguments

`pdev`

  PCI device to be initialized

##### Description

Managed `pci_enable_device`.

#### LINUX

Kernel Hackers Manual January 2008
pcim_pin_device
9
2.6.24-rc6-git8

#### pcim_pin_device

Pin managed PCI device

##### Synopsis

       void pcim_pin_device
       struct pci_dev * pdev

##### Arguments

`pdev`

  PCI device to pin

##### Description

Pin managed PCI device `pdev`. Pinned device won't be disabled on driver detach. `pdev` must have been enabled with `pcim_enable_device`.

#### LINUX

Kernel Hackers Manual January 2008
pci_disable_device
9
2.6.24-rc6-git8

#### pci_disable_device

Disable PCI device after use

##### Synopsis

       void pci_disable_device
       struct pci_dev * dev

##### Arguments

`dev`

  PCI device to be disabled

##### Description

Signal to the system that the PCI device is not in use by the system anymore. This only involves disabling PCI bus-mastering, if active.

Note we don't actually disable the device until all callers of `pci_device_enable` have called `pci_device_disable`.

#### LINUX

Kernel Hackers Manual January 2008
pci_set_pcie_reset_state
9
2.6.24-rc6-git8

#### pci_set_pcie_reset_state

set reset state for device dev

##### Synopsis

       int pci_set_pcie_reset_state
       struct pci_dev * dev
       enum pcie_reset_state state

##### Arguments

`dev`

  the PCI-E device reset

`state`

  Reset state to enter into

##### Description

Sets the PCI reset state for the device.

#### LINUX

Kernel Hackers Manual January 2008
pci_enable_wake
9
2.6.24-rc6-git8

#### pci_enable_wake

enable PCI device as wakeup event source

##### Synopsis

       int pci_enable_wake
       struct pci_dev * dev
       pci_power_t state
       int enable

##### Arguments

`dev`

  PCI device affected

`state`

  PCI state from which device will issue wakeup events

`enable`

  True to enable event generation; false to disable

##### Description

This enables the device as a wakeup event source, or disables it. When such events involves platform-specific hooks, those hooks are called automatically by this routine.

Devices with legacy power management (no standard PCI PM capabilities) always require such platform hooks. Depending on the platform, devices supporting the standard PCI PME# signal may require such platform hooks; they always update bits in config space to allow PME# generation.

-EIO is returned if the device can't ever be a wakeup event source. -EINVAL is returned if the device can't generate wakeup events from the specified PCI state. Returns zero if the operation is successful.

#### LINUX

Kernel Hackers Manual January 2008
pci_release_region
9
2.6.24-rc6-git8

#### pci_release_region

Release a PCI bar

##### Synopsis

       void pci_release_region
       struct pci_dev * pdev
       int bar

##### Arguments

`pdev`

  PCI device whose resources were previously reserved by pci_request_region

`bar`

  BAR to release

##### Description

Releases the PCI I/O and memory resources previously reserved by a successful call to pci_request_region. Call this function only after all use of the PCI regions has ceased.

#### LINUX

Kernel Hackers Manual January 2008
pci_request_region
9
2.6.24-rc6-git8

#### pci_request_region

Reserved PCI I/O and memory resource

##### Synopsis

       int pci_request_region
       struct pci_dev * pdev
       int bar
       const char * res_name

##### Arguments

`pdev`

  PCI device whose resources are to be reserved

`bar`

  BAR to be reserved

`res_name`

  Name to be associated with resource.

##### Description

Mark the PCI region associated with PCI device `pdev` BR `bar` as being reserved by owner `res_name`. Do not access any address inside the PCI regions unless this call returns successfully.

Returns 0 on success, or `EBUSY` on error. A warning message is also printed on failure.

#### LINUX

Kernel Hackers Manual January 2008
pci_release_selected_regions
9
2.6.24-rc6-git8

#### pci_release_selected_regions

Release selected PCI I/O and memory resources

##### Synopsis

       void pci_release_selected_regions
       struct pci_dev * pdev
       int bars

##### Arguments

`pdev`

  PCI device whose resources were previously reserved

`bars`

  Bitmask of BARs to be released

##### Description

Release selected PCI I/O and memory resources previously reserved. Call this function only after all use of the PCI regions has ceased.

#### LINUX

Kernel Hackers Manual January 2008
pci_request_selected_regions
9
2.6.24-rc6-git8

#### pci_request_selected_regions

Reserve selected PCI I/O and memory resources

##### Synopsis

       int pci_request_selected_regions
       struct pci_dev * pdev
       int bars
       const char * res_name

##### Arguments

`pdev`

  PCI device whose resources are to be reserved

`bars`

  Bitmask of BARs to be requested

`res_name`

  Name to be associated with resource

#### LINUX

Kernel Hackers Manual January 2008
pci_release_regions
9
2.6.24-rc6-git8

#### pci_release_regions

Release reserved PCI I/O and memory resources

##### Synopsis

       void pci_release_regions
       struct pci_dev * pdev

##### Arguments

`pdev`

  PCI device whose resources were previously reserved by pci_request_regions

##### Description

Releases all PCI I/O and memory resources previously reserved by a successful call to pci_request_regions. Call this function only after all use of the PCI regions has ceased.

#### LINUX

Kernel Hackers Manual January 2008
pci_request_regions
9
2.6.24-rc6-git8

#### pci_request_regions

Reserved PCI I/O and memory resources

##### Synopsis

       int pci_request_regions
       struct pci_dev * pdev
       const char * res_name

##### Arguments

`pdev`

  PCI device whose resources are to be reserved

`res_name`

  Name to be associated with resource.

##### Description

Mark all PCI regions associated with PCI device `pdev` as being reserved by owner `res_name`. Do not access any address inside the PCI regions unless this call returns successfully.

Returns 0 on success, or `EBUSY` on error. A warning message is also printed on failure.

#### LINUX

Kernel Hackers Manual January 2008
pci_set_master
9
2.6.24-rc6-git8

#### pci_set_master

enables bus-mastering for device dev

##### Synopsis

       void pci_set_master
       struct pci_dev * dev

##### Arguments

`dev`

  the PCI device to enable

##### Description

Enables bus-mastering on the device and calls `pcibios_set_master` to do the needed arch specific settings.

#### LINUX

Kernel Hackers Manual January 2008
pci_set_mwi
9
2.6.24-rc6-git8

#### pci_set_mwi

enables memory-write-invalidate PCI transaction

##### Synopsis

       int pci_set_mwi
       struct pci_dev * dev

##### Arguments

`dev`

  the PCI device for which MWI is enabled

##### Description

Enables the Memory-Write-Invalidate transaction in `PCI_COMMAND`.

##### RETURNS

An appropriate -ERRNO error value on error, or zero for success.

#### LINUX

Kernel Hackers Manual January 2008
pci_try_set_mwi
9
2.6.24-rc6-git8

#### pci_try_set_mwi

enables memory-write-invalidate PCI transaction

##### Synopsis

       int pci_try_set_mwi
       struct pci_dev * dev

##### Arguments

`dev`

  the PCI device for which MWI is enabled

##### Description

Enables the Memory-Write-Invalidate transaction in `PCI_COMMAND`. Callers are not required to check the return value.

##### RETURNS

An appropriate -ERRNO error value on error, or zero for success.

#### LINUX

Kernel Hackers Manual January 2008
pci_clear_mwi
9
2.6.24-rc6-git8

#### pci_clear_mwi

disables Memory-Write-Invalidate for device dev

##### Synopsis

       void pci_clear_mwi
       struct pci_dev * dev

##### Arguments

`dev`

  the PCI device to disable

##### Description

Disables PCI Memory-Write-Invalidate transaction on the device

#### LINUX

Kernel Hackers Manual January 2008
pci_intx
9
2.6.24-rc6-git8

#### pci_intx

enables/disables PCI INTx for device dev

##### Synopsis

       void pci_intx
       struct pci_dev * pdev
       int enable

##### Arguments

`pdev`

  the PCI device to operate on

`enable`

  boolean: whether to enable or disable PCI INTx

##### Description

Enables/disables PCI INTx for device dev

#### LINUX

Kernel Hackers Manual January 2008
pcix_get_max_mmrbc
9
2.6.24-rc6-git8

#### pcix_get_max_mmrbc

get PCI-X maximum designed memory read byte count

##### Synopsis

       int pcix_get_max_mmrbc
       struct pci_dev * dev

##### Arguments

`dev`

  PCI device to query

##### Returns mmrbc

maximum designed memory read count in bytes or appropriate error value.

#### LINUX

Kernel Hackers Manual January 2008
pcix_get_mmrbc
9
2.6.24-rc6-git8

#### pcix_get_mmrbc

get PCI-X maximum memory read byte count

##### Synopsis

       int pcix_get_mmrbc
       struct pci_dev * dev

##### Arguments

`dev`

  PCI device to query

##### Returns mmrbc

maximum memory read count in bytes or appropriate error value.

#### LINUX

Kernel Hackers Manual January 2008
pcix_set_mmrbc
9
2.6.24-rc6-git8

#### pcix_set_mmrbc

set PCI-X maximum memory read byte count

##### Synopsis

       int pcix_set_mmrbc
       struct pci_dev * dev
       int mmrbc

##### Arguments

`dev`

  PCI device to query

`mmrbc`

  maximum memory read count in bytes valid values are 512, 1024, 2048, 4096

##### Description

If possible sets maximum memory read byte count, some bridges have erratas that prevent this.

#### LINUX

Kernel Hackers Manual January 2008
pcie_get_readrq
9
2.6.24-rc6-git8

#### pcie_get_readrq

get PCI Express read request size

##### Synopsis

       int pcie_get_readrq
       struct pci_dev * dev

##### Arguments

`dev`

  PCI device to query

##### Description

Returns maximum memory read request in bytes or appropriate error value.

#### LINUX

Kernel Hackers Manual January 2008
pcie_set_readrq
9
2.6.24-rc6-git8

#### pcie_set_readrq

set PCI Express maximum memory read request

##### Synopsis

       int pcie_set_readrq
       struct pci_dev * dev
       int rq

##### Arguments

`dev`

  PCI device to query

`rq`

  maximum memory read count in bytes valid values are 128, 256, 512, 1024, 2048, 4096

##### Description

If possible sets maximum read byte count

#### LINUX

Kernel Hackers Manual January 2008
pci_select_bars
9
2.6.24-rc6-git8

#### pci_select_bars

Make BAR mask from the type of resource

##### Synopsis

       int pci_select_bars
       struct pci_dev * dev
       unsigned long flags

##### Arguments

`dev`

  the PCI device for which BAR mask is made

`flags`

  resource type mask to be selected

##### Description

This helper routine makes bar mask from the type of resource.

#### LINUX

Kernel Hackers Manual January 2008
pci_match_id
9
2.6.24-rc6-git8

#### pci_match_id

See if a pci device matches a given pci_id table

##### Synopsis

       const struct pci_device_id * pci_match_id
       const struct pci_device_id * ids
       struct pci_dev * dev

##### Arguments

`ids`

  array of PCI device id structures to search in

`dev`

  the PCI device structure to match against.

##### Description

Used by a driver to check whether a PCI device present in the system is in its list of supported devices. Returns the matching pci_device_id structure or `NULL` if there is no match.

Deprecated, don't use this as it will not catch any dynamic ids that a driver might want to check for.

#### LINUX

Kernel Hackers Manual January 2008
__pci_register_driver
9
2.6.24-rc6-git8

#### __pci_register_driver

register a new pci driver

##### Synopsis

       int __pci_register_driver
       struct pci_driver * drv
       struct module * owner
       const char * mod_name

##### Arguments

`drv`

  the driver structure to register

`owner`

  owner module of drv

`mod_name`

  module name string

##### Description

Adds the driver structure to the list of registered drivers. Returns a negative value on error, otherwise 0. If no error occurred, the driver remains registered even if no device was claimed during registration.

#### LINUX

Kernel Hackers Manual January 2008
pci_unregister_driver
9
2.6.24-rc6-git8

#### pci_unregister_driver

unregister a pci driver

##### Synopsis

       void pci_unregister_driver
       struct pci_driver * drv

##### Arguments

`drv`

  the driver structure to unregister

##### Description

Deletes the driver structure from the list of registered PCI drivers, gives it a chance to clean up by calling its `remove` function for each device it was responsible for, and marks those devices as driverless.

#### LINUX

Kernel Hackers Manual January 2008
pci_dev_driver
9
2.6.24-rc6-git8

#### pci_dev_driver

get the pci_driver of a device

##### Synopsis

       struct pci_driver * pci_dev_driver
       const struct pci_dev * dev

##### Arguments

`dev`

  the device to query

##### Description

Returns the appropriate pci_driver structure or `NULL` if there is no registered driver for the device.

#### LINUX

Kernel Hackers Manual January 2008
pci_dev_get
9
2.6.24-rc6-git8

#### pci_dev_get

increments the reference count of the pci device structure

##### Synopsis

       struct pci_dev * pci_dev_get
       struct pci_dev * dev

##### Arguments

`dev`

  the device being referenced

##### Description

Each live reference to a device should be refcounted.

Drivers for PCI devices should normally record such references in their `probe` methods, when they bind to a device, and release them by calling `pci_dev_put`, in their `disconnect` methods.

A pointer to the device with the incremented reference counter is returned.

#### LINUX

Kernel Hackers Manual January 2008
pci_dev_put
9
2.6.24-rc6-git8

#### pci_dev_put

release a use of the pci device structure

##### Synopsis

       void pci_dev_put
       struct pci_dev * dev

##### Arguments

`dev`

  device that's been disconnected

##### Description

Must be called when a user of a device is finished with it. When the last user of the device calls this function, the memory of the device is freed.

#### LINUX

Kernel Hackers Manual January 2008
pci_remove_bus_device
9
2.6.24-rc6-git8

#### pci_remove_bus_device

remove a PCI device and any children

##### Synopsis

       void pci_remove_bus_device
       struct pci_dev * dev

##### Arguments

`dev`

  the device to remove

##### Description

Remove a PCI device from the device lists, informing the drivers that the device has been removed. We also remove any subordinate buses and children in a depth-first manner.

For each device we remove, delete the device structure from the device lists, remove the /proc entry, and notify userspace (/sbin/hotplug).

#### LINUX

Kernel Hackers Manual January 2008
pci_remove_behind_bridge
9
2.6.24-rc6-git8

#### pci_remove_behind_bridge

remove all devices behind a PCI bridge

##### Synopsis

       void pci_remove_behind_bridge
       struct pci_dev * dev

##### Arguments

`dev`

  PCI bridge device

##### Description

Remove all devices on the bus, except for the parent bridge. This also removes any child buses, and any devices they may contain in a depth-first manner.

#### LINUX

Kernel Hackers Manual January 2008
pci_stop_bus_device
9
2.6.24-rc6-git8

#### pci_stop_bus_device

stop a PCI device and any children

##### Synopsis

       void pci_stop_bus_device
       struct pci_dev * dev

##### Arguments

`dev`

  the device to stop

##### Description

Stop a PCI device (detach the driver, remove from the global list and so on). This also stop any subordinate buses and children in a depth-first manner.

#### LINUX

Kernel Hackers Manual January 2008
pci_osc_support_set
9
2.6.24-rc6-git8

#### pci_osc_support_set

register OS support to Firmware

##### Synopsis

       acpi_status pci_osc_support_set
       u32 flags

##### Arguments

`flags`

  OS support bits

##### Description

Update OS support fields and doing a _OSC Query to obtain an update from Firmware on supported control bits.

#### LINUX

Kernel Hackers Manual January 2008
pci_osc_control_set
9
2.6.24-rc6-git8

#### pci_osc_control_set

commit requested control to Firmware

##### Synopsis

       acpi_status pci_osc_control_set
       acpi_handle handle
       u32 flags

##### Arguments

`handle`

  acpi_handle for the target ACPI object

`flags`

  driver's requested control bits

##### Description

Attempt to take control from Firmware on requested control bits.

#### LINUX

Kernel Hackers Manual January 2008
pci_find_bus
9
2.6.24-rc6-git8

#### pci_find_bus

locate PCI bus from a given domain and bus number

##### Synopsis

       struct pci_bus * pci_find_bus
       int domain
       int busnr

##### Arguments

`domain`

  number of PCI domain to search

`busnr`

  number of desired PCI bus

##### Description

Given a PCI bus number and domain number, the desired PCI bus is located in the global list of PCI buses. If the bus is found, a pointer to its data structure is returned. If no bus is found, `NULL` is returned.

#### LINUX

Kernel Hackers Manual January 2008
pci_find_next_bus
9
2.6.24-rc6-git8

#### pci_find_next_bus

begin or continue searching for a PCI bus

##### Synopsis

       struct pci_bus * pci_find_next_bus
       const struct pci_bus * from

##### Arguments

`from`

  Previous PCI bus found, or `NULL` for new search.

##### Description

Iterates through the list of known PCI busses. A new search is initiated by passing `NULL` as the `from` argument. Otherwise if `from` is not `NULL`, searches continue from next device on the global list.

#### LINUX

Kernel Hackers Manual January 2008
pci_find_slot
9
2.6.24-rc6-git8

#### pci_find_slot

locate PCI device from a given PCI slot

##### Synopsis

       struct pci_dev * pci_find_slot
       unsigned int bus
       unsigned int devfn

##### Arguments

`bus`

  number of PCI bus on which desired PCI device resides

`devfn`

  encodes number of PCI slot in which the desired PCI device resides and the logical device number within that slot in case of multi-function devices.

##### Description

Given a PCI bus and slot/function number, the desired PCI device is located in system global list of PCI devices. If the device is found, a pointer to its data structure is returned. If no device is found, `NULL` is returned.

#### LINUX

Kernel Hackers Manual January 2008
pci_get_slot
9
2.6.24-rc6-git8

#### pci_get_slot

locate PCI device for a given PCI slot

##### Synopsis

       struct pci_dev * pci_get_slot
       struct pci_bus * bus
       unsigned int devfn

##### Arguments

`bus`

  PCI bus on which desired PCI device resides

`devfn`

  encodes number of PCI slot in which the desired PCI device resides and the logical device number within that slot in case of multi-function devices.

##### Description

Given a PCI bus and slot/function number, the desired PCI device is located in the list of PCI devices. If the device is found, its reference count is increased and this function returns a pointer to its data structure. The caller must decrement the reference count by calling `pci_dev_put`. If no device is found, `NULL` is returned.

#### LINUX

Kernel Hackers Manual January 2008
pci_get_bus_and_slot
9
2.6.24-rc6-git8

#### pci_get_bus_and_slot

locate PCI device from a given PCI bus & slot

##### Synopsis

       struct pci_dev * pci_get_bus_and_slot
       unsigned int bus
       unsigned int devfn

##### Arguments

`bus`

  number of PCI bus on which desired PCI device resides

`devfn`

  encodes number of PCI slot in which the desired PCI device resides and the logical device number within that slot in case of multi-function devices.

##### Note

the bus/slot search is limited to PCI domain (segment) 0.

Given a PCI bus and slot/function number, the desired PCI device is located in system global list of PCI devices. If the device is found, a pointer to its data structure is returned. If no device is found, `NULL` is returned. The returned device has its reference count bumped by one.

#### LINUX

Kernel Hackers Manual January 2008
pci_find_device
9
2.6.24-rc6-git8

#### pci_find_device

begin or continue searching for a PCI device by vendor/device id

##### Synopsis

       struct pci_dev * pci_find_device
       unsigned int vendor
       unsigned int device
       const struct pci_dev * from

##### Arguments

`vendor`

  PCI vendor id to match, or `PCI_ANY_ID` to match all vendor ids

`device`

  PCI device id to match, or `PCI_ANY_ID` to match all device ids

`from`

  Previous PCI device found in search, or `NULL` for new search.

##### Description

Iterates through the list of known PCI devices. If a PCI device is found with a matching `vendor` and `device`, a pointer to its device structure is returned. Otherwise, `NULL` is returned. A new search is initiated by passing `NULL` as the `from` argument. Otherwise if `from` is not `NULL`, searches continue from next device on the global list.

##### NOTE

Do not use this function any more; use `pci_get_device` instead, as the PCI device returned by this function can disappear at any moment in time.

#### LINUX

Kernel Hackers Manual January 2008
pci_get_subsys
9
2.6.24-rc6-git8

#### pci_get_subsys

begin or continue searching for a PCI device by vendor/subvendor/device/subdevice id

##### Synopsis

       struct pci_dev * pci_get_subsys
       unsigned int vendor
       unsigned int device
       unsigned int ss_vendor
       unsigned int ss_device
       struct pci_dev * from

##### Arguments

`vendor`

  PCI vendor id to match, or `PCI_ANY_ID` to match all vendor ids

`device`

  PCI device id to match, or `PCI_ANY_ID` to match all device ids

`ss_vendor`

  PCI subsystem vendor id to match, or `PCI_ANY_ID` to match all vendor ids

`ss_device`

  PCI subsystem device id to match, or `PCI_ANY_ID` to match all device ids

`from`

  Previous PCI device found in search, or `NULL` for new search.

##### Description

Iterates through the list of known PCI devices. If a PCI device is found with a matching `vendor`, `device`, `ss_vendor` and `ss_device`, a pointer to its device structure is returned, and the reference count to the device is incremented. Otherwise, `NULL` is returned. A new search is initiated by passing `NULL` as the `from` argument. Otherwise if `from` is not `NULL`, searches continue from next device on the global list. The reference count for `from` is always decremented if it is not `NULL`.

#### LINUX

Kernel Hackers Manual January 2008
pci_get_device
9
2.6.24-rc6-git8

#### pci_get_device

begin or continue searching for a PCI device by vendor/device id

##### Synopsis

       struct pci_dev * pci_get_device
       unsigned int vendor
       unsigned int device
       struct pci_dev * from

##### Arguments

`vendor`

  PCI vendor id to match, or `PCI_ANY_ID` to match all vendor ids

`device`

  PCI device id to match, or `PCI_ANY_ID` to match all device ids

`from`

  Previous PCI device found in search, or `NULL` for new search.

##### Description

Iterates through the list of known PCI devices. If a PCI device is found with a matching `vendor` and `device`, the reference count to the device is incremented and a pointer to its device structure is returned. Otherwise, `NULL` is returned. A new search is initiated by passing `NULL` as the `from` argument. Otherwise if `from` is not `NULL`, searches continue from next device on the global list. The reference count for `from` is always decremented if it is not `NULL`.

#### LINUX

Kernel Hackers Manual January 2008
pci_get_device_reverse
9
2.6.24-rc6-git8

#### pci_get_device_reverse

begin or continue searching for a PCI device by vendor/device id

##### Synopsis

       struct pci_dev * pci_get_device_reverse
       unsigned int vendor
       unsigned int device
       struct pci_dev * from

##### Arguments

`vendor`

  PCI vendor id to match, or `PCI_ANY_ID` to match all vendor ids

`device`

  PCI device id to match, or `PCI_ANY_ID` to match all device ids

`from`

  Previous PCI device found in search, or `NULL` for new search.

##### Description

Iterates through the list of known PCI devices in the reverse order of pci_get_device. If a PCI device is found with a matching `vendor` and `device`, the reference count to the device is incremented and a pointer to its device structure is returned Otherwise, `NULL` is returned. A new search is initiated by passing `NULL` as the `from` argument. Otherwise if `from` is not `NULL`, searches continue from next device on the global list. The reference count for `from` is always decremented if it is not `NULL`.

#### LINUX

Kernel Hackers Manual January 2008
pci_get_class
9
2.6.24-rc6-git8

#### pci_get_class

begin or continue searching for a PCI device by class

##### Synopsis

       struct pci_dev * pci_get_class
       unsigned int class
       struct pci_dev * from

##### Arguments

`class`

  search for a PCI device with this class designation

`from`

  Previous PCI device found in search, or `NULL` for new search.

##### Description

Iterates through the list of known PCI devices. If a PCI device is found with a matching `class`, the reference count to the device is incremented and a pointer to its device structure is returned. Otherwise, `NULL` is returned. A new search is initiated by passing `NULL` as the `from` argument. Otherwise if `from` is not `NULL`, searches continue from next device on the global list. The reference count for `from` is always decremented if it is not `NULL`.

#### LINUX

Kernel Hackers Manual January 2008
pci_dev_present
9
2.6.24-rc6-git8

#### pci_dev_present

Returns 1 if device matching the device list is present, 0 if not.

##### Synopsis

       int pci_dev_present
       const struct pci_device_id * ids

##### Arguments

`ids`

  A pointer to a null terminated list of struct pci_device_id structures that describe the type of PCI device the caller is trying to find.

##### Obvious fact

You do not have a reference to any device that might be found by this function, so if that device is removed from the system right after this function is finished, the value will be stale. Use this function to find devices that are usually built into a system, or for a general hint as to if another device happens to be present at this specific moment in time.

#### LINUX

Kernel Hackers Manual January 2008
pci_enable_msi
9
2.6.24-rc6-git8

#### pci_enable_msi

configure device's MSI capability structure

##### Synopsis

       int pci_enable_msi
       struct pci_dev * dev

##### Arguments

`dev`

  pointer to the pci_dev data structure of MSI device function

##### Description

Setup the MSI capability structure of device function with a single MSI irq upon its software driver call to request for MSI mode enabled on its hardware device function. A return of zero indicates the successful setup of an entry zero with the new MSI irq or non-zero for otherwise.

#### LINUX

Kernel Hackers Manual January 2008
pci_enable_msix
9
2.6.24-rc6-git8

#### pci_enable_msix

configure device's MSI-X capability structure

##### Synopsis

       int pci_enable_msix
       struct pci_dev * dev
       struct msix_entry * entries
       int nvec

##### Arguments

`dev`

  pointer to the pci_dev data structure of MSI-X device function

`entries`

  pointer to an array of MSI-X entries

`nvec`

  number of MSI-X irqs requested for allocation by device driver

##### Description

Setup the MSI-X capability structure of device function with the number of requested irqs upon its software driver call to request for MSI-X mode enabled on its hardware device function. A return of zero indicates the successful configuration of MSI-X capability structure with new allocated MSI-X irqs. A return of < 0 indicates a failure. Or a return of > 0 indicates that driver request is exceeding the number of irqs available. Driver should use the returned value to re-send its request.

#### LINUX

Kernel Hackers Manual January 2008
pci_bus_alloc_resource
9
2.6.24-rc6-git8

#### pci_bus_alloc_resource

allocate a resource from a parent bus

##### Synopsis

       int pci_bus_alloc_resource
       struct pci_bus * bus
       struct resource * res
       resource_size_t size
       resource_size_t align
       resource_size_t min
       unsigned int type_mask
       void (*alignf)
         void *, struct resource *, resource_size_t, 				resource_size_t
       void * alignf_data

##### Arguments

`bus`

  PCI bus

`res`

  resource to allocate

`size`

  size of resource to allocate

`align`

  alignment of resource to allocate

`min`

  minimum /proc/iomem address to allocate

`type_mask`

  IORESOURCE_* type flags

`alignf`

  resource alignment function

`alignf_data`

  data argument for resource alignment function

##### Description

Given the PCI bus a device resides on, the size, minimum address, alignment and type, try to find an acceptable resource allocation for a specific device resource.

#### LINUX

Kernel Hackers Manual January 2008
pci_bus_add_device
9
2.6.24-rc6-git8

#### pci_bus_add_device

##### Synopsis

       int pci_bus_add_device
       struct pci_dev * dev

##### Arguments

`dev`

  device to add

##### Description

This adds a single pci device to the global device list and adds sysfs and procfs entries

#### LINUX

Kernel Hackers Manual January 2008
pci_bus_add_devices
9
2.6.24-rc6-git8

#### pci_bus_add_devices

insert newly discovered PCI devices

##### Synopsis

       void pci_bus_add_devices
       struct pci_bus * bus

##### Arguments

`bus`

  bus to check for new devices

##### Description

Add newly discovered PCI devices (which are on the bus->devices list) to the global PCI device list, add the sysfs and procfs entries. Where a bridge is found, add the discovered bus to the parents list of child buses, and recurse (breadth-first to be compatible with 2.4)

Call hotplug for each new devices.

#### LINUX

Kernel Hackers Manual January 2008
pci_scan_slot
9
2.6.24-rc6-git8

#### pci_scan_slot

scan a PCI slot on a bus for devices.

##### Synopsis

       int pci_scan_slot
       struct pci_bus * bus
       int devfn

##### Arguments

`bus`

  PCI bus to scan

`devfn`

  slot number to scan (must have zero function.)

##### Description

Scan a PCI slot on the specified PCI bus for devices, adding discovered devices to the `bus`->devices list. New devices will have an empty dev->global_list head.

#### LINUX

Kernel Hackers Manual January 2008
pci_map_rom
9
2.6.24-rc6-git8

#### pci_map_rom

map a PCI ROM to kernel space

##### Synopsis

       void __iomem * pci_map_rom
       struct pci_dev * pdev
       size_t * size

##### Arguments

`pdev`

  pointer to pci device struct

`size`

  pointer to receive size of pci window over ROM

##### Description

Map a PCI ROM into kernel space. If ROM is boot video ROM, the shadow BIOS copy will be returned instead of the actual ROM.

#### LINUX

Kernel Hackers Manual January 2008
pci_map_rom_copy
9
2.6.24-rc6-git8

#### pci_map_rom_copy

map a PCI ROM to kernel space, create a copy

##### Synopsis

       void __iomem * pci_map_rom_copy
       struct pci_dev * pdev
       size_t * size

##### Arguments

`pdev`

  pointer to pci device struct

`size`

  pointer to receive size of pci window over ROM

##### Description

Map a PCI ROM into kernel space. If ROM is boot video ROM, the shadow BIOS copy will be returned instead of the actual ROM.

#### LINUX

Kernel Hackers Manual January 2008
pci_unmap_rom
9
2.6.24-rc6-git8

#### pci_unmap_rom

unmap the ROM from kernel space

##### Synopsis

       void pci_unmap_rom
       struct pci_dev * pdev
       void __iomem * rom

##### Arguments

`pdev`

  pointer to pci device struct

`rom`

  virtual address of the previous mapping

##### Description

Remove a mapping of a previously mapped ROM

#### LINUX

Kernel Hackers Manual January 2008
pci_remove_rom
9
2.6.24-rc6-git8

#### pci_remove_rom

disable the ROM and remove its sysfs attribute

##### Synopsis

       void pci_remove_rom
       struct pci_dev * pdev

##### Arguments

`pdev`

  pointer to pci device struct

##### Description

Remove the rom file in sysfs and disable ROM decoding.

### PCI Hotplug Support Library

#### LINUX

Kernel Hackers Manual January 2008
pci_hp_register
9
2.6.24-rc6-git8

#### pci_hp_register

register a hotplug_slot with the PCI hotplug subsystem

##### Synopsis

       int pci_hp_register
       struct hotplug_slot * slot

##### Arguments

`slot`

  pointer to the &struct hotplug_slot to register

##### Description

Registers a hotplug slot with the pci hotplug subsystem, which will allow userspace interaction to the slot.

Returns 0 if successful, anything else for an error.

#### LINUX

Kernel Hackers Manual January 2008
pci_hp_deregister
9
2.6.24-rc6-git8

#### pci_hp_deregister

deregister a hotplug_slot with the PCI hotplug subsystem

##### Synopsis

       int pci_hp_deregister
       struct hotplug_slot * slot

##### Arguments

`slot`

  pointer to the &struct hotplug_slot to deregister

##### Description

The `slot` must have been registered with the pci hotplug subsystem previously with a call to `pci_hp_register`.

Returns 0 if successful, anything else for an error.

#### LINUX

Kernel Hackers Manual January 2008
pci_hp_change_slot_info
9
2.6.24-rc6-git8

#### pci_hp_change_slot_info

changes the slot's information structure in the core

##### Synopsis

       int __must_check pci_hp_change_slot_info
       struct hotplug_slot * slot
       struct hotplug_slot_info * info

##### Arguments

`slot`

  pointer to the slot whose info has changed

`info`

  pointer to the info copy into the slot's info structure

##### Description

`slot` must have been registered with the pci hotplug subsystem previously with a call to `pci_hp_register`.

Returns 0 if successful, anything else for an error.

### MCA Architecture

#### MCA Device Functions

Refer to the file arch/x86/kernel/mca_32.c for more information.

#### MCA Bus DMA

##### LINUX

Kernel Hackers Manual January 2008
mca_enable_dma
9
2.6.24-rc6-git8

##### mca_enable_dma

channel to enable DMA on

###### Synopsis

       void mca_enable_dma
       unsigned int dmanr

###### Arguments

`dmanr`

  DMA channel

###### Description

Enable the MCA bus DMA on a channel. This can be called from IRQ context.

##### LINUX

Kernel Hackers Manual January 2008
mca_disable_dma
9
2.6.24-rc6-git8

##### mca_disable_dma

channel to disable DMA on

###### Synopsis

       void mca_disable_dma
       unsigned int dmanr

###### Arguments

`dmanr`

  DMA channel

###### Description

Enable the MCA bus DMA on a channel. This can be called from IRQ context.

##### LINUX

Kernel Hackers Manual January 2008
mca_set_dma_addr
9
2.6.24-rc6-git8

##### mca_set_dma_addr

load a 24bit DMA address

###### Synopsis

       void mca_set_dma_addr
       unsigned int dmanr
       unsigned int a

###### Arguments

`dmanr`

  DMA channel

`a`

  24bit bus address

###### Description

Load the address register in the DMA controller. This has a 24bit limitation (16Mb).

##### LINUX

Kernel Hackers Manual January 2008
mca_get_dma_addr
9
2.6.24-rc6-git8

##### mca_get_dma_addr

load a 24bit DMA address

###### Synopsis

       unsigned int mca_get_dma_addr
       unsigned int dmanr

###### Arguments

`dmanr`

  DMA channel

###### Description

Read the address register in the DMA controller. This has a 24bit limitation (16Mb). The return is a bus address.

##### LINUX

Kernel Hackers Manual January 2008
mca_set_dma_count
9
2.6.24-rc6-git8

##### mca_set_dma_count

load a 16bit transfer count

###### Synopsis

       void mca_set_dma_count
       unsigned int dmanr
       unsigned int count

###### Arguments

`dmanr`

  DMA channel

`count`

  count

###### Description

Set the DMA count for this channel. This can be up to 64Kbytes. Setting a count of zero will not do what you expect.

##### LINUX

Kernel Hackers Manual January 2008
mca_get_dma_residue
9
2.6.24-rc6-git8

##### mca_get_dma_residue

get the remaining bytes to transfer

###### Synopsis

       unsigned int mca_get_dma_residue
       unsigned int dmanr

###### Arguments

`dmanr`

  DMA channel

###### Description

This function returns the number of bytes left to transfer on this DMA channel.

##### LINUX

Kernel Hackers Manual January 2008
mca_set_dma_io
9
2.6.24-rc6-git8

##### mca_set_dma_io

set the port for an I/O transfer

###### Synopsis

       void mca_set_dma_io
       unsigned int dmanr
       unsigned int io_addr

###### Arguments

`dmanr`

  DMA channel

`io_addr`

  an I/O port number

###### Description

Unlike the ISA bus DMA controllers the DMA on MCA bus can transfer with an I/O port target.

##### LINUX

Kernel Hackers Manual January 2008
mca_set_dma_mode
9
2.6.24-rc6-git8

##### mca_set_dma_mode

set the DMA mode

###### Synopsis

       void mca_set_dma_mode
       unsigned int dmanr
       unsigned int mode

###### Arguments

`dmanr`

  DMA channel

`mode`

  mode to set

###### Description

The DMA controller supports several modes. The mode values you can set are-

`MCA_DMA_MODE_READ` when reading from the DMA device.

`MCA_DMA_MODE_WRITE` to writing to the DMA device.

`MCA_DMA_MODE_IO` to do DMA to or from an I/O port.

`MCA_DMA_MODE_16` to do 16bit transfers.

## Firmware Interfaces

### DMI Interfaces

#### LINUX

Kernel Hackers Manual January 2008
dmi_check_system
9
2.6.24-rc6-git8

#### dmi_check_system

check system DMI data

##### Synopsis

       int dmi_check_system
       const struct dmi_system_id * list

##### Arguments

`list`

  array of dmi_system_id structures to match against All non-null elements of the list must match their slot's (field index's) data (i.e., each list string must be a substring of the specified DMI slot's string data) to be considered a successful match.

##### Description

Walk the blacklist table running matching functions until someone returns non zero or we hit the end. Callback function is called for each successful match. Returns the number of matches.

#### LINUX

Kernel Hackers Manual January 2008
dmi_get_system_info
9
2.6.24-rc6-git8

#### dmi_get_system_info

return DMI data value

##### Synopsis

       const char * dmi_get_system_info
       int field

##### Arguments

`field`

  data index (see enum dmi_field)

##### Description

Returns one DMI data value, can be used to perform complex DMI data checks.

#### LINUX

Kernel Hackers Manual January 2008
dmi_name_in_vendors
9
2.6.24-rc6-git8

#### dmi_name_in_vendors

Check if string is anywhere in the DMI vendor information.

##### Synopsis

       int dmi_name_in_vendors
       const char * str

##### Arguments

`str`

  Case sensitive Name

#### LINUX

Kernel Hackers Manual January 2008
dmi_find_device
9
2.6.24-rc6-git8

#### dmi_find_device

find onboard device by type/name

##### Synopsis

       const struct dmi_device * dmi_find_device
       int type
       const char * name
       const struct dmi_device * from

##### Arguments

`type`

  device type or `DMI_DEV_TYPE_ANY` to match all device types

`name`

  device name string or `NULL` to match all

`from`

  previous device found in search, or `NULL` for new search.

##### Description

Iterates through the list of known onboard devices. If a device is found with a matching `vendor` and `device`, a pointer to its device structure is returned. Otherwise, `NULL` is returned. A new search is initiated by passing `NULL` as the `from` argument. If `from` is not `NULL`, searches continue from next device.

### EDD Interfaces

#### LINUX

Kernel Hackers Manual January 2008
edd_show_raw_data
9
2.6.24-rc6-git8

#### edd_show_raw_data

copies raw data to buffer for userspace to parse

##### Synopsis

       ssize_t edd_show_raw_data
       struct edd_device * edev
       char * buf

##### Arguments

`edev`

  target edd_device

`buf`

  output buffer

##### Returns

number of bytes written, or -EINVAL on failure

#### LINUX

Kernel Hackers Manual January 2008
edd_release
9
2.6.24-rc6-git8

#### edd_release

free edd structure

##### Synopsis

       void edd_release
       struct kobject * kobj

##### Arguments

`kobj`

  kobject of edd structure

##### Description

This is called when the refcount of the edd structure reaches 0. This should happen right after we unregister, but just in case, we use the release callback anyway.

#### LINUX

Kernel Hackers Manual January 2008
edd_dev_is_type
9
2.6.24-rc6-git8

#### edd_dev_is_type

is this EDD device a 'type' device?

##### Synopsis

       int edd_dev_is_type
       struct edd_device * edev
       const char * type

##### Arguments

`edev`

  target edd_device

`type`

  a host bus or interface identifier string per the EDD spec

##### Description

Returns 1 (TRUE) if it is a 'type' device, 0 otherwise.

#### LINUX

Kernel Hackers Manual January 2008
edd_get_pci_dev
9
2.6.24-rc6-git8

#### edd_get_pci_dev

finds pci_dev that matches edev

##### Synopsis

       struct pci_dev * edd_get_pci_dev
       struct edd_device * edev

##### Arguments

`edev`

  edd_device

##### Description

Returns pci_dev if found, or NULL

#### LINUX

Kernel Hackers Manual January 2008
edd_init
9
2.6.24-rc6-git8

#### edd_init

creates sysfs tree of EDD data

##### Synopsis

       int __init edd_init
        void

##### Arguments

`void`

  no arguments

## Security Framework

### LINUX

Kernel Hackers Manual January 2008
security_init
9
2.6.24-rc6-git8

### security_init

initializes the security framework

#### Synopsis

       int __init security_init
        void

#### Arguments

`void`

  no arguments

#### Description

This should be called early in the kernel initialization sequence.

### LINUX

Kernel Hackers Manual January 2008
register_security
9
2.6.24-rc6-git8

### register_security

registers a security framework with the kernel

#### Synopsis

       int register_security
       struct security_operations * ops

#### Arguments

`ops`

  a pointer to the struct security_options that is to be registered

#### Description

This function is to allow a security module to register itself with the kernel security subsystem. Some rudimentary checking is done on the `ops` value passed to this function.

If there is already a security module registered with the kernel, an error will be returned. Otherwise 0 is returned on success.

### LINUX

Kernel Hackers Manual January 2008
mod_reg_security
9
2.6.24-rc6-git8

### mod_reg_security

allows security modules to be stacked

#### Synopsis

       int mod_reg_security
       const char * name
       struct security_operations * ops

#### Arguments

`name`

  a pointer to a string with the name of the security_options to be registered

`ops`

  a pointer to the struct security_options that is to be registered

#### Description

This function allows security modules to be stacked if the currently loaded security module allows this to happen. It passes the `name` and `ops` to the register_security function of the currently loaded security module.

The return value depends on the currently loaded security module, with 0 as success.

## Audit Interfaces

### LINUX

Kernel Hackers Manual January 2008
audit_log_start
9
2.6.24-rc6-git8

### audit_log_start

obtain an audit buffer

#### Synopsis

       struct audit_buffer * audit_log_start
       struct audit_context * ctx
       gfp_t gfp_mask
       int type

#### Arguments

`ctx`

  audit_context (may be NULL)

`gfp_mask`

  type of allocation

`type`

  audit message type

#### Description

Returns audit_buffer pointer on success or NULL on error.

Obtain an audit buffer. This routine does locking to obtain the audit buffer, but then no locking is required for calls to audit_log_*format. If the task (ctx) is a task that is currently in a syscall, then the syscall is marked as auditable and an audit record will be written at syscall exit. If there is no associated task, then task context (ctx) should be NULL.

### LINUX

Kernel Hackers Manual January 2008
audit_log_format
9
2.6.24-rc6-git8

### audit_log_format

format a message into the audit buffer.

#### Synopsis

       void audit_log_format
       struct audit_buffer * ab
       const char * fmt
        ...

#### Arguments

`ab`

  audit_buffer

`fmt`

  format string @...: optional parameters matching `fmt` string

`...`

  variable arguments

#### Description

All the work is done in audit_log_vformat.

### LINUX

Kernel Hackers Manual January 2008
audit_log_end
9
2.6.24-rc6-git8

### audit_log_end

end one audit record

#### Synopsis

       void audit_log_end
       struct audit_buffer * ab

#### Arguments

`ab`

  the audit_buffer

#### Description

The netlink_* functions cannot be called inside an irq context, so the audit buffer is placed on a queue and a tasklet is scheduled to remove them from the queue outside the irq context. May be called in any context.

### LINUX

Kernel Hackers Manual January 2008
audit_log
9
2.6.24-rc6-git8

### audit_log

Log an audit record

#### Synopsis

       void audit_log
       struct audit_context * ctx
       gfp_t gfp_mask
       int type
       const char * fmt
        ...

#### Arguments

`ctx`

  audit context

`gfp_mask`

  type of allocation

`type`

  audit message type

`fmt`

  format string to use @...: variable parameters matching the format string

`...`

  variable arguments

#### Description

This is a convenience function that calls audit_log_start, audit_log_vformat, and audit_log_end. It may be called in any context.

### LINUX

Kernel Hackers Manual January 2008
audit_alloc
9
2.6.24-rc6-git8

### audit_alloc

allocate an audit context block for a task

#### Synopsis

       int audit_alloc
       struct task_struct * tsk

#### Arguments

`tsk`

  task

#### Description

Filter on the task information and allocate a per-task audit context if necessary. Doing so turns on system call auditing for the specified task. This is called from copy_process, so no lock is needed.

### LINUX

Kernel Hackers Manual January 2008
audit_free
9
2.6.24-rc6-git8

### audit_free

free a per-task audit context

#### Synopsis

       void audit_free
       struct task_struct * tsk

#### Arguments

`tsk`

  task whose audit context block to free

#### Description

Called from copy_process and do_exit

### LINUX

Kernel Hackers Manual January 2008
audit_syscall_entry
9
2.6.24-rc6-git8

### audit_syscall_entry

fill in an audit record at syscall entry

#### Synopsis

       void audit_syscall_entry
       int arch
       int major
       unsigned long a1
       unsigned long a2
       unsigned long a3
       unsigned long a4

#### Arguments

`arch`

  architecture type

`major`

  major syscall type (function)

`a1`

  additional syscall register 1

`a2`

  additional syscall register 2

`a3`

  additional syscall register 3

`a4`

  additional syscall register 4

#### Description

Fill in audit context at syscall entry. This only happens if the audit context was created when the task was created and the state or filters demand the audit context be built. If the state from the per-task filter or from the per-syscall filter is AUDIT_RECORD_CONTEXT, then the record will be written at syscall exit time (otherwise, it will only be written if another part of the kernel requests that it be written).

### LINUX

Kernel Hackers Manual January 2008
audit_syscall_exit
9
2.6.24-rc6-git8

### audit_syscall_exit

deallocate audit context after a system call

#### Synopsis

       void audit_syscall_exit
       int valid
       long return_code

#### Arguments

`valid`

  success/failure flag

`return_code`

  syscall return value

#### Description

Tear down after system call. If the audit context has been marked as auditable (either because of the AUDIT_RECORD_CONTEXT state from filtering, or because some other part of the kernel write an audit message), then write out the syscall information. In call cases, free the names stored from `getname`.

### LINUX

Kernel Hackers Manual January 2008
__audit_getname
9
2.6.24-rc6-git8

### __audit_getname

add a name to the list

#### Synopsis

       void __audit_getname
       const char * name

#### Arguments

`name`

  name to add

#### Description

Add a name to the list of audit names for this context. Called from fs/namei.c:`getname`.

### LINUX

Kernel Hackers Manual January 2008
__audit_inode
9
2.6.24-rc6-git8

### __audit_inode

store the inode and device from a lookup

#### Synopsis

       void __audit_inode
       const char * name
       const struct dentry * dentry

#### Arguments

`name`

  name being audited

`dentry`

  dentry being audited

#### Description

Called from fs/namei.c:`path_lookup`.

### LINUX

Kernel Hackers Manual January 2008
auditsc_get_stamp
9
2.6.24-rc6-git8

### auditsc_get_stamp

get local copies of audit_context values

#### Synopsis

       void auditsc_get_stamp
       struct audit_context * ctx
       struct timespec * t
       unsigned int * serial

#### Arguments

`ctx`

  audit_context for the task

`t`

  timespec to store time recorded in the audit_context

`serial`

  serial value that is recorded in the audit_context

#### Description

Also sets the context as auditable.

### LINUX

Kernel Hackers Manual January 2008
audit_set_loginuid
9
2.6.24-rc6-git8

### audit_set_loginuid

set a task's audit_context loginuid

#### Synopsis

       int audit_set_loginuid
       struct task_struct * task
       uid_t loginuid

#### Arguments

`task`

  task whose audit context is being modified

`loginuid`

  loginuid value

#### Description

Returns 0.

Called (set) from fs/proc/base.c::`proc_loginuid_write`.

### LINUX

Kernel Hackers Manual January 2008
__audit_mq_open
9
2.6.24-rc6-git8

### __audit_mq_open

record audit data for a POSIX MQ open

#### Synopsis

       int __audit_mq_open
       int oflag
       mode_t mode
       struct mq_attr __user * u_attr

#### Arguments

`oflag`

  open flag

`mode`

  mode bits

`u_attr`

  queue attributes

#### Description

Returns 0 for success or NULL context or < 0 on error.

### LINUX

Kernel Hackers Manual January 2008
__audit_mq_timedsend
9
2.6.24-rc6-git8

### __audit_mq_timedsend

record audit data for a POSIX MQ timed send

#### Synopsis

       int __audit_mq_timedsend
       mqd_t mqdes
       size_t msg_len
       unsigned int msg_prio
       const struct timespec __user * u_abs_timeout

#### Arguments

`mqdes`

  MQ descriptor

`msg_len`

  Message length

`msg_prio`

  Message priority

`u_abs_timeout`

  Message timeout in absolute time

#### Description

Returns 0 for success or NULL context or < 0 on error.

### LINUX

Kernel Hackers Manual January 2008
__audit_mq_timedreceive
9
2.6.24-rc6-git8

### __audit_mq_timedreceive

record audit data for a POSIX MQ timed receive

#### Synopsis

       int __audit_mq_timedreceive
       mqd_t mqdes
       size_t msg_len
       unsigned int __user * u_msg_prio
       const struct timespec __user * u_abs_timeout

#### Arguments

`mqdes`

  MQ descriptor

`msg_len`

  Message length

`u_msg_prio`

  Message priority

`u_abs_timeout`

  Message timeout in absolute time

#### Description

Returns 0 for success or NULL context or < 0 on error.

### LINUX

Kernel Hackers Manual January 2008
__audit_mq_notify
9
2.6.24-rc6-git8

### __audit_mq_notify

record audit data for a POSIX MQ notify

#### Synopsis

       int __audit_mq_notify
       mqd_t mqdes
       const struct sigevent __user * u_notification

#### Arguments

`mqdes`

  MQ descriptor

`u_notification`

  Notification event

#### Description

Returns 0 for success or NULL context or < 0 on error.

### LINUX

Kernel Hackers Manual January 2008
__audit_mq_getsetattr
9
2.6.24-rc6-git8

### __audit_mq_getsetattr

record audit data for a POSIX MQ get/set attribute

#### Synopsis

       int __audit_mq_getsetattr
       mqd_t mqdes
       struct mq_attr * mqstat

#### Arguments

`mqdes`

  MQ descriptor

`mqstat`

  MQ flags

#### Description

Returns 0 for success or NULL context or < 0 on error.

### LINUX

Kernel Hackers Manual January 2008
__audit_ipc_obj
9
2.6.24-rc6-git8

### __audit_ipc_obj

record audit data for ipc object

#### Synopsis

       int __audit_ipc_obj
       struct kern_ipc_perm * ipcp

#### Arguments

`ipcp`

  ipc permissions

#### Description

Returns 0 for success or NULL context or < 0 on error.

### LINUX

Kernel Hackers Manual January 2008
__audit_ipc_set_perm
9
2.6.24-rc6-git8

### __audit_ipc_set_perm

record audit data for new ipc permissions

#### Synopsis

       int __audit_ipc_set_perm
       unsigned long qbytes
       uid_t uid
       gid_t gid
       mode_t mode

#### Arguments

`qbytes`

  msgq bytes

`uid`

  msgq user id

`gid`

  msgq group id

`mode`

  msgq mode (permissions)

#### Description

Returns 0 for success or NULL context or < 0 on error.

### LINUX

Kernel Hackers Manual January 2008
audit_socketcall
9
2.6.24-rc6-git8

### audit_socketcall

record audit data for sys_socketcall

#### Synopsis

       int audit_socketcall
       int nargs
       unsigned long * args

#### Arguments

`nargs`

  number of args

`args`

  args array

#### Description

Returns 0 for success or NULL context or < 0 on error.

### LINUX

Kernel Hackers Manual January 2008
__audit_fd_pair
9
2.6.24-rc6-git8

### __audit_fd_pair

record audit data for pipe and socketpair

#### Synopsis

       int __audit_fd_pair
       int fd1
       int fd2

#### Arguments

`fd1`

  the first file descriptor

`fd2`

  the second file descriptor

#### Description

Returns 0 for success or NULL context or < 0 on error.

### LINUX

Kernel Hackers Manual January 2008
audit_sockaddr
9
2.6.24-rc6-git8

### audit_sockaddr

record audit data for sys_bind, sys_connect, sys_sendto

#### Synopsis

       int audit_sockaddr
       int len
       void * a

#### Arguments

`len`

  data length in user space

`a`

  data address in kernel space

#### Description

Returns 0 for success or NULL context or < 0 on error.

### LINUX

Kernel Hackers Manual January 2008
__audit_signal_info
9
2.6.24-rc6-git8

### __audit_signal_info

record signal info for shutting down audit subsystem

#### Synopsis

       int __audit_signal_info
       int sig
       struct task_struct * t

#### Arguments

`sig`

  signal value

`t`

  task being signaled

#### Description

If the audit subsystem is being terminated, record the task (pid) and uid that is doing that.

### LINUX

Kernel Hackers Manual January 2008
audit_core_dumps
9
2.6.24-rc6-git8

### audit_core_dumps

record information about processes that end abnormally

#### Synopsis

       void audit_core_dumps
       long signr

#### Arguments

`signr`

  signal value

#### Description

If a process ends with a core dump, something fishy is going on and we should record the event for investigation.

### LINUX

Kernel Hackers Manual January 2008
audit_receive_filter
9
2.6.24-rc6-git8

### audit_receive_filter

apply all rules to the specified message type

#### Synopsis

       int audit_receive_filter
       int type
       int pid
       int uid
       int seq
       void * data
       size_t datasz
       uid_t loginuid
       u32 sid

#### Arguments

`type`

  audit message type

`pid`

  target pid for netlink audit messages

`uid`

  target uid for netlink audit messages

`seq`

  netlink audit message sequence (serial) number

`data`

  payload data

`datasz`

  size of payload data

`loginuid`

  loginuid of sender

`sid`

  SE Linux Security ID of sender

## Accounting Framework

### LINUX

Kernel Hackers Manual January 2008
sys_acct
9
2.6.24-rc6-git8

### sys_acct

enable/disable process accounting

#### Synopsis

       long sys_acct
       const char __user * name

#### Arguments

`name`

  file name for accounting records or NULL to shutdown accounting

#### Description

Returns 0 for success or negative errno values for failure.

`sys_acct` is the only system call needed to implement process accounting. It takes the name of the file where accounting records should be written. If the filename is NULL, accounting will be shutdown.

### LINUX

Kernel Hackers Manual January 2008
acct_auto_close_mnt
9
2.6.24-rc6-git8

### acct_auto_close_mnt

turn off a filesystem's accounting if it is on

#### Synopsis

       void acct_auto_close_mnt
       struct vfsmount * m

#### Arguments

`m`

  vfsmount being shut down

#### Description

If the accounting is turned on for a file in the subtree pointed to to by m, turn accounting off. Done when m is about to die.

### LINUX

Kernel Hackers Manual January 2008
acct_auto_close
9
2.6.24-rc6-git8

### acct_auto_close

turn off a filesystem's accounting if it is on

#### Synopsis

       void acct_auto_close
       struct super_block * sb

#### Arguments

`sb`

  super block for the filesystem

#### Description

If the accounting is turned on for a file in the filesystem pointed to by sb, turn accounting off.

### LINUX

Kernel Hackers Manual January 2008
acct_init_pacct
9
2.6.24-rc6-git8

### acct_init_pacct

initialize a new pacct_struct

#### Synopsis

       void acct_init_pacct
       struct pacct_struct * pacct

#### Arguments

`pacct`

  per-process accounting info struct to initialize

### LINUX

Kernel Hackers Manual January 2008
acct_collect
9
2.6.24-rc6-git8

### acct_collect

collect accounting information into pacct_struct

#### Synopsis

       void acct_collect
       long exitcode
       int group_dead

#### Arguments

`exitcode`

  task exit code

`group_dead`

  not 0, if this thread is the last one in the process.

### LINUX

Kernel Hackers Manual January 2008
acct_process
9
2.6.24-rc6-git8

### acct_process

now just a wrapper around do_acct_process

#### Synopsis

       void acct_process
        void

#### Arguments

`void`

  no arguments

#### Description

handles process accounting for an exiting task

## Power Management

### LINUX

Kernel Hackers Manual January 2008
pm_register
9
2.6.24-rc6-git8

### pm_register

register a device with power management

#### Synopsis

       struct pm_dev * pm_register
       pm_dev_t type
       unsigned long id
       pm_callback callback

#### Arguments

`type`

  device type

`id`

  device ID

`callback`

  callback function

#### Description

Add a device to the list of devices that wish to be notified about power management events. A &pm_dev structure is returned on success, on failure the return is `NULL`.

The callback function will be called in process context and it may sleep.

### LINUX

Kernel Hackers Manual January 2008
pm_send_all
9
2.6.24-rc6-git8

### pm_send_all

send request to all managed devices

#### Synopsis

       int pm_send_all
       pm_request_t rqst
       void * data

#### Arguments

`rqst`

  power management request

`data`

  data for the callback

#### Description

Issue a power management request to a all devices. The `PM_SUSPEND` events are handled specially. Any device is permitted to fail a suspend by returning a non zero (error) value from its callback function. If any device vetoes a suspend request then all other devices that have suspended during the processing of this request are restored to their previous state.

#### WARNING

This function takes the pm_devs_lock. The lock is not dropped until the callbacks have completed. This prevents races against pm locking functions, races against module unload pm_unregister code. It does mean however that you must not issue pm_ functions within the callback or you will deadlock and users will hate you.

Zero is returned on success. If a suspend fails then the status from the device that vetoes the suspend is returned.

#### BUGS

what stops two power management requests occurring in parallel and conflicting.

## Device drivers infrastructure

### Device Drivers Base

#### LINUX

Kernel Hackers Manual January 2008
driver_for_each_device
9
2.6.24-rc6-git8

#### driver_for_each_device

Iterator for devices bound to a driver.

##### Synopsis

       int driver_for_each_device
       struct device_driver * drv
       struct device * start
       void * data
       int (*fn)
         struct device *, void *

##### Arguments

`drv`

  Driver we're iterating.

`start`

  Device to begin with

`data`

  Data to pass to the callback.

`fn`

  Function to call for each device.

##### Description

Iterate over the `drv`'s list of devices calling `fn` for each one.

#### LINUX

Kernel Hackers Manual January 2008
driver_find_device
9
2.6.24-rc6-git8

#### driver_find_device

device iterator for locating a particular device.

##### Synopsis

       struct device * driver_find_device
       struct device_driver * drv
       struct device * start
       void * data
       int (*match)
         struct device *, void *

##### Arguments

`drv`

  The device's driver

`start`

  Device to begin with

`data`

  Data to pass to match function

`match`

  Callback function to check device

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
driver_create_file
9
2.6.24-rc6-git8

#### driver_create_file

create sysfs file for driver.

##### Synopsis

       int driver_create_file
       struct device_driver * drv
       struct driver_attribute * attr

##### Arguments

`drv`

  driver.

`attr`

  driver attribute descriptor.

#### LINUX

Kernel Hackers Manual January 2008
driver_remove_file
9
2.6.24-rc6-git8

#### driver_remove_file

remove sysfs file for driver.

##### Synopsis

       void driver_remove_file
       struct device_driver * drv
       struct driver_attribute * attr

##### Arguments

`drv`

  driver.

`attr`

  driver attribute descriptor.

#### LINUX

Kernel Hackers Manual January 2008
get_driver
9
2.6.24-rc6-git8

#### get_driver

increment driver reference count.

##### Synopsis

       struct device_driver * get_driver
       struct device_driver * drv

##### Arguments

`drv`

  driver.

#### LINUX

Kernel Hackers Manual January 2008
put_driver
9
2.6.24-rc6-git8

#### put_driver

decrement driver's refcount.

##### Synopsis

       void put_driver
       struct device_driver * drv

##### Arguments

`drv`

  driver.

#### LINUX

Kernel Hackers Manual January 2008
driver_register
9
2.6.24-rc6-git8

#### driver_register

register driver with bus

##### Synopsis

       int driver_register
       struct device_driver * drv

##### Arguments

`drv`

  driver to register

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
driver_unregister
9
2.6.24-rc6-git8

#### driver_unregister

remove driver from system.

##### Synopsis

       void driver_unregister
       struct device_driver * drv

##### Arguments

`drv`

  driver.

##### Description

Again, we pass off most of the work to the bus-level call.

#### LINUX

Kernel Hackers Manual January 2008
driver_find
9
2.6.24-rc6-git8

#### driver_find

locate driver on a bus by its name.

##### Synopsis

       struct device_driver * driver_find
       const char * name
       struct bus_type * bus

##### Arguments

`name`

  name of the driver.

`bus`

  bus to scan for the driver.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
dev_driver_string
9
2.6.24-rc6-git8

#### dev_driver_string

Return a device's driver name, if at all possible

##### Synopsis

       const char * dev_driver_string
       struct device * dev

##### Arguments

`dev`

  struct device to get the name of

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
device_create_file
9
2.6.24-rc6-git8

#### device_create_file

create sysfs attribute file for device.

##### Synopsis

       int device_create_file
       struct device * dev
       struct device_attribute * attr

##### Arguments

`dev`

  device.

`attr`

  device attribute descriptor.

#### LINUX

Kernel Hackers Manual January 2008
device_remove_file
9
2.6.24-rc6-git8

#### device_remove_file

remove sysfs attribute file.

##### Synopsis

       void device_remove_file
       struct device * dev
       struct device_attribute * attr

##### Arguments

`dev`

  device.

`attr`

  device attribute descriptor.

#### LINUX

Kernel Hackers Manual January 2008
device_create_bin_file
9
2.6.24-rc6-git8

#### device_create_bin_file

create sysfs binary attribute file for device.

##### Synopsis

       int device_create_bin_file
       struct device * dev
       struct bin_attribute * attr

##### Arguments

`dev`

  device.

`attr`

  device binary attribute descriptor.

#### LINUX

Kernel Hackers Manual January 2008
device_remove_bin_file
9
2.6.24-rc6-git8

#### device_remove_bin_file

remove sysfs binary attribute file

##### Synopsis

       void device_remove_bin_file
       struct device * dev
       struct bin_attribute * attr

##### Arguments

`dev`

  device.

`attr`

  device binary attribute descriptor.

#### LINUX

Kernel Hackers Manual January 2008
device_schedule_callback_owner
9
2.6.24-rc6-git8

#### device_schedule_callback_owner

helper to schedule a callback for a device

##### Synopsis

       int device_schedule_callback_owner
       struct device * dev
       void (*func)
         struct device *
       struct module * owner

##### Arguments

`dev`

  device.

`func`

  callback function to invoke later.

`owner`

  module owning the callback routine

##### Description

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.

##### NOTE

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.

#### LINUX

Kernel Hackers Manual January 2008
device_initialize
9
2.6.24-rc6-git8

#### device_initialize

init device structure.

##### Synopsis

       void device_initialize
       struct device * dev

##### Arguments

`dev`

  device.

##### Description

This prepares the device for use by other layers, including adding it to the device hierarchy. It is the first half of `device_register`, if called by that, though it can also be called separately, so one may use `dev`'s fields (e.g. the refcount).

#### LINUX

Kernel Hackers Manual January 2008
device_add
9
2.6.24-rc6-git8

#### device_add

add device to device hierarchy.

##### Synopsis

       int device_add
       struct device * dev

##### Arguments

`dev`

  device.

##### Description

This is part 2 of `device_register`, though may be called separately _iff_ `device_initialize` has been called separately.

This adds it 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.

#### LINUX

Kernel Hackers Manual January 2008
device_register
9
2.6.24-rc6-git8

#### device_register

register a device with the system.

##### Synopsis

       int device_register
       struct device * dev

##### Arguments

`dev`

  pointer to the device structure

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
get_device
9
2.6.24-rc6-git8

#### get_device

increment reference count for device.

##### Synopsis

       struct device * get_device
       struct device * dev

##### Arguments

`dev`

  device.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
put_device
9
2.6.24-rc6-git8

#### put_device

decrement reference count.

##### Synopsis

       void put_device
       struct device * dev

##### Arguments

`dev`

  device in question.

#### LINUX

Kernel Hackers Manual January 2008
device_del
9
2.6.24-rc6-git8

#### device_del

delete device from system.

##### Synopsis

       void device_del
       struct device * dev

##### Arguments

`dev`

  device.

##### Description

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.

##### NOTE

this should be called manually _iff_ `device_add` was also called manually.

#### LINUX

Kernel Hackers Manual January 2008
device_unregister
9
2.6.24-rc6-git8

#### device_unregister

unregister device from system.

##### Synopsis

       void device_unregister
       struct device * dev

##### Arguments

`dev`

  device going away.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
device_for_each_child
9
2.6.24-rc6-git8

#### device_for_each_child

device child iterator.

##### Synopsis

       int device_for_each_child
       struct device * parent
       void * data
       int (*fn)
         struct device *, void *

##### Arguments

`parent`

  parent struct device.

`data`

  data for the callback.

`fn`

  function to be called for each device.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
device_find_child
9
2.6.24-rc6-git8

#### device_find_child

device iterator for locating a particular device.

##### Synopsis

       struct device * device_find_child
       struct device * parent
       void * data
       int (*match)
         struct device *, void *

##### Arguments

`parent`

  parent struct device

`data`

  Data to pass to match function

`match`

  Callback function to check device

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
device_create
9
2.6.24-rc6-git8

#### device_create

creates a device and registers it with sysfs

##### Synopsis

       struct device * device_create
       struct class * class
       struct device * parent
       dev_t devt
       const char * fmt
        ...

##### Arguments

`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

`fmt`

  string for the device's name

`...`

  variable arguments

##### Description

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.

##### Note

the struct class passed to this function must have previously been created with a call to `class_create`.

#### LINUX

Kernel Hackers Manual January 2008
device_destroy
9
2.6.24-rc6-git8

#### device_destroy

removes a device that was created with `device_create`

##### Synopsis

       void device_destroy
       struct class * class
       dev_t devt

##### Arguments

`class`

  pointer to the struct class that this device was registered with

`devt`

  the dev_t of the device that was previously registered

##### Description

This call unregisters and cleans up a device that was created with a call to `device_create`.

#### LINUX

Kernel Hackers Manual January 2008
device_rename
9
2.6.24-rc6-git8

#### device_rename

renames a device

##### Synopsis

       int device_rename
       struct device * dev
       char * new_name

##### Arguments

`dev`

  the pointer to the struct device to be renamed

`new_name`

  the new name of the device

#### LINUX

Kernel Hackers Manual January 2008
device_move
9
2.6.24-rc6-git8

#### device_move

moves a device to a new parent

##### Synopsis

       int device_move
       struct device * dev
       struct device * new_parent

##### Arguments

`dev`

  the pointer to the struct device to be moved

`new_parent`

  the new parent of the device (can by NULL)

#### LINUX

Kernel Hackers Manual January 2008
class_create
9
2.6.24-rc6-git8

#### class_create

create a struct class structure

##### Synopsis

       struct class * class_create
       struct module * owner
       const char * name

##### Arguments

`owner`

  pointer to the module that is to own this struct class

`name`

  pointer to a string for the name of this class.

##### Description

This is used to create a struct class pointer that can then be used in calls to `class_device_create`.

Note, the pointer created here is to be destroyed when finished by making a call to `class_destroy`.

#### LINUX

Kernel Hackers Manual January 2008
class_destroy
9
2.6.24-rc6-git8

#### class_destroy

destroys a struct class structure

##### Synopsis

       void class_destroy
       struct class * cls

##### Arguments

`cls`

  pointer to the struct class that is to be destroyed

##### Description

Note, the pointer to be destroyed must have been created with a call to `class_create`.

#### LINUX

Kernel Hackers Manual January 2008
class_device_create
9
2.6.24-rc6-git8

#### class_device_create

creates a class device and registers it with sysfs

##### Synopsis

       struct class_device * class_device_create
       struct class * cls
       struct class_device * parent
       dev_t devt
       struct device * device
       const char * fmt
        ...

##### Arguments

`cls`

  pointer to the struct class that this device should be registered to.

`parent`

  pointer to the parent struct class_device of this new device, if any.

`devt`

  the dev_t for the char device to be added.

`device`

  a pointer to a struct device that is assiociated with this class device.

`fmt`

  string for the class device's name

`...`

  variable arguments

##### Description

This function can be used by char device classes. A struct class_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 class_device is passed in, the newly created struct class_device will be a child of that device in sysfs. The pointer to the struct class_device will be returned from the call. Any further sysfs files that might be required can be created using this pointer.

##### Note

the struct class passed to this function must have previously been created with a call to `class_create`.

#### LINUX

Kernel Hackers Manual January 2008
class_device_destroy
9
2.6.24-rc6-git8

#### class_device_destroy

removes a class device that was created with `class_device_create`

##### Synopsis

       void class_device_destroy
       struct class * cls
       dev_t devt

##### Arguments

`cls`

  the pointer to the struct class that this device was registered * with.

`devt`

  the dev_t of the device that was previously registered.

##### Description

This call unregisters and cleans up a class device that was created with a call to `class_device_create`

#### LINUX

Kernel Hackers Manual January 2008
request_firmware
9
2.6.24-rc6-git8

#### request_firmware

send firmware request and wait for it

##### Synopsis

       int request_firmware
       const struct firmware ** firmware_p
       const char * name
       struct device * device

##### Arguments

`firmware_p`

  pointer to firmware image

`name`

  name of firmware file

`device`

  device for which firmware is being loaded

##### Description

`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.

#### LINUX

Kernel Hackers Manual January 2008
release_firmware
9
2.6.24-rc6-git8

#### release_firmware

release the resource associated with a firmware image

##### Synopsis

       void release_firmware
       const struct firmware * fw

##### Arguments

`fw`

  firmware resource to release

#### LINUX

Kernel Hackers Manual January 2008
request_firmware_nowait
9
2.6.24-rc6-git8

#### request_firmware_nowait

##### Synopsis

       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

##### Arguments

`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.

##### Description

Asynchronous variant of `request_firmware` for contexts where it is not possible to sleep.

#### LINUX

Kernel Hackers Manual January 2008
transport_class_register
9
2.6.24-rc6-git8

#### transport_class_register

register an initial transport class

##### Synopsis

       int transport_class_register
       struct transport_class * tclass

##### Arguments

`tclass`

  a pointer to the transport class structure to be initialised

##### Description

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.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
transport_class_unregister
9
2.6.24-rc6-git8

#### transport_class_unregister

unregister a previously registered class

##### Synopsis

       void transport_class_unregister
       struct transport_class * tclass

##### Arguments

`tclass`

  The transport class to unregister

##### Description

Must be called prior to deallocating the memory for the transport class.

##### Description

Must be called prior to deallocating the memory for the transport class.

#### LINUX

Kernel Hackers Manual January 2008
anon_transport_class_register
9
2.6.24-rc6-git8

#### anon_transport_class_register

register an anonymous class

##### Synopsis

       int anon_transport_class_register
       struct anon_transport_class * atc

##### Arguments

`atc`

  The anon transport class to register

##### Description

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.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
anon_transport_class_unregister
9
2.6.24-rc6-git8

#### anon_transport_class_unregister

unregister an anon class

##### Synopsis

       void anon_transport_class_unregister
       struct anon_transport_class * atc

##### Arguments

`atc`

  Pointer to the anon transport class to unregister

##### Description

Must be called prior to deallocating the memory for the anon transport class.

##### Description

Must be called prior to deallocating the memory for the anon transport class.

#### LINUX

Kernel Hackers Manual January 2008
transport_setup_device
9
2.6.24-rc6-git8

#### transport_setup_device

declare a new dev for transport class association

##### Synopsis

       void transport_setup_device
       struct device * dev

##### Arguments

`dev`

  the generic device representing the entity being added

##### Description

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).

##### Description

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).

#### LINUX

Kernel Hackers Manual January 2008
transport_add_device
9
2.6.24-rc6-git8

#### transport_add_device

declare a new dev for transport class association

##### Synopsis

       void transport_add_device
       struct device * dev

##### Arguments

`dev`

  the generic device representing the entity being added

##### Description

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.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
transport_configure_device
9
2.6.24-rc6-git8

#### transport_configure_device

configure an already set up device

##### Synopsis

       void transport_configure_device
       struct device * dev

##### Arguments

`dev`

  generic device representing device to be configured

##### Description

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.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
transport_remove_device
9
2.6.24-rc6-git8

#### transport_remove_device

remove the visibility of a device

##### Synopsis

       void transport_remove_device
       struct device * dev

##### Arguments

`dev`

  generic device to remove

##### Description

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.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
transport_destroy_device
9
2.6.24-rc6-git8

#### transport_destroy_device

destroy a removed device

##### Synopsis

       void transport_destroy_device
       struct device * dev

##### Arguments

`dev`

  device to eliminate from the transport class.

##### Description

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.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
dma_pool_create
9
2.6.24-rc6-git8

#### dma_pool_create

Creates a pool of consistent memory blocks, for dma.

##### Synopsis

       struct dma_pool * dma_pool_create
       const char * name
       struct device * dev
       size_t size
       size_t align
       size_t allocation

##### Arguments

`name`

  name of pool, for diagnostics

`dev`

  device that will be doing the DMA

`size`

  size of the blocks in this pool.

`align`

  alignment requirement for blocks; must be a power of two

`allocation`

  returned blocks won't cross this boundary (or zero)

##### Context

!`in_interrupt`

##### Description

Returns a dma allocation pool with the requested characteristics, or null if one can't be created. Given one of these pools, `dma_pool_alloc` may be used to allocate memory. Such memory will all have consistent DMA mappings, accessible by the device and its driver without using cache flushing primitives. The actual size of blocks allocated may be larger than requested because of alignment.

If allocation is nonzero, objects returned from `dma_pool_alloc` won't cross that size boundary. This is useful for devices which have addressing restrictions on individual DMA transfers, such as not crossing boundaries of 4KBytes.

#### LINUX

Kernel Hackers Manual January 2008
dma_pool_destroy
9
2.6.24-rc6-git8

#### dma_pool_destroy

destroys a pool of dma memory blocks.

##### Synopsis

       void dma_pool_destroy
       struct dma_pool * pool

##### Arguments

`pool`

  dma pool that will be destroyed

##### Context

!`in_interrupt`

##### Description

Caller guarantees that no more memory from the pool is in use, and that nothing will try to use the pool after this call.

#### LINUX

Kernel Hackers Manual January 2008
dma_pool_alloc
9
2.6.24-rc6-git8

#### dma_pool_alloc

get a block of consistent memory

##### Synopsis

       void * dma_pool_alloc
       struct dma_pool * pool
       gfp_t mem_flags
       dma_addr_t * handle

##### Arguments

`pool`

  dma pool that will produce the block

`mem_flags`

  GFP_* bitmask

`handle`

  pointer to dma address of block

##### Description

This returns the kernel virtual address of a currently unused block, and reports its dma address through the handle. If such a memory block can't be allocated, null is returned.

#### LINUX

Kernel Hackers Manual January 2008
dma_pool_free
9
2.6.24-rc6-git8

#### dma_pool_free

put block back into dma pool

##### Synopsis

       void dma_pool_free
       struct dma_pool * pool
       void * vaddr
       dma_addr_t dma

##### Arguments

`pool`

  the dma pool holding the block

`vaddr`

  virtual address of block

`dma`

  dma address of block

##### Description

Caller promises neither device nor driver will again touch this block unless it is first re-allocated.

#### LINUX

Kernel Hackers Manual January 2008
dmam_pool_create
9
2.6.24-rc6-git8

#### dmam_pool_create

Managed `dma_pool_create`

##### Synopsis

       struct dma_pool * dmam_pool_create
       const char * name
       struct device * dev
       size_t size
       size_t align
       size_t allocation

##### Arguments

`name`

  name of pool, for diagnostics

`dev`

  device that will be doing the DMA

`size`

  size of the blocks in this pool.

`align`

  alignment requirement for blocks; must be a power of two

`allocation`

  returned blocks won't cross this boundary (or zero)

##### Description

Managed `dma_pool_create`. DMA pool created with this function is automatically destroyed on driver detach.

#### LINUX

Kernel Hackers Manual January 2008
dmam_pool_destroy
9
2.6.24-rc6-git8

#### dmam_pool_destroy

Managed `dma_pool_destroy`

##### Synopsis

       void dmam_pool_destroy
       struct dma_pool * pool

##### Arguments

`pool`

  dma pool that will be destroyed

##### Description

Managed `dma_pool_destroy`.

#### LINUX

Kernel Hackers Manual January 2008
sysdev_driver_register
9
2.6.24-rc6-git8

#### sysdev_driver_register

Register auxillary driver

##### Synopsis

       int sysdev_driver_register
       struct sysdev_class * cls
       struct sysdev_driver * drv

##### Arguments

`cls`

  Device class driver belongs to.

`drv`

  Driver.

##### Description

`drv` is inserted into `cls`->drivers to be called on each operation on devices of that class. The refcount of `cls` is incremented.

#### LINUX

Kernel Hackers Manual January 2008
sysdev_driver_unregister
9
2.6.24-rc6-git8

#### sysdev_driver_unregister

Remove an auxillary driver.

##### Synopsis

       void sysdev_driver_unregister
       struct sysdev_class * cls
       struct sysdev_driver * drv

##### Arguments

`cls`

  Class driver belongs to.

`drv`

  Driver.

#### LINUX

Kernel Hackers Manual January 2008
sysdev_register
9
2.6.24-rc6-git8

#### sysdev_register

add a system device to the tree

##### Synopsis

       int sysdev_register
       struct sys_device * sysdev

##### Arguments

`sysdev`

  device in question

#### LINUX

Kernel Hackers Manual January 2008
platform_get_resource
9
2.6.24-rc6-git8

#### platform_get_resource

get a resource for a device

##### Synopsis

       struct resource * platform_get_resource
       struct platform_device * dev
       unsigned int type
       unsigned int num

##### Arguments

`dev`

  platform device

`type`

  resource type

`num`

  resource index

#### LINUX

Kernel Hackers Manual January 2008
platform_get_irq
9
2.6.24-rc6-git8

#### platform_get_irq

get an IRQ for a device

##### Synopsis

       int platform_get_irq
       struct platform_device * dev
       unsigned int num

##### Arguments

`dev`

  platform device

`num`

  IRQ number index

#### LINUX

Kernel Hackers Manual January 2008
platform_get_resource_byname
9
2.6.24-rc6-git8

#### platform_get_resource_byname

get a resource for a device by name

##### Synopsis

       struct resource * platform_get_resource_byname
       struct platform_device * dev
       unsigned int type
       char * name

##### Arguments

`dev`

  platform device

`type`

  resource type

`name`

  resource name

#### LINUX

Kernel Hackers Manual January 2008
platform_get_irq_byname
9
2.6.24-rc6-git8

#### platform_get_irq_byname

get an IRQ for a device

##### Synopsis

       int platform_get_irq_byname
       struct platform_device * dev
       char * name

##### Arguments

`dev`

  platform device

`name`

  IRQ name

#### LINUX

Kernel Hackers Manual January 2008
platform_add_devices
9
2.6.24-rc6-git8

#### platform_add_devices

add a numbers of platform devices

##### Synopsis

       int platform_add_devices
       struct platform_device ** devs
       int num

##### Arguments

`devs`

  array of platform devices to add

`num`

  number of platform devices in array

#### LINUX

Kernel Hackers Manual January 2008
platform_device_put
9
2.6.24-rc6-git8

#### platform_device_put

##### Synopsis

       void platform_device_put
       struct platform_device * pdev

##### Arguments

`pdev`

  platform device to free

##### Description

Free all memory associated with a platform device. This function must _only_ be externally called in error cases. All other usage is a bug.

#### LINUX

Kernel Hackers Manual January 2008
platform_device_alloc
9
2.6.24-rc6-git8

#### platform_device_alloc

##### Synopsis

       struct platform_device * platform_device_alloc
       const char * name
       int id

##### Arguments

`name`

  base name of the device we're adding

`id`

  instance id

##### Description

Create a platform device object which can have other objects attached to it, and which will have attached objects freed when it is released.

#### LINUX

Kernel Hackers Manual January 2008
platform_device_add_resources
9
2.6.24-rc6-git8

#### platform_device_add_resources

##### Synopsis

       int platform_device_add_resources
       struct platform_device * pdev
       struct resource * res
       unsigned int num

##### Arguments

`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

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
platform_device_add_data
9
2.6.24-rc6-git8

#### platform_device_add_data

##### Synopsis

       int platform_device_add_data
       struct platform_device * pdev
       const void * data
       size_t size

##### Arguments

`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

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
platform_device_add
9
2.6.24-rc6-git8

#### platform_device_add

add a platform device to device hierarchy

##### Synopsis

       int platform_device_add
       struct platform_device * pdev

##### Arguments

`pdev`

  platform device we're adding

##### Description

This is part 2 of `platform_device_register`, though may be called separately _iff_ pdev was allocated by `platform_device_alloc`.

#### LINUX

Kernel Hackers Manual January 2008
platform_device_del
9
2.6.24-rc6-git8

#### platform_device_del

remove a platform-level device

##### Synopsis

       void platform_device_del
       struct platform_device * pdev

##### Arguments

`pdev`

  platform device we're removing

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
platform_device_register
9
2.6.24-rc6-git8

#### platform_device_register

add a platform-level device

##### Synopsis

       int platform_device_register
       struct platform_device * pdev

##### Arguments

`pdev`

  platform device we're adding

#### LINUX

Kernel Hackers Manual January 2008
platform_device_unregister
9
2.6.24-rc6-git8

#### platform_device_unregister

unregister a platform-level device

##### Synopsis

       void platform_device_unregister
       struct platform_device * pdev

##### Arguments

`pdev`

  platform device we're unregistering

##### Description

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`.

#### LINUX

Kernel Hackers Manual January 2008
platform_device_register_simple
9
2.6.24-rc6-git8

#### platform_device_register_simple

##### Synopsis

       struct platform_device * platform_device_register_simple
       char * name
       int id
       struct resource * res
       unsigned int num

##### Arguments

`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

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
platform_driver_register
9
2.6.24-rc6-git8

#### platform_driver_register

##### Synopsis

       int platform_driver_register
       struct platform_driver * drv

##### Arguments

`drv`

  platform driver structure

#### LINUX

Kernel Hackers Manual January 2008
platform_driver_unregister
9
2.6.24-rc6-git8

#### platform_driver_unregister

##### Synopsis

       void platform_driver_unregister
       struct platform_driver * drv

##### Arguments

`drv`

  platform driver structure

#### LINUX

Kernel Hackers Manual January 2008
platform_driver_probe
9
2.6.24-rc6-git8

#### platform_driver_probe

register driver for non-hotpluggable device

##### Synopsis

       int __init_or_module platform_driver_probe
       struct platform_driver * drv
       int (*probe)
         struct platform_device *

##### Arguments

`drv`

  platform driver structure

`probe`

  the driver probe routine, probably from an __init section

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
bus_for_each_dev
9
2.6.24-rc6-git8

#### bus_for_each_dev

device iterator.

##### Synopsis

       int bus_for_each_dev
       struct bus_type * bus
       struct device * start
       void * data
       int (*fn)
         struct device *, void *

##### Arguments

`bus`

  bus type.

`start`

  device to start iterating from.

`data`

  data for the callback.

`fn`

  function to be called for each device.

##### Description

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.

##### NOTE

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, and increment the reference count in the supplied callback.

#### LINUX

Kernel Hackers Manual January 2008
bus_find_device
9
2.6.24-rc6-git8

#### bus_find_device

device iterator for locating a particular device.

##### Synopsis

       struct device * bus_find_device
       struct bus_type * bus
       struct device * start
       void * data
       int (*match)
         struct device *, void *

##### Arguments

`bus`

  bus type

`start`

  Device to begin with

`data`

  Data to pass to match function

`match`

  Callback function to check device

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
bus_for_each_drv
9
2.6.24-rc6-git8

#### bus_for_each_drv

driver iterator

##### Synopsis

       int bus_for_each_drv
       struct bus_type * bus
       struct device_driver * start
       void * data
       int (*fn)
         struct device_driver *, void *

##### Arguments

`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.

##### Description

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.

##### NOTE

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.

#### LINUX

Kernel Hackers Manual January 2008
bus_rescan_devices
9
2.6.24-rc6-git8

#### bus_rescan_devices

rescan devices on the bus for possible drivers

##### Synopsis

       int bus_rescan_devices
       struct bus_type * bus

##### Arguments

`bus`

  the bus to scan.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
device_reprobe
9
2.6.24-rc6-git8

#### device_reprobe

remove driver for a device and probe for a new driver

##### Synopsis

       int device_reprobe
       struct device * dev

##### Arguments

`dev`

  the device to reprobe

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
bus_register
9
2.6.24-rc6-git8

#### bus_register

register a bus with the system.

##### Synopsis

       int bus_register
       struct bus_type * bus

##### Arguments

`bus`

  bus.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
bus_unregister
9
2.6.24-rc6-git8

#### bus_unregister

remove a bus from the system

##### Synopsis

       void bus_unregister
       struct bus_type * bus

##### Arguments

`bus`

  bus.

##### Description

Unregister the child subsystems and the bus itself. Finally, we call `bus_put` to release the refcount

### Device Drivers Power Management

#### LINUX

Kernel Hackers Manual January 2008
device_resume
9
2.6.24-rc6-git8

#### device_resume

Restore state of each device in system.

##### Synopsis

       void device_resume
        void

##### Arguments

`void`

  no arguments

##### Description

Walk the dpm_off list, remove each entry, resume the device, then add it to the dpm_active list.

#### LINUX

Kernel Hackers Manual January 2008
device_power_up
9
2.6.24-rc6-git8

#### device_power_up

Turn on all devices that need special attention.

##### Synopsis

       void device_power_up
        void

##### Arguments

`void`

  no arguments

##### Description

Power on system devices then devices that required we shut them down with interrupts disabled. Called with interrupts disabled.

#### LINUX

Kernel Hackers Manual January 2008
device_suspend
9
2.6.24-rc6-git8

#### device_suspend

Save state and stop all devices in system.

##### Synopsis

       int device_suspend
       pm_message_t state

##### Arguments

`state`

  Power state to put each device in.

##### Description

Walk the dpm_active list, call ->`suspend` for each device, and move it to the dpm_off list.

(For historical reasons, if it returns -EAGAIN, that used to mean that the device would be called again with interrupts disabled. These days, we use the `suspend_late` callback for that, so we print a warning and consider it an error).

If we get a different error, try and back out.

If we hit a failure with any of the devices, call `device_resume` above to bring the suspended devices back to life.

#### LINUX

Kernel Hackers Manual January 2008
device_power_down
9
2.6.24-rc6-git8

#### device_power_down

Shut down special devices.

##### Synopsis

       int device_power_down
       pm_message_t state

##### Arguments

`state`

  Power state to enter.

##### Description

Walk the dpm_off_irq list, calling ->`power_down` for each device that couldn't power down the device with interrupts enabled. When we're done, power down system devices.

### Device Drivers ACPI Support

#### LINUX

Kernel Hackers Manual January 2008
acpi_bus_register_driver
9
2.6.24-rc6-git8

#### acpi_bus_register_driver

register a driver with the ACPI bus

##### Synopsis

       int acpi_bus_register_driver
       struct acpi_driver * driver

##### Arguments

`driver`

  driver being registered

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
acpi_bus_unregister_driver
9
2.6.24-rc6-git8

#### acpi_bus_unregister_driver

unregisters a driver with the APIC bus

##### Synopsis

       void acpi_bus_unregister_driver
       struct acpi_driver * driver

##### Arguments

`driver`

  driver to unregister

##### Description

Unregisters a driver with the ACPI bus. Searches the namespace for all devices that match the driver's criteria and unbinds.

#### LINUX

Kernel Hackers Manual January 2008
acpi_bus_driver_init
9
2.6.24-rc6-git8

#### acpi_bus_driver_init

add a device to a driver

##### Synopsis

       int acpi_bus_driver_init
       struct acpi_device * device
       struct acpi_driver * driver

##### Arguments

`device`

  the device to add and initialize

`driver`

  driver for the device

##### Description

Used to initialize a device via its device driver. Called whenever a driver is bound to a device. Invokes the driver's `add` ops.

### Device drivers PnP support

#### LINUX

Kernel Hackers Manual January 2008
pnp_register_protocol
9
2.6.24-rc6-git8

#### pnp_register_protocol

adds a pnp protocol to the pnp layer

##### Synopsis

       int pnp_register_protocol
       struct pnp_protocol * protocol

##### Arguments

`protocol`

  pointer to the corresponding pnp_protocol structure

##### Ex protocols

ISAPNP, PNPBIOS, etc

#### LINUX

Kernel Hackers Manual January 2008
pnp_unregister_protocol
9
2.6.24-rc6-git8

#### pnp_unregister_protocol

removes a pnp protocol from the pnp layer

##### Synopsis

       void pnp_unregister_protocol
       struct pnp_protocol * protocol

##### Arguments

`protocol`

  pointer to the corresponding pnp_protocol structure

#### LINUX

Kernel Hackers Manual January 2008
pnp_request_card_device
9
2.6.24-rc6-git8

#### pnp_request_card_device

Searches for a PnP device under the specified card

##### Synopsis

       struct pnp_dev * pnp_request_card_device
       struct pnp_card_link * clink
       const char * id
       struct pnp_dev * from

##### Arguments

`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.

#### LINUX

Kernel Hackers Manual January 2008
pnp_release_card_device
9
2.6.24-rc6-git8

#### pnp_release_card_device

call this when the driver no longer needs the device

##### Synopsis

       void pnp_release_card_device
       struct pnp_dev * dev

##### Arguments

`dev`

  pointer to the PnP device stucture

#### LINUX

Kernel Hackers Manual January 2008
pnp_register_card_driver
9
2.6.24-rc6-git8

#### pnp_register_card_driver

registers a PnP card driver with the PnP Layer

##### Synopsis

       int pnp_register_card_driver
       struct pnp_card_driver * drv

##### Arguments

`drv`

  pointer to the driver to register

#### LINUX

Kernel Hackers Manual January 2008
pnp_unregister_card_driver
9
2.6.24-rc6-git8

#### pnp_unregister_card_driver

unregisters a PnP card driver from the PnP Layer

##### Synopsis

       void pnp_unregister_card_driver
       struct pnp_card_driver * drv

##### Arguments

`drv`

  pointer to the driver to unregister

#### LINUX

Kernel Hackers Manual January 2008
pnp_add_id
9
2.6.24-rc6-git8

#### pnp_add_id

adds an EISA id to the specified device

##### Synopsis

       int pnp_add_id
       struct pnp_id * id
       struct pnp_dev * dev

##### Arguments

`id`

  pointer to a pnp_id structure

`dev`

  pointer to the desired device

#### LINUX

Kernel Hackers Manual January 2008
pnp_init_resource_table
9
2.6.24-rc6-git8

#### pnp_init_resource_table

Resets a resource table to default values.

##### Synopsis

       void pnp_init_resource_table
       struct pnp_resource_table * table

##### Arguments

`table`

  pointer to the desired resource table

#### LINUX

Kernel Hackers Manual January 2008
pnp_manual_config_dev
9
2.6.24-rc6-git8

#### pnp_manual_config_dev

Disables Auto Config and Manually sets the resource table

##### Synopsis

       int pnp_manual_config_dev
       struct pnp_dev * dev
       struct pnp_resource_table * res
       int mode

##### Arguments

`dev`

  pointer to the desired device

`res`

  pointer to the new resource config

`mode`

  0 or PNP_CONFIG_FORCE

##### Description

This function can be used by drivers that want to manually set thier resources.

#### LINUX

Kernel Hackers Manual January 2008
pnp_start_dev
9
2.6.24-rc6-git8

#### pnp_start_dev

low-level start of the PnP device

##### Synopsis

       int pnp_start_dev
       struct pnp_dev * dev

##### Arguments

`dev`

  pointer to the desired device

##### Description

assumes that resources have already been allocated

#### LINUX

Kernel Hackers Manual January 2008
pnp_stop_dev
9
2.6.24-rc6-git8

#### pnp_stop_dev

low-level disable of the PnP device

##### Synopsis

       int pnp_stop_dev
       struct pnp_dev * dev

##### Arguments

`dev`

  pointer to the desired device

##### Description

does not free resources

#### LINUX

Kernel Hackers Manual January 2008
pnp_activate_dev
9
2.6.24-rc6-git8

#### pnp_activate_dev

activates a PnP device for use

##### Synopsis

       int pnp_activate_dev
       struct pnp_dev * dev

##### Arguments

`dev`

  pointer to the desired device

##### Description

does not validate or set resources so be careful.

#### LINUX

Kernel Hackers Manual January 2008
pnp_disable_dev
9
2.6.24-rc6-git8

#### pnp_disable_dev

disables device

##### Synopsis

       int pnp_disable_dev
       struct pnp_dev * dev

##### Arguments

`dev`

  pointer to the desired device

##### Description

inform the correct pnp protocol so that resources can be used by other devices

#### LINUX

Kernel Hackers Manual January 2008
pnp_resource_change
9
2.6.24-rc6-git8

#### pnp_resource_change

change one resource

##### Synopsis

       void pnp_resource_change
       struct resource * resource
       resource_size_t start
       resource_size_t size

##### Arguments

`resource`

  pointer to resource to be changed

`start`

  start of region

`size`

  size of region

#### LINUX

Kernel Hackers Manual January 2008
pnp_is_active
9
2.6.24-rc6-git8

#### pnp_is_active

Determines if a device is active based on its current

##### Synopsis

       int pnp_is_active
       struct pnp_dev * dev

##### Arguments

`dev`

  pointer to the desired PnP device

##### Description

resources

### Userspace IO devices

#### LINUX

Kernel Hackers Manual January 2008
uio_event_notify
9
2.6.24-rc6-git8

#### uio_event_notify

trigger an interrupt event

##### Synopsis

       void uio_event_notify
       struct uio_info * info

##### Arguments

`info`

  UIO device capabilities

#### LINUX

Kernel Hackers Manual January 2008
__uio_register_device
9
2.6.24-rc6-git8

#### __uio_register_device

register a new userspace IO device

##### Synopsis

       int __uio_register_device
       struct module * owner
       struct device * parent
       struct uio_info * info

##### Arguments

`owner`

  module that creates the new device

`parent`

  parent device

`info`

  UIO device capabilities

##### Description

returns zero on success or a negative error code.

#### LINUX

Kernel Hackers Manual January 2008
uio_unregister_device
9
2.6.24-rc6-git8

#### uio_unregister_device

unregister a industrial IO device

##### Synopsis

       void uio_unregister_device
       struct uio_info * info

##### Arguments

`info`

  UIO device capabilities

#### LINUX

Kernel Hackers Manual January 2008
struct uio_mem
9
2.6.24-rc6-git8

#### struct uio_mem

description of a UIO memory region

##### Synopsis

    struct uio_mem {
      struct kobject kobj;
      unsigned long addr;
      unsigned long size;
      int memtype;
      void __iomem * internal_addr;
    };

##### Members

kobj

  kobject for this mapping

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

#### LINUX

Kernel Hackers Manual January 2008
struct uio_info
9
2.6.24-rc6-git8

#### struct uio_info

UIO device capabilities

##### Synopsis

    struct uio_info {
      struct uio_device * uio_dev;
      char * name;
      char * version;
      struct uio_mem mem[MAX_UIO_MAPS];
      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);
    };

##### Members

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

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

## Block Devices

### LINUX

Kernel Hackers Manual January 2008
blk_get_backing_dev_info
9
2.6.24-rc6-git8

### blk_get_backing_dev_info

get the address of a queue's backing_dev_info

#### Synopsis

       struct backing_dev_info * blk_get_backing_dev_info
       struct block_device * bdev

#### Arguments

`bdev`

  device

#### Description

Locates the passed device's request queue and returns the address of its backing_dev_info

Will return NULL if the request queue cannot be located.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_prep_rq
9
2.6.24-rc6-git8

### blk_queue_prep_rq

set a prepare_request function for queue

#### Synopsis

       void blk_queue_prep_rq
       struct request_queue * q
       prep_rq_fn * pfn

#### Arguments

`q`

  queue

`pfn`

  prepare_request function

#### Description

It's possible for a queue to register a prepare_request callback which is invoked before the request is handed to the request_fn. The goal of the function is to prepare a request for I/O, it can be used to build a cdb from the request data for instance.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_merge_bvec
9
2.6.24-rc6-git8

### blk_queue_merge_bvec

set a merge_bvec function for queue

#### Synopsis

       void blk_queue_merge_bvec
       struct request_queue * q
       merge_bvec_fn * mbfn

#### Arguments

`q`

  queue

`mbfn`

  merge_bvec_fn

#### Description

Usually queues have static limitations on the max sectors or segments that we can put in a request. Stacking drivers may have some settings that are dynamic, and thus we have to query the queue whether it is ok to add a new bio_vec to a bio at a given offset or not. If the block device has such limitations, it needs to register a merge_bvec_fn to control the size of bio's sent to it. Note that a block device *must* allow a single page to be added to an empty bio. The block device driver may want to use the `bio_split` function to deal with these bio's. By default no merge_bvec_fn is defined for a queue, and only the fixed limits are honored.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_make_request
9
2.6.24-rc6-git8

### blk_queue_make_request

define an alternate make_request function for a device

#### Synopsis

       void blk_queue_make_request
       struct request_queue * q
       make_request_fn * mfn

#### Arguments

`q`

  the request queue for the device to be affected

`mfn`

  the alternate make_request function

#### Description

The normal way for &struct bios to be passed to a device driver is for them to be collected into requests on a request queue, and then to allow the device driver to select requests off that queue when it is ready. This works well for many block devices. However some block devices (typically virtual devices such as md or lvm) do not benefit from the processing on the request queue, and are served best by having the requests passed directly to them. This can be achieved by providing a function to `blk_queue_make_request`.

#### Caveat

The driver that does this *must* be able to deal appropriately with buffers in highmemory. This can be accomplished by either calling `__bio_kmap_atomic` to get a temporary kernel mapping, or by calling `blk_queue_bounce` to create a buffer in normal memory.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_ordered
9
2.6.24-rc6-git8

### blk_queue_ordered

does this queue support ordered writes

#### Synopsis

       int blk_queue_ordered
       struct request_queue * q
       unsigned ordered
       prepare_flush_fn * prepare_flush_fn

#### Arguments

`q`

  the request queue

`ordered`

  one of QUEUE_ORDERED_*

`prepare_flush_fn`

  rq setup helper for cache flush ordered writes

#### Description

For journalled file systems, doing ordered writes on a commit block instead of explicitly doing wait_on_buffer (which is bad for performance) can be a big win. Block drivers supporting this feature should call this function and indicate so.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_bounce_limit
9
2.6.24-rc6-git8

### blk_queue_bounce_limit

set bounce buffer limit for queue

#### Synopsis

       void blk_queue_bounce_limit
       struct request_queue * q
       u64 dma_addr

#### Arguments

`q`

  the request queue for the device

`dma_addr`

  bus address limit

#### Description

Different hardware can have different requirements as to what pages it can do I/O directly to. A low level driver can call blk_queue_bounce_limit to have lower memory pages allocated as bounce buffers for doing I/O to pages residing above `page`.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_max_sectors
9
2.6.24-rc6-git8

### blk_queue_max_sectors

set max sectors for a request for this queue

#### Synopsis

       void blk_queue_max_sectors
       struct request_queue * q
       unsigned int max_sectors

#### Arguments

`q`

  the request queue for the device

`max_sectors`

  max sectors in the usual 512b unit

#### Description

Enables a low level driver to set an upper limit on the size of received requests.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_max_phys_segments
9
2.6.24-rc6-git8

### blk_queue_max_phys_segments

set max phys segments for a request for this queue

#### Synopsis

       void blk_queue_max_phys_segments
       struct request_queue * q
       unsigned short max_segments

#### Arguments

`q`

  the request queue for the device

`max_segments`

  max number of segments

#### Description

Enables a low level driver to set an upper limit on the number of physical data segments in a request. This would be the largest sized scatter list the driver could handle.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_max_hw_segments
9
2.6.24-rc6-git8

### blk_queue_max_hw_segments

set max hw segments for a request for this queue

#### Synopsis

       void blk_queue_max_hw_segments
       struct request_queue * q
       unsigned short max_segments

#### Arguments

`q`

  the request queue for the device

`max_segments`

  max number of segments

#### Description

Enables a low level driver to set an upper limit on the number of hw data segments in a request. This would be the largest number of address/length pairs the host adapter can actually give as once to the device.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_max_segment_size
9
2.6.24-rc6-git8

### blk_queue_max_segment_size

set max segment size for blk_rq_map_sg

#### Synopsis

       void blk_queue_max_segment_size
       struct request_queue * q
       unsigned int max_size

#### Arguments

`q`

  the request queue for the device

`max_size`

  max size of segment in bytes

#### Description

Enables a low level driver to set an upper limit on the size of a coalesced segment

### LINUX

Kernel Hackers Manual January 2008
blk_queue_hardsect_size
9
2.6.24-rc6-git8

### blk_queue_hardsect_size

set hardware sector size for the queue

#### Synopsis

       void blk_queue_hardsect_size
       struct request_queue * q
       unsigned short size

#### Arguments

`q`

  the request queue for the device

`size`

  the hardware sector size, in bytes

#### Description

This should typically be set to the lowest possible sector size that the hardware can operate on (possible without reverting to even internal read-modify-write operations). Usually the default of 512 covers most hardware.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_stack_limits
9
2.6.24-rc6-git8

### blk_queue_stack_limits

inherit underlying queue limits for stacked drivers

#### Synopsis

       void blk_queue_stack_limits
       struct request_queue * t
       struct request_queue * b

#### Arguments

`t`

  the stacking driver (top)

`b`

  the underlying device (bottom)

### LINUX

Kernel Hackers Manual January 2008
blk_queue_segment_boundary
9
2.6.24-rc6-git8

### blk_queue_segment_boundary

set boundary rules for segment merging

#### Synopsis

       void blk_queue_segment_boundary
       struct request_queue * q
       unsigned long mask

#### Arguments

`q`

  the request queue for the device

`mask`

  the memory boundary mask

### LINUX

Kernel Hackers Manual January 2008
blk_queue_dma_alignment
9
2.6.24-rc6-git8

### blk_queue_dma_alignment

set dma length and memory alignment

#### Synopsis

       void blk_queue_dma_alignment
       struct request_queue * q
       int mask

#### Arguments

`q`

  the request queue for the device

`mask`

  alignment mask

#### description

set required memory and length aligment for direct dma transactions. this is used when buiding direct io requests for the queue.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_find_tag
9
2.6.24-rc6-git8

### blk_queue_find_tag

find a request by its tag and queue

#### Synopsis

       struct request * blk_queue_find_tag
       struct request_queue * q
       int tag

#### Arguments

`q`

  The request queue for the device

`tag`

  The tag of the request

#### Notes

Should be used when a device returns a tag and you want to match it with a request.

no locks need be held.

### LINUX

Kernel Hackers Manual January 2008
blk_free_tags
9
2.6.24-rc6-git8

### blk_free_tags

release a given set of tag maintenance info

#### Synopsis

       void blk_free_tags
       struct blk_queue_tag * bqt

#### Arguments

`bqt`

  the tag map to free

#### Description

For externally managed `bqt`@ frees the map. Callers of this function must guarantee to have released all the queues that might have been using this tag map.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_free_tags
9
2.6.24-rc6-git8

### blk_queue_free_tags

release tag maintenance info

#### Synopsis

       void blk_queue_free_tags
       struct request_queue * q

#### Arguments

`q`

  the request queue for the device

#### Notes

This is used to disabled tagged queuing to a device, yet leave queue in function.

### LINUX

Kernel Hackers Manual January 2008
blk_init_tags
9
2.6.24-rc6-git8

### blk_init_tags

initialize the tag info for an external tag map

#### Synopsis

       struct blk_queue_tag * blk_init_tags
       int depth

#### Arguments

`depth`

  the maximum queue depth supported

### LINUX

Kernel Hackers Manual January 2008
blk_queue_init_tags
9
2.6.24-rc6-git8

### blk_queue_init_tags

initialize the queue tag info

#### Synopsis

       int blk_queue_init_tags
       struct request_queue * q
       int depth
       struct blk_queue_tag * tags

#### Arguments

`q`

  the request queue for the device

`depth`

  the maximum queue depth supported

`tags`

  the tag to use

### LINUX

Kernel Hackers Manual January 2008
blk_queue_resize_tags
9
2.6.24-rc6-git8

### blk_queue_resize_tags

change the queueing depth

#### Synopsis

       int blk_queue_resize_tags
       struct request_queue * q
       int new_depth

#### Arguments

`q`

  the request queue for the device

`new_depth`

  the new max command queueing depth

#### Notes

Must be called with the queue lock held.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_end_tag
9
2.6.24-rc6-git8

### blk_queue_end_tag

end tag operations for a request

#### Synopsis

       void blk_queue_end_tag
       struct request_queue * q
       struct request * rq

#### Arguments

`q`

  the request queue for the device

`rq`

  the request that has completed

#### Description

Typically called when `end_that_request_first` returns 0, meaning all transfers have been done for a request. It's important to call this function before `end_that_request_last`, as that will put the request back on the free list thus corrupting the internal tag list.

#### Notes

queue lock must be held.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_start_tag
9
2.6.24-rc6-git8

### blk_queue_start_tag

find a free tag and assign it

#### Synopsis

       int blk_queue_start_tag
       struct request_queue * q
       struct request * rq

#### Arguments

`q`

  the request queue for the device

`rq`

  the block request that needs tagging

#### Description

This can either be used as a stand-alone helper, or possibly be assigned as the queue &prep_rq_fn (in which case &struct request automagically gets a tag assigned). Note that this function assumes that any type of request can be queued! if this is not true for your device, you must check the request type before calling this function. The request will also be removed from the request queue, so it's the drivers responsibility to readd it if it should need to be restarted for some reason.

#### Notes

queue lock must be held.

### LINUX

Kernel Hackers Manual January 2008
blk_queue_invalidate_tags
9
2.6.24-rc6-git8

### blk_queue_invalidate_tags

invalidate all pending tags

#### Synopsis

       void blk_queue_invalidate_tags
       struct request_queue * q

#### Arguments

`q`

  the request queue for the device

#### Description

Hardware conditions may dictate a need to stop all pending requests. In this case, we will safely clear the block side of the tag queue and readd all requests to the request queue in the right order.

#### Notes

queue lock must be held.

### LINUX

Kernel Hackers Manual January 2008
generic_unplug_device
9
2.6.24-rc6-git8

### generic_unplug_device

fire a request queue

#### Synopsis

       void generic_unplug_device
       struct request_queue * q

#### Arguments

`q`

  The &struct request_queue in question

#### Description

Linux uses plugging to build bigger requests queues before letting the device have at them. If a queue is plugged, the I/O scheduler is still adding and merging requests on the queue. Once the queue gets unplugged, the request_fn defined for the queue is invoked and transfers started.

### LINUX

Kernel Hackers Manual January 2008
blk_start_queue
9
2.6.24-rc6-git8

### blk_start_queue

restart a previously stopped queue

#### Synopsis

       void blk_start_queue
       struct request_queue * q

#### Arguments

`q`

  The &struct request_queue in question

#### Description

`blk_start_queue` will clear the stop flag on the queue, and call the request_fn for the queue if it was in a stopped state when entered. Also see `blk_stop_queue`. Queue lock must be held.

### LINUX

Kernel Hackers Manual January 2008
blk_stop_queue
9
2.6.24-rc6-git8

### blk_stop_queue

stop a queue

#### Synopsis

       void blk_stop_queue
       struct request_queue * q

#### Arguments

`q`

  The &struct request_queue in question

#### Description

The Linux block layer assumes that a block driver will consume all entries on the request queue when the request_fn strategy is called. Often this will not happen, because of hardware limitations (queue depth settings). If a device driver gets a 'queue full' response, or if it simply chooses not to queue more I/O at one point, it can call this function to prevent the request_fn from being called until the driver has signalled it's ready to go again. This happens by calling `blk_start_queue` to restart queue operations. Queue lock must be held.

### LINUX

Kernel Hackers Manual January 2008
blk_sync_queue
9
2.6.24-rc6-git8

### blk_sync_queue

cancel any pending callbacks on a queue

#### Synopsis

       void blk_sync_queue
       struct request_queue * q

#### Arguments

`q`

  the queue

#### Description

The block layer may perform asynchronous callback activity on a queue, such as calling the unplug function after a timeout. A block device may call blk_sync_queue to ensure that any such activity is cancelled, thus allowing it to release resources that the callbacks might use. The caller must already have made sure that its ->make_request_fn will not re-add plugging prior to calling this function.

### LINUX

Kernel Hackers Manual January 2008
blk_run_queue
9
2.6.24-rc6-git8

### blk_run_queue

run a single device queue

#### Synopsis

       void blk_run_queue
       struct request_queue * q

#### Arguments

`q`

  The queue to run

### LINUX

Kernel Hackers Manual January 2008
blk_init_queue
9
2.6.24-rc6-git8

### blk_init_queue

prepare a request queue for use with a block device

#### Synopsis

       struct request_queue * blk_init_queue
       request_fn_proc * rfn
       spinlock_t * lock

#### Arguments

`rfn`

  The function to be called to process requests that have been placed on the queue.

`lock`

  Request queue spin lock

#### Description

If a block device wishes to use the standard request handling procedures, which sorts requests and coalesces adjacent requests, then it must call `blk_init_queue`. The function `rfn` will be called when there are requests on the queue that need to be processed. If the device supports plugging, then `rfn` may not be called immediately when requests are available on the queue, but may be called at some time later instead. Plugged queues are generally unplugged when a buffer belonging to one of the requests on the queue is needed, or due to memory pressure.

`rfn` is not required, or even expected, to remove all requests off the queue, but only as many as it can handle at a time. If it does leave requests on the queue, it is responsible for arranging that the requests get dealt with eventually.

The queue spin lock must be held while manipulating the requests on the request queue; this lock will be taken also from interrupt context, so irq disabling is needed for it.

Function returns a pointer to the initialized request queue, or NULL if it didn't succeed.

#### Note

`blk_init_queue` must be paired with a `blk_cleanup_queue` call when the block device is deactivated (such as at module unload).

### LINUX

Kernel Hackers Manual January 2008
blk_start_queueing
9
2.6.24-rc6-git8

### blk_start_queueing

initiate dispatch of requests to device

#### Synopsis

       void blk_start_queueing
       struct request_queue * q

#### Arguments

`q`

  request queue to kick into gear

#### Description

This is basically a helper to remove the need to know whether a queue is plugged or not if someone just wants to initiate dispatch of requests for this queue.

The queue lock must be held with interrupts disabled.

### LINUX

Kernel Hackers Manual January 2008
blk_requeue_request
9
2.6.24-rc6-git8

### blk_requeue_request

put a request back on queue

#### Synopsis

       void blk_requeue_request
       struct request_queue * q
       struct request * rq

#### Arguments

`q`

  request queue where request should be inserted

`rq`

  request to be inserted

#### Description

Drivers often keep queueing requests until the hardware cannot accept more, when that condition happens we need to put the request back on the queue. Must be called with queue lock held.

### LINUX

Kernel Hackers Manual January 2008
blk_insert_request
9
2.6.24-rc6-git8

### blk_insert_request

insert a special request in to a request queue

#### Synopsis

       void blk_insert_request
       struct request_queue * q
       struct request * rq
       int at_head
       void * data

#### Arguments

`q`

  request queue where request should be inserted

`rq`

  request to be inserted

`at_head`

  insert request at head or tail of queue

`data`

  private data

#### Description

Many block devices need to execute commands asynchronously, so they don't block the whole kernel from preemption during request execution. This is accomplished normally by inserting aritficial requests tagged as REQ_SPECIAL in to the corresponding request queue, and letting them be scheduled for actual execution by the request queue.

We have the option of inserting the head or the tail of the queue. Typically we use the tail for new ioctls and so forth. We use the head of the queue for things like a QUEUE_FULL message from a device, or a host that is unable to accept a particular command.

### LINUX

Kernel Hackers Manual January 2008
blk_rq_map_user
9
2.6.24-rc6-git8

### blk_rq_map_user

map user data to a request, for REQ_BLOCK_PC usage

#### Synopsis

       int blk_rq_map_user
       struct request_queue * q
       struct request * rq
       void __user * ubuf
       unsigned long len

#### Arguments

`q`

  request queue where request should be inserted

`rq`

  request structure to fill

`ubuf`

  the user buffer

`len`

  length of user data

#### Description

Data will be mapped directly for zero copy io, if possible. Otherwise a kernel bounce buffer is used.

A matching `blk_rq_unmap_user` must be issued at the end of io, while still in process context.

#### Note

The mapped bio may need to be bounced through `blk_queue_bounce` before being submitted to the device, as pages mapped may be out of reach. It's the callers responsibility to make sure this happens. The original bio must be passed back in to `blk_rq_unmap_user` for proper unmapping.

### LINUX

Kernel Hackers Manual January 2008
blk_rq_map_user_iov
9
2.6.24-rc6-git8

### blk_rq_map_user_iov

map user data to a request, for REQ_BLOCK_PC usage

#### Synopsis

       int blk_rq_map_user_iov
       struct request_queue * q
       struct request * rq
       struct sg_iovec * iov
       int iov_count
       unsigned int len

#### Arguments

`q`

  request queue where request should be inserted

`rq`

  request to map data to

`iov`

  pointer to the iovec

`iov_count`

  number of elements in the iovec

`len`

  I/O byte count

#### Description

Data will be mapped directly for zero copy io, if possible. Otherwise a kernel bounce buffer is used.

A matching `blk_rq_unmap_user` must be issued at the end of io, while still in process context.

#### Note

The mapped bio may need to be bounced through `blk_queue_bounce` before being submitted to the device, as pages mapped may be out of reach. It's the callers responsibility to make sure this happens. The original bio must be passed back in to `blk_rq_unmap_user` for proper unmapping.

### LINUX

Kernel Hackers Manual January 2008
blk_rq_unmap_user
9
2.6.24-rc6-git8

### blk_rq_unmap_user

unmap a request with user data

#### Synopsis

       int blk_rq_unmap_user
       struct bio * bio

#### Arguments

`bio`

  start of bio list

#### Description

Unmap a rq previously mapped by `blk_rq_map_user`. The caller must supply the original rq->bio from the `blk_rq_map_user` return, since the io completion may have changed rq->bio.

### LINUX

Kernel Hackers Manual January 2008
blk_rq_map_kern
9
2.6.24-rc6-git8

### blk_rq_map_kern

map kernel data to a request, for REQ_BLOCK_PC usage

#### Synopsis

       int blk_rq_map_kern
       struct request_queue * q
       struct request * rq
       void * kbuf
       unsigned int len
       gfp_t gfp_mask

#### Arguments

`q`

  request queue where request should be inserted

`rq`

  request to fill

`kbuf`

  the kernel buffer

`len`

  length of user data

`gfp_mask`

  memory allocation flags

### LINUX

Kernel Hackers Manual January 2008
blk_execute_rq_nowait
9
2.6.24-rc6-git8

### blk_execute_rq_nowait

insert a request into queue for execution

#### Synopsis

       void blk_execute_rq_nowait
       struct request_queue * q
       struct gendisk * bd_disk
       struct request * rq
       int at_head
       rq_end_io_fn * done

#### Arguments

`q`

  queue to insert the request in

`bd_disk`

  matching gendisk

`rq`

  request to insert

`at_head`

  insert request at head or tail of queue

`done`

  I/O completion handler

#### Description

Insert a fully prepared request at the back of the io scheduler queue for execution. Don't wait for completion.

### LINUX

Kernel Hackers Manual January 2008
blk_execute_rq
9
2.6.24-rc6-git8

### blk_execute_rq

insert a request into queue for execution

#### Synopsis

       int blk_execute_rq
       struct request_queue * q
       struct gendisk * bd_disk
       struct request * rq
       int at_head

#### Arguments

`q`

  queue to insert the request in

`bd_disk`

  matching gendisk

`rq`

  request to insert

`at_head`

  insert request at head or tail of queue

#### Description

Insert a fully prepared request at the back of the io scheduler queue for execution and wait for completion.

### LINUX

Kernel Hackers Manual January 2008
blkdev_issue_flush
9
2.6.24-rc6-git8

### blkdev_issue_flush

queue a flush

#### Synopsis

       int blkdev_issue_flush
       struct block_device * bdev
       sector_t * error_sector

#### Arguments

`bdev`

  blockdev to issue flush for

`error_sector`

  error sector

#### Description

Issue a flush for the block device in question. Caller can supply room for storing the error offset in case of a flush error, if they wish to. Caller must run `wait_for_completion` on its own.

### LINUX

Kernel Hackers Manual January 2008
blk_end_sync_rq
9
2.6.24-rc6-git8

### blk_end_sync_rq

executes a completion event on a request

#### Synopsis

       void blk_end_sync_rq
       struct request * rq
       int error

#### Arguments

`rq`

  request to complete

`error`

  end io status of the request

### LINUX

Kernel Hackers Manual January 2008
submit_bio
9
2.6.24-rc6-git8

### submit_bio

#### Synopsis

       void submit_bio
       int rw
       struct bio * bio

#### Arguments

`rw`

  whether to `READ` or `WRITE`, or maybe to `READA` (read ahead)

`bio`

  The &struct bio which describes the I/O

#### Description

`submit_bio` is very similar in purpose to `generic_make_request`, and uses that function to do most of the work. Both are fairly rough interfaces, `bio` must be presetup and ready for I/O.

### LINUX

Kernel Hackers Manual January 2008
end_that_request_first
9
2.6.24-rc6-git8

### end_that_request_first

end I/O on a request

#### Synopsis

       int end_that_request_first
       struct request * req
       int uptodate
       int nr_sectors

#### Arguments

`req`

  the request being processed

`uptodate`

  1 for success, 0 for I/O error, < 0 for specific error

`nr_sectors`

  number of sectors to end I/O on

#### Description

Ends I/O on a number of sectors attached to `req`, and sets it up for the next range of segments (if any) in the cluster.

#### Return

0 - we are done with this request, call `end_that_request_last` 1 - still buffers pending for this request

### LINUX

Kernel Hackers Manual January 2008
end_that_request_chunk
9
2.6.24-rc6-git8

### end_that_request_chunk

end I/O on a request

#### Synopsis

       int end_that_request_chunk
       struct request * req
       int uptodate
       int nr_bytes

#### Arguments

`req`

  the request being processed

`uptodate`

  1 for success, 0 for I/O error, < 0 for specific error

`nr_bytes`

  number of bytes to complete

#### Description

Ends I/O on a number of bytes attached to `req`, and sets it up for the next range of segments (if any). Like `end_that_request_first`, but deals with bytes instead of sectors.

#### Return

0 - we are done with this request, call `end_that_request_last` 1 - still buffers pending for this request

### LINUX

Kernel Hackers Manual January 2008
blk_complete_request
9
2.6.24-rc6-git8

### blk_complete_request

end I/O on a request

#### Synopsis

       void blk_complete_request
       struct request * req

#### Arguments

`req`

  the request being processed

#### Description

Ends all I/O on a request. It does not handle partial completions, unless the driver actually implements this in its completion callback through requeueing. The actual completion happens out-of-order, through a softirq handler. The user must have registered a completion callback through `blk_queue_softirq_done`.

### LINUX

Kernel Hackers Manual January 2008
end_queued_request
9
2.6.24-rc6-git8

### end_queued_request

end all I/O on a queued request

#### Synopsis

       void end_queued_request
       struct request * rq
       int uptodate

#### Arguments

`rq`

  the request being processed

`uptodate`

  error value or 0/1 uptodate flag

#### Description

Ends all I/O on a request, and removes it from the block layer queues. Not suitable for normal IO completion, unless the driver still has the request attached to the block layer.

### LINUX

Kernel Hackers Manual January 2008
end_dequeued_request
9
2.6.24-rc6-git8

### end_dequeued_request

end all I/O on a dequeued request

#### Synopsis

       void end_dequeued_request
       struct request * rq
       int uptodate

#### Arguments

`rq`

  the request being processed

`uptodate`

  error value or 0/1 uptodate flag

#### Description

Ends all I/O on a request. The request must already have been dequeued using `blkdev_dequeue_request`, as is normally the case for most drivers.

### LINUX

Kernel Hackers Manual January 2008
end_request
9
2.6.24-rc6-git8

### end_request

end I/O on the current segment of the request

#### Synopsis

       void end_request
       struct request * req
       int uptodate

#### Arguments

`req`

  the request being processed

`uptodate`

  error value or 0/1 uptodate flag

#### Description

Ends I/O on the current segment of a request. If that is the only remaining segment, the request is also completed and freed.

This is a remnant of how older block drivers handled IO completions. Modern drivers typically end IO on the full request in one go, unless they have a residual value to account for. For that case this function isn't really useful, unless the residual just happens to be the full current segment. In other words, don't use this function in new code. Either use `end_request_completely`, or the `end_that_request_chunk` (along with `end_that_request_last`) for partial completions.

## Char devices

### LINUX

Kernel Hackers Manual January 2008
register_chrdev_region
9
2.6.24-rc6-git8

### register_chrdev_region

register a range of device numbers

#### Synopsis

       int register_chrdev_region
       dev_t from
       unsigned count
       const char * name

#### Arguments

`from`

  the first in the desired range of device numbers; must include the major number.

`count`

  the number of consecutive device numbers required

`name`

  the name of the device or driver.

#### Description

Return value is zero on success, a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
alloc_chrdev_region
9
2.6.24-rc6-git8

### alloc_chrdev_region

register a range of char device numbers

#### Synopsis

       int alloc_chrdev_region
       dev_t * dev
       unsigned baseminor
       unsigned count
       const char * name

#### Arguments

`dev`

  output parameter for first assigned number

`baseminor`

  first of the requested range of minor numbers

`count`

  the number of minor numbers required

`name`

  the name of the associated device or driver

#### Description

Allocates a range of char device numbers. The major number will be chosen dynamically, and returned (along with the first minor number) in `dev`. Returns zero or a negative error code.

### LINUX

Kernel Hackers Manual January 2008
register_chrdev
9
2.6.24-rc6-git8

### register_chrdev

Register a major number for character devices.

#### Synopsis

       int register_chrdev
       unsigned int major
       const char * name
       const struct file_operations * fops

#### Arguments

`major`

  major device number or 0 for dynamic allocation

`name`

  name of this range of devices

`fops`

  file operations associated with this devices

#### Description

If `major` == 0 this functions will dynamically allocate a major and return its number.

If `major` > 0 this function will attempt to reserve a device with the given major number and will return zero on success.

Returns a -ve errno on failure.

The name of this device has nothing to do with the name of the device in /dev. It only helps to keep track of the different owners of devices. If your module name has only one type of devices it's ok to use e.g. the name of the module here.

This function registers a range of 256 minor numbers. The first minor number is 0.

### LINUX

Kernel Hackers Manual January 2008
unregister_chrdev_region
9
2.6.24-rc6-git8

### unregister_chrdev_region

return a range of device numbers

#### Synopsis

       void unregister_chrdev_region
       dev_t from
       unsigned count

#### Arguments

`from`

  the first in the range of numbers to unregister

`count`

  the number of device numbers to unregister

#### Description

This function will unregister a range of `count` device numbers, starting with `from`. The caller should normally be the one who allocated those numbers in the first place...

### LINUX

Kernel Hackers Manual January 2008
cdev_add
9
2.6.24-rc6-git8

### cdev_add

add a char device to the system

#### Synopsis

       int cdev_add
       struct cdev * p
       dev_t dev
       unsigned count

#### Arguments

`p`

  the cdev structure for the device

`dev`

  the first device number for which this device is responsible

`count`

  the number of consecutive minor numbers corresponding to this device

#### Description

`cdev_add` adds the device represented by `p` to the system, making it live immediately. A negative error code is returned on failure.

### LINUX

Kernel Hackers Manual January 2008
cdev_del
9
2.6.24-rc6-git8

### cdev_del

remove a cdev from the system

#### Synopsis

       void cdev_del
       struct cdev * p

#### Arguments

`p`

  the cdev structure to be removed

#### Description

`cdev_del` removes `p` from the system, possibly freeing the structure itself.

### LINUX

Kernel Hackers Manual January 2008
cdev_alloc
9
2.6.24-rc6-git8

### cdev_alloc

allocate a cdev structure

#### Synopsis

       struct cdev * cdev_alloc
        void

#### Arguments

`void`

  no arguments

#### Description

Allocates and returns a cdev structure, or NULL on failure.

### LINUX

Kernel Hackers Manual January 2008
cdev_init
9
2.6.24-rc6-git8

### cdev_init

initialize a cdev structure

#### Synopsis

       void cdev_init
       struct cdev * cdev
       const struct file_operations * fops

#### Arguments

`cdev`

  the structure to initialize

`fops`

  the file_operations for this device

#### Description

Initializes `cdev`, remembering `fops`, making it ready to add to the system with `cdev_add`.

## Miscellaneous Devices

### LINUX

Kernel Hackers Manual January 2008
misc_register
9
2.6.24-rc6-git8

### misc_register

register a miscellaneous device

#### Synopsis

       int misc_register
       struct miscdevice * misc

#### Arguments

`misc`

  device structure

#### Description

Register a miscellaneous device with the kernel. If the minor number is set to `MISC_DYNAMIC_MINOR` a minor number is assigned and placed in the minor field of the structure. For other cases the minor number requested is used.

The structure passed is linked into the kernel and may not be destroyed until it has been unregistered.

A zero is returned on success and a negative errno code for failure.

### LINUX

Kernel Hackers Manual January 2008
misc_deregister
9
2.6.24-rc6-git8

### misc_deregister

unregister a miscellaneous device

#### Synopsis

       int misc_deregister
       struct miscdevice * misc

#### Arguments

`misc`

  device to unregister

#### Description

Unregister a miscellaneous device that was previously successfully registered with `misc_register`. Success is indicated by a zero return, a negative errno code indicates an error.

## Parallel Port Devices

### LINUX

Kernel Hackers Manual January 2008
parport_yield
9
2.6.24-rc6-git8

### parport_yield

relinquish a parallel port temporarily

#### Synopsis

       int parport_yield
       struct pardevice * dev

#### Arguments

`dev`

  a device on the parallel port

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_yield_blocking
9
2.6.24-rc6-git8

### parport_yield_blocking

relinquish a parallel port temporarily

#### Synopsis

       int parport_yield_blocking
       struct pardevice * dev

#### Arguments

`dev`

  a device on the parallel port

#### Description

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`.

### LINUX

Kernel Hackers Manual January 2008
parport_wait_event
9
2.6.24-rc6-git8

### parport_wait_event

wait for an event on a parallel port

#### Synopsis

       int parport_wait_event
       struct parport * port
       signed long timeout

#### Arguments

`port`

  port to wait on

`timeout`

  time to wait (in jiffies)

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_wait_peripheral
9
2.6.24-rc6-git8

### parport_wait_peripheral

wait for status lines to change in 35ms

#### Synopsis

       int parport_wait_peripheral
       struct parport * port
       unsigned char mask
       unsigned char result

#### Arguments

`port`

  port to watch

`mask`

  status lines to watch

`result`

  desired values of chosen status lines

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_negotiate
9
2.6.24-rc6-git8

### parport_negotiate

negotiate an IEEE 1284 mode

#### Synopsis

       int parport_negotiate
       struct parport * port
       int mode

#### Arguments

`port`

  port to use

`mode`

  mode to negotiate to

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_write
9
2.6.24-rc6-git8

### parport_write

write a block of data to a parallel port

#### Synopsis

       ssize_t parport_write
       struct parport * port
       const void * buffer
       size_t len

#### Arguments

`port`

  port to write to

`buffer`

  data buffer (in kernel space)

`len`

  number of bytes of data to transfer

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_read
9
2.6.24-rc6-git8

### parport_read

read a block of data from a parallel port

#### Synopsis

       ssize_t parport_read
       struct parport * port
       void * buffer
       size_t len

#### Arguments

`port`

  port to read from

`buffer`

  data buffer (in kernel space)

`len`

  number of bytes of data to transfer

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_set_timeout
9
2.6.24-rc6-git8

### parport_set_timeout

set the inactivity timeout for a device

#### Synopsis

       long parport_set_timeout
       struct pardevice * dev
       long inactivity

#### Arguments

`dev`

  device on a port

`inactivity`

  inactivity timeout (in jiffies)

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_register_driver
9
2.6.24-rc6-git8

### parport_register_driver

register a parallel port device driver

#### Synopsis

       int parport_register_driver
       struct parport_driver * drv

#### Arguments

`drv`

  structure describing the driver

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_unregister_driver
9
2.6.24-rc6-git8

### parport_unregister_driver

deregister a parallel port device driver

#### Synopsis

       void parport_unregister_driver
       struct parport_driver * drv

#### Arguments

`drv`

  structure describing the driver that was given to `parport_register_driver`

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_get_port
9
2.6.24-rc6-git8

### parport_get_port

increment a port's reference count

#### Synopsis

       struct parport * parport_get_port
       struct parport * port

#### Arguments

`port`

  the port

#### Description

This ensures that a struct parport pointer remains valid until the matching `parport_put_port` call.

### LINUX

Kernel Hackers Manual January 2008
parport_put_port
9
2.6.24-rc6-git8

### parport_put_port

decrement a port's reference count

#### Synopsis

       void parport_put_port
       struct parport * port

#### Arguments

`port`

  the port

#### Description

This should be called once for each call to `parport_get_port`, once the port is no longer needed.

### LINUX

Kernel Hackers Manual January 2008
parport_register_port
9
2.6.24-rc6-git8

### parport_register_port

register a parallel port

#### Synopsis

       struct parport * parport_register_port
       unsigned long base
       int irq
       int dma
       struct parport_operations * ops

#### Arguments

`base`

  base I/O address

`irq`

  IRQ line

`dma`

  DMA channel

`ops`

  pointer to the port driver's port operations structure

#### Description

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`.

### LINUX

Kernel Hackers Manual January 2008
parport_announce_port
9
2.6.24-rc6-git8

### parport_announce_port

tell device drivers about a parallel port

#### Synopsis

       void parport_announce_port
       struct parport * port

#### Arguments

`port`

  parallel port to announce

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_remove_port
9
2.6.24-rc6-git8

### parport_remove_port

deregister a parallel port

#### Synopsis

       void parport_remove_port
       struct parport * port

#### Arguments

`port`

  parallel port to deregister

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_register_device
9
2.6.24-rc6-git8

### parport_register_device

register a device on a parallel port

#### Synopsis

       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

#### Arguments

`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

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_unregister_device
9
2.6.24-rc6-git8

### parport_unregister_device

deregister a device on a parallel port

#### Synopsis

       void parport_unregister_device
       struct pardevice * dev

#### Arguments

`dev`

  pointer to structure representing device

#### Description

This undoes the effect of `parport_register_device`.

### LINUX

Kernel Hackers Manual January 2008
parport_find_number
9
2.6.24-rc6-git8

### parport_find_number

find a parallel port by number

#### Synopsis

       struct parport * parport_find_number
       int number

#### Arguments

`number`

  parallel port number

#### Description

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`.

### LINUX

Kernel Hackers Manual January 2008
parport_find_base
9
2.6.24-rc6-git8

### parport_find_base

find a parallel port by base address

#### Synopsis

       struct parport * parport_find_base
       unsigned long base

#### Arguments

`base`

  base I/O address

#### Description

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`.

### LINUX

Kernel Hackers Manual January 2008
parport_claim
9
2.6.24-rc6-git8

### parport_claim

claim access to a parallel port device

#### Synopsis

       int parport_claim
       struct pardevice * dev

#### Arguments

`dev`

  pointer to structure representing a device on the port

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_claim_or_block
9
2.6.24-rc6-git8

### parport_claim_or_block

claim access to a parallel port device

#### Synopsis

       int parport_claim_or_block
       struct pardevice * dev

#### Arguments

`dev`

  pointer to structure representing a device on the port

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_release
9
2.6.24-rc6-git8

### parport_release

give up access to a parallel port device

#### Synopsis

       void parport_release
       struct pardevice * dev

#### Arguments

`dev`

  pointer to structure representing parallel port device

#### Description

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.

### LINUX

Kernel Hackers Manual January 2008
parport_open
9
2.6.24-rc6-git8

### parport_open

find a device by canonical device number

#### Synopsis

       struct pardevice * parport_open
       int devnum
       const char * name

#### Arguments

`devnum`

  canonical device number

`name`

  name to associate with the device

#### Description

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`.

### LINUX

Kernel Hackers Manual January 2008
parport_close
9
2.6.24-rc6-git8

### parport_close

close a device opened with `parport_open`

#### Synopsis

       void parport_close
       struct pardevice * dev

#### Arguments

`dev`

  device to close

#### Description

This is to `parport_open` as `parport_unregister_device` is to `parport_register_device`.

## Message-based devices

### Fusion message devices

#### LINUX

Kernel Hackers Manual January 2008
mpt_register
9
2.6.24-rc6-git8

#### mpt_register

Register protocol-specific main callback handler.

##### Synopsis

       u8 mpt_register
       MPT_CALLBACK cbfunc
       MPT_DRIVER_CLASS dclass

##### Arguments

`cbfunc`

  callback function pointer

`dclass`

  Protocol driver's class (`MPT_DRIVER_CLASS` enum value)

##### Description

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.

##### NOTES

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.

#### LINUX

Kernel Hackers Manual January 2008
mpt_deregister
9
2.6.24-rc6-git8

#### mpt_deregister

Deregister a protocol drivers resources.

##### Synopsis

       void mpt_deregister
       u8 cb_idx

##### Arguments

`cb_idx`

  previously registered callback handle

##### Description

Each protocol-specific driver should call this routine when its module is unloaded.

#### LINUX

Kernel Hackers Manual January 2008
mpt_event_register
9
2.6.24-rc6-git8

#### mpt_event_register

Register protocol-specific event callback

##### Synopsis

       int mpt_event_register
       u8 cb_idx
       MPT_EVHANDLER ev_cbfunc

##### Arguments

`cb_idx`

  previously registered (via mpt_register) callback handle

`ev_cbfunc`

  callback function

##### Description

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.

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
mpt_event_deregister
9
2.6.24-rc6-git8

#### mpt_event_deregister

Deregister protocol-specific event callback

##### Synopsis

       void mpt_event_deregister
       u8 cb_idx

##### Arguments

`cb_idx`

  previously registered callback handle

##### Description

Each protocol-specific driver should call this routine when it does not (or can no longer) handle events, or when its module is unloaded.

##### Description

Each protocol-specific driver should call this routine when it does not (or can no longer) handle events, or when its module is unloaded.

#### LINUX

Kernel Hackers Manual January 2008
mpt_reset_register
9
2.6.24-rc6-git8

#### mpt_reset_register

Register protocol-specific IOC reset handler.

##### Synopsis

       int mpt_reset_register
       u8 cb_idx
       MPT_RESETHANDLER reset_func

##### Arguments

`cb_idx`

  previously registered (via mpt_register) callback handle

`reset_func`

  reset function

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
mpt_reset_deregister
9
2.6.24-rc6-git8

#### mpt_reset_deregister

Deregister protocol-specific IOC reset handler.

##### Synopsis

       void mpt_reset_deregister
       u8 cb_idx

##### Arguments

`cb_idx`

  previously registered callback handle

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
mpt_device_driver_register
9
2.6.24-rc6-git8

#### mpt_device_driver_register

Register device driver hooks

##### Synopsis

       int mpt_device_driver_register
       struct mpt_pci_driver * dd_cbfunc
       u8 cb_idx

##### Arguments

`dd_cbfunc`

  driver callbacks struct

`cb_idx`

  MPT protocol driver index

#### LINUX

Kernel Hackers Manual January 2008
mpt_device_driver_deregister
9
2.6.24-rc6-git8

#### mpt_device_driver_deregister

DeRegister device driver hooks

##### Synopsis

       void mpt_device_driver_deregister
       u8 cb_idx

##### Arguments

`cb_idx`

  MPT protocol driver index

#### LINUX

Kernel Hackers Manual January 2008
mpt_get_msg_frame
9
2.6.24-rc6-git8

#### mpt_get_msg_frame

Obtain a MPT request frame from the pool (of 1024)

##### Synopsis

       MPT_FRAME_HDR* mpt_get_msg_frame
       u8 cb_idx
       MPT_ADAPTER * ioc

##### Arguments

`cb_idx`

  Handle of registered MPT protocol driver

`ioc`

  Pointer to MPT adapter structure

##### Description

Returns pointer to a MPT request frame or `NULL` if none are available or IOC is not active.

##### Description

Returns pointer to a MPT request frame or `NULL` if none are available or IOC is not active.

#### LINUX

Kernel Hackers Manual January 2008
mpt_put_msg_frame
9
2.6.24-rc6-git8

#### mpt_put_msg_frame

Send a protocol specific MPT request frame

##### Synopsis

       void mpt_put_msg_frame
       u8 cb_idx
       MPT_ADAPTER * ioc
       MPT_FRAME_HDR * mf

##### Arguments

`cb_idx`

  Handle of registered MPT protocol driver

`ioc`

  Pointer to MPT adapter structure

`mf`

  Pointer to MPT request frame

##### Description

This routine posts a MPT request frame to the request post FIFO of a specific MPT adapter.

##### Description

This routine posts a MPT request frame to the request post FIFO of a specific MPT adapter.

#### LINUX

Kernel Hackers Manual January 2008
mpt_put_msg_frame_hi_pri
9
2.6.24-rc6-git8

#### mpt_put_msg_frame_hi_pri

Send a protocol specific MPT request frame

##### Synopsis

       void mpt_put_msg_frame_hi_pri
       u8 cb_idx
       MPT_ADAPTER * ioc
       MPT_FRAME_HDR * mf

##### Arguments

`cb_idx`

  Handle of registered MPT protocol driver

`ioc`

  Pointer to MPT adapter structure

`mf`

  Pointer to MPT request frame

##### Description

This routine posts a MPT request frame to the request post FIFO of a specific MPT adapter.

##### Description

This routine posts a MPT request frame to the request post FIFO of a specific MPT adapter.

#### LINUX

Kernel Hackers Manual January 2008
mpt_free_msg_frame
9
2.6.24-rc6-git8

#### mpt_free_msg_frame

Place MPT request frame back on FreeQ.

##### Synopsis

       void mpt_free_msg_frame
       MPT_ADAPTER * ioc
       MPT_FRAME_HDR * mf

##### Arguments

`ioc`

  Pointer to MPT adapter structure

`mf`

  Pointer to MPT request frame

##### Description

This routine places a MPT request frame back on the MPT adapter's FreeQ.

#### LINUX

Kernel Hackers Manual January 2008
mpt_add_sge
9
2.6.24-rc6-git8

#### mpt_add_sge

Place a simple SGE at address pAddr.

##### Synopsis

       void mpt_add_sge
       char * pAddr
       u32 flagslength
       dma_addr_t dma_addr

##### Arguments

`pAddr`

  virtual address for SGE

`flagslength`

  SGE flags and data transfer length

`dma_addr`

  Physical address

##### Description

This routine places a MPT request frame back on the MPT adapter's FreeQ.

#### LINUX

Kernel Hackers Manual January 2008
mpt_send_handshake_request
9
2.6.24-rc6-git8

#### mpt_send_handshake_request

Send MPT request via doorbell handshake method.

##### Synopsis

       int mpt_send_handshake_request
       u8 cb_idx
       MPT_ADAPTER * ioc
       int reqBytes
       u32 * req
       int sleepFlag

##### Arguments

`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.

##### Description

This routine is used exclusively to send MptScsiTaskMgmt requests since they are required to be sent via doorbell handshake.

##### NOTE

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.

#### LINUX

Kernel Hackers Manual January 2008
mpt_verify_adapter
9
2.6.24-rc6-git8

#### mpt_verify_adapter

Given IOC identifier, set pointer to its adapter structure.

##### Synopsis

       int mpt_verify_adapter
       int iocid
       MPT_ADAPTER ** iocpp

##### Arguments

`iocid`

  IOC unique identifier (integer)

`iocpp`

  Pointer to pointer to IOC adapter

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
mpt_attach
9
2.6.24-rc6-git8

#### mpt_attach

Install a PCI intelligent MPT adapter.

##### Synopsis

       int mpt_attach
       struct pci_dev * pdev
       const struct pci_device_id * id

##### Arguments

`pdev`

  Pointer to pci_dev structure

`id`

  PCI device ID information

##### Description

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.

##### TODO

Add support for polled controllers

#### LINUX

Kernel Hackers Manual January 2008
mpt_detach
9
2.6.24-rc6-git8

#### mpt_detach

Remove a PCI intelligent MPT adapter.

##### Synopsis

       void mpt_detach
       struct pci_dev * pdev

##### Arguments

`pdev`

  Pointer to pci_dev structure

#### LINUX

Kernel Hackers Manual January 2008
mpt_suspend
9
2.6.24-rc6-git8

#### mpt_suspend

Fusion MPT base driver suspend routine.

##### Synopsis

       int mpt_suspend
       struct pci_dev * pdev
       pm_message_t state

##### Arguments

`pdev`

  Pointer to pci_dev structure

`state`

  new state to enter

#### LINUX

Kernel Hackers Manual January 2008
mpt_resume
9
2.6.24-rc6-git8

#### mpt_resume

Fusion MPT base driver resume routine.

##### Synopsis

       int mpt_resume
       struct pci_dev * pdev

##### Arguments

`pdev`

  Pointer to pci_dev structure

#### LINUX

Kernel Hackers Manual January 2008
mpt_GetIocState
9
2.6.24-rc6-git8

#### mpt_GetIocState

Get the current state of a MPT adapter.

##### Synopsis

       u32 mpt_GetIocState
       MPT_ADAPTER * ioc
       int cooked

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`cooked`

  Request raw or cooked IOC state

##### Description

Returns all IOC Doorbell register bits if cooked==0, else just the Doorbell bits in MPI_IOC_STATE_MASK.

#### LINUX

Kernel Hackers Manual January 2008
mpt_alloc_fw_memory
9
2.6.24-rc6-git8

#### mpt_alloc_fw_memory

allocate firmware memory

##### Synopsis

       void mpt_alloc_fw_memory
       MPT_ADAPTER * ioc
       int size

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`size`

  total FW bytes

##### Description

If memory has already been allocated, the same (cached) value is returned.

#### LINUX

Kernel Hackers Manual January 2008
mpt_free_fw_memory
9
2.6.24-rc6-git8

#### mpt_free_fw_memory

free firmware memory

##### Synopsis

       void mpt_free_fw_memory
       MPT_ADAPTER * ioc

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

##### Description

If alt_img is NULL, delete from ioc structure. Else, delete a secondary image in same format.

#### LINUX

Kernel Hackers Manual January 2008
mptbase_sas_persist_operation
9
2.6.24-rc6-git8

#### mptbase_sas_persist_operation

Perform operation on SAS Persistent Table

##### Synopsis

       int mptbase_sas_persist_operation
       MPT_ADAPTER * ioc
       u8 persist_opcode

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`persist_opcode`

  see below

##### Description

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

##### NOTE

Don't use not this function during interrupt time.

Returns 0 for success, non-zero error

#### LINUX

Kernel Hackers Manual January 2008
mpt_raid_phys_disk_pg0
9
2.6.24-rc6-git8

#### mpt_raid_phys_disk_pg0

returns phys disk page zero

##### Synopsis

       int mpt_raid_phys_disk_pg0
       MPT_ADAPTER * ioc
       u8 phys_disk_num
       pRaidPhysDiskPage0_t phys_disk

##### Arguments

`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

##### Return

0 on success -EFAULT if read of config page header fails or data pointer not NULL -ENOMEM if pci_alloc failed

#### LINUX

Kernel Hackers Manual January 2008
mpt_findImVolumes
9
2.6.24-rc6-git8

#### mpt_findImVolumes

Identify IDs of hidden disks and RAID Volumes

##### Synopsis

       int mpt_findImVolumes
       MPT_ADAPTER * ioc

##### Arguments

`ioc`

  Pointer to a Adapter Strucutre

##### Return

0 on success -EFAULT if read of config page header fails or data pointer not NULL -ENOMEM if pci_alloc failed

#### LINUX

Kernel Hackers Manual January 2008
mpt_config
9
2.6.24-rc6-git8

#### mpt_config

Generic function to issue config message

##### Synopsis

       int mpt_config
       MPT_ADAPTER * ioc
       CONFIGPARMS * pCfg

##### Arguments

`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.

##### Description

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)

#### LINUX

Kernel Hackers Manual January 2008
mpt_print_ioc_summary
9
2.6.24-rc6-git8

#### mpt_print_ioc_summary

Write ASCII summary of IOC to a buffer.

##### Synopsis

       void mpt_print_ioc_summary
       MPT_ADAPTER * ioc
       char * buffer
       int * size
       int len
       int showlan

##### Arguments

`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?

##### Description

This routine writes (english readable) ASCII text, which represents a summary of IOC information, to a buffer.

#### LINUX

Kernel Hackers Manual January 2008
mpt_HardResetHandler
9
2.6.24-rc6-git8

#### mpt_HardResetHandler

Generic reset handler

##### Synopsis

       int mpt_HardResetHandler
       MPT_ADAPTER * ioc
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`sleepFlag`

  Indicates if sleep or schedule must be called.

##### Description

Issues SCSI Task Management call based on input arg values. If TaskMgmt fails, returns associated SCSI request.

##### Remark

_HardResetHandler can be invoked from an interrupt thread (timer) or a non-interrupt thread. In the former, must not call `schedule`.

##### Note

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.

#### LINUX

Kernel Hackers Manual January 2008
mpt_get_cb_idx
9
2.6.24-rc6-git8

#### mpt_get_cb_idx

obtain cb_idx for registered driver

##### Synopsis

       u8 mpt_get_cb_idx
       MPT_DRIVER_CLASS dclass

##### Arguments

`dclass`

  class driver enum

##### Description

Returns cb_idx, or zero means it wasn't found

#### LINUX

Kernel Hackers Manual January 2008
mpt_interrupt
9
2.6.24-rc6-git8

#### mpt_interrupt

MPT adapter (IOC) specific interrupt handler.

##### Synopsis

       irqreturn_t mpt_interrupt
       int irq
       void * bus_id

##### Arguments

`irq`

  irq number (not used)

`bus_id`

  bus identifier cookie == pointer to MPT_ADAPTER structure

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
mpt_base_reply
9
2.6.24-rc6-git8

#### mpt_base_reply

MPT base driver's callback routine

##### Synopsis

       int mpt_base_reply
       MPT_ADAPTER * ioc
       MPT_FRAME_HDR * mf
       MPT_FRAME_HDR * reply

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`mf`

  Pointer to original MPT request frame

`reply`

  Pointer to MPT reply frame (NULL if TurboReply)

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
mpt_host_page_access_control
9
2.6.24-rc6-git8

#### mpt_host_page_access_control

control the IOC's Host Page Buffer access

##### Synopsis

       int mpt_host_page_access_control
       MPT_ADAPTER * ioc
       u8 access_control_value
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT adapter structure

`access_control_value`

  define bits below

`sleepFlag`

  Specifies whether the process can sleep

##### Description

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.

#### LINUX

Kernel Hackers Manual January 2008
mpt_host_page_alloc
9
2.6.24-rc6-git8

#### mpt_host_page_alloc

allocate system memory for the fw

##### Synopsis

       int mpt_host_page_alloc
       MPT_ADAPTER * ioc
       pIOCInit_t ioc_init

##### Arguments

`ioc`

  Pointer to pointer to IOC adapter

`ioc_init`

  Pointer to ioc init config page

##### Description

If we already allocated memory in past, then resend the same pointer. Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
mpt_get_product_name
9
2.6.24-rc6-git8

#### mpt_get_product_name

returns product string

##### Synopsis

       void mpt_get_product_name
       u16 vendor
       u16 device
       u8 revision
       char * prod_name

##### Arguments

`vendor`

  pci vendor id

`device`

  pci device id

`revision`

  pci revision id

`prod_name`

  string returned

##### Description

Returns product string displayed when driver loads, in /proc/mpt/summary and /sysfs/class/scsi_host/host<X>/version_product

#### LINUX

Kernel Hackers Manual January 2008
mpt_do_ioc_recovery
9
2.6.24-rc6-git8

#### mpt_do_ioc_recovery

Initialize or recover MPT adapter.

##### Synopsis

       int mpt_do_ioc_recovery
       MPT_ADAPTER * ioc
       u32 reason
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT adapter structure

`reason`

  Event word / reason

`sleepFlag`

  Use schedule if CAN_SLEEP else use udelay.

##### Description

This routine performs all the steps necessary to bring the IOC to a OPERATIONAL state.

This routine also pre-fetches the LAN MAC address of a Fibre Channel MPT adapter.

##### Returns

0 for success -1 if failed to get board READY -2 if READY but IOCFacts Failed -3 if READY but PrimeIOCFifos Failed -4 if READY but IOCInit Failed

#### LINUX

Kernel Hackers Manual January 2008
mpt_detect_bound_ports
9
2.6.24-rc6-git8

#### mpt_detect_bound_ports

Search for matching PCI bus/dev_function

##### Synopsis

       void mpt_detect_bound_ports
       MPT_ADAPTER * ioc
       struct pci_dev * pdev

##### Arguments

`ioc`

  Pointer to MPT adapter structure

`pdev`

  Pointer to (struct pci_dev) structure

##### Description

Search for PCI bus/dev_function which matches PCI bus/dev_function (+/-1) for newly discovered 929, 929X, 1030 or 1035.

If match on PCI dev_function +/-1 is found, bind the two MPT adapters using alt_ioc pointer fields in their `MPT_ADAPTER` structures.

#### LINUX

Kernel Hackers Manual January 2008
mpt_adapter_disable
9
2.6.24-rc6-git8

#### mpt_adapter_disable

Disable misbehaving MPT adapter.

##### Synopsis

       void mpt_adapter_disable
       MPT_ADAPTER * ioc

##### Arguments

`ioc`

  Pointer to MPT adapter structure

#### LINUX

Kernel Hackers Manual January 2008
mpt_adapter_dispose
9
2.6.24-rc6-git8

#### mpt_adapter_dispose

Free all resources associated with an MPT adapter

##### Synopsis

       void mpt_adapter_dispose
       MPT_ADAPTER * ioc

##### Arguments

`ioc`

  Pointer to MPT adapter structure

##### Description

This routine unregisters h/w resources and frees all alloc'd memory associated with a MPT adapter structure.

#### LINUX

Kernel Hackers Manual January 2008
MptDisplayIocCapabilities
9
2.6.24-rc6-git8

#### MptDisplayIocCapabilities

Disply IOC's capabilities.

##### Synopsis

       void MptDisplayIocCapabilities
       MPT_ADAPTER * ioc

##### Arguments

`ioc`

  Pointer to MPT adapter structure

#### LINUX

Kernel Hackers Manual January 2008
MakeIocReady
9
2.6.24-rc6-git8

#### MakeIocReady

Get IOC to a READY state, using KickStart if needed.

##### Synopsis

       int MakeIocReady
       MPT_ADAPTER * ioc
       int force
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`force`

  Force hard KickStart of IOC

`sleepFlag`

  Specifies whether the process can sleep

##### Returns

1 - DIAG reset and READY 0 - READY initially OR soft reset and READY -1 - Any failure on KickStart -2 - Msg Unit Reset Failed -3 - IO Unit Reset Failed -4 - IOC owned by a PEER

#### LINUX

Kernel Hackers Manual January 2008
GetIocFacts
9
2.6.24-rc6-git8

#### GetIocFacts

Send IOCFacts request to MPT adapter.

##### Synopsis

       int GetIocFacts
       MPT_ADAPTER * ioc
       int sleepFlag
       int reason

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`sleepFlag`

  Specifies whether the process can sleep

`reason`

  If recovery, only update facts.

##### Description

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
GetPortFacts
9
2.6.24-rc6-git8

#### GetPortFacts

Send PortFacts request to MPT adapter.

##### Synopsis

       int GetPortFacts
       MPT_ADAPTER * ioc
       int portnum
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`portnum`

  Port number

`sleepFlag`

  Specifies whether the process can sleep

##### Description

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
SendIocInit
9
2.6.24-rc6-git8

#### SendIocInit

Send IOCInit request to MPT adapter.

##### Synopsis

       int SendIocInit
       MPT_ADAPTER * ioc
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`sleepFlag`

  Specifies whether the process can sleep

##### Description

Send IOCInit followed by PortEnable to bring IOC to OPERATIONAL state.

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
SendPortEnable
9
2.6.24-rc6-git8

#### SendPortEnable

Send PortEnable request to MPT adapter port.

##### Synopsis

       int SendPortEnable
       MPT_ADAPTER * ioc
       int portnum
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`portnum`

  Port number to enable

`sleepFlag`

  Specifies whether the process can sleep

##### Description

Send PortEnable to bring IOC to OPERATIONAL state.

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
mpt_do_upload
9
2.6.24-rc6-git8

#### mpt_do_upload

Construct and Send FWUpload request to MPT adapter port.

##### Synopsis

       int mpt_do_upload
       MPT_ADAPTER * ioc
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`sleepFlag`

  Specifies whether the process can sleep

##### Description

Returns 0 for success, >0 for handshake failure <0 for fw upload failure.

##### Remark

If bound IOC and a successful FWUpload was performed on the bound IOC, the second image is discarded and memory is free'd. Both channels must upload to prevent IOC from running in degraded mode.

#### LINUX

Kernel Hackers Manual January 2008
mpt_downloadboot
9
2.6.24-rc6-git8

#### mpt_downloadboot

DownloadBoot code

##### Synopsis

       int mpt_downloadboot
       MPT_ADAPTER * ioc
       MpiFwHeader_t * pFwHeader
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`pFwHeader`

  Pointer to firmware header info

`sleepFlag`

  Specifies whether the process can sleep

##### Description

FwDownloadBoot requires Programmed IO access.

Returns 0 for success -1 FW Image size is 0 -2 No valid cached_fw Pointer <0 for fw upload failure.

#### LINUX

Kernel Hackers Manual January 2008
KickStart
9
2.6.24-rc6-git8

#### KickStart

Perform hard reset of MPT adapter.

##### Synopsis

       int KickStart
       MPT_ADAPTER * ioc
       int force
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`force`

  Force hard reset

`sleepFlag`

  Specifies whether the process can sleep

##### Description

This routine places MPT adapter in diagnostic mode via the WriteSequence register, and then performs a hard reset of adapter via the Diagnostic register.

##### Inputs

sleepflag - CAN_SLEEP (non-interrupt thread) or NO_SLEEP (interrupt thread, use mdelay) force - 1 if doorbell active, board fault state board operational, IOC_RECOVERY or IOC_BRINGUP and there is an alt_ioc. 0 else

##### Returns

1 - hard reset, READY 0 - no reset due to History bit, READY -1 - no reset due to History bit but not READY OR reset but failed to come READY -2 - no reset, could not enter DIAG mode -3 - reset but bad FW bit

#### LINUX

Kernel Hackers Manual January 2008
mpt_diag_reset
9
2.6.24-rc6-git8

#### mpt_diag_reset

Perform hard reset of the adapter.

##### Synopsis

       int mpt_diag_reset
       MPT_ADAPTER * ioc
       int ignore
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`ignore`

  Set if to honor and clear to ignore the reset history bit

`sleepFlag`

  CAN_SLEEP if called in a non-interrupt thread, else set to NO_SLEEP (use mdelay instead)

##### Description

This routine places the adapter in diagnostic mode via the WriteSequence register and then performs a hard reset of adapter via the Diagnostic register. Adapter should be in ready state upon successful completion.

##### Returns

1 hard reset successful 0 no reset performed because reset history bit set -2 enabling diagnostic mode failed -3 diagnostic reset failed

#### LINUX

Kernel Hackers Manual January 2008
SendIocReset
9
2.6.24-rc6-git8

#### SendIocReset

Send IOCReset request to MPT adapter.

##### Synopsis

       int SendIocReset
       MPT_ADAPTER * ioc
       u8 reset_type
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`reset_type`

  reset type, expected values are `MPI_FUNCTION_IOC_MESSAGE_UNIT_RESET` or `MPI_FUNCTION_IO_UNIT_RESET`

`sleepFlag`

  Specifies whether the process can sleep

##### Description

Send IOCReset request to the MPT adapter.

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
initChainBuffers
9
2.6.24-rc6-git8

#### initChainBuffers

Allocate memory for and initialize chain buffers

##### Synopsis

       int initChainBuffers
       MPT_ADAPTER * ioc

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

##### Description

Allocates memory for and initializes chain buffers, chain buffer control arrays and spinlock.

#### LINUX

Kernel Hackers Manual January 2008
PrimeIocFifos
9
2.6.24-rc6-git8

#### PrimeIocFifos

Initialize IOC request and reply FIFOs.

##### Synopsis

       int PrimeIocFifos
       MPT_ADAPTER * ioc

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

##### Description

This routine allocates memory for the MPT reply and request frame pools (if necessary), and primes the IOC reply FIFO with reply frames.

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
mpt_handshake_req_reply_wait
9
2.6.24-rc6-git8

#### mpt_handshake_req_reply_wait

Send MPT request to and receive reply

##### Synopsis

       int mpt_handshake_req_reply_wait
       MPT_ADAPTER * ioc
       int reqBytes
       u32 * req
       int replyBytes
       u16 * u16reply
       int maxwait
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`reqBytes`

  Size of the request in bytes

`req`

  Pointer to MPT request frame

`replyBytes`

  Expected size of the reply in bytes

`u16reply`

  Pointer to area where reply should be written

`maxwait`

  Max wait time for a reply (in seconds)

`sleepFlag`

  Specifies whether the process can sleep

##### Description

from IOC via doorbell handshake method.

##### NOTES

It is the callers responsibility to byte-swap fields in the request which are greater than 1 byte in size. It is also the callers responsibility to byte-swap response fields which are greater than 1 byte in size.

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
WaitForDoorbellAck
9
2.6.24-rc6-git8

#### WaitForDoorbellAck

Wait for IOC doorbell handshake acknowledge

##### Synopsis

       int WaitForDoorbellAck
       MPT_ADAPTER * ioc
       int howlong
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`howlong`

  How long to wait (in seconds)

`sleepFlag`

  Specifies whether the process can sleep

##### Description

This routine waits (up to ~2 seconds max) for IOC doorbell handshake ACKnowledge, indicated by the IOP_DOORBELL_STATUS bit in its IntStatus register being clear.

Returns a negative value on failure, else wait loop count.

#### LINUX

Kernel Hackers Manual January 2008
WaitForDoorbellInt
9
2.6.24-rc6-git8

#### WaitForDoorbellInt

Wait for IOC to set its doorbell interrupt bit

##### Synopsis

       int WaitForDoorbellInt
       MPT_ADAPTER * ioc
       int howlong
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`howlong`

  How long to wait (in seconds)

`sleepFlag`

  Specifies whether the process can sleep

##### Description

This routine waits (up to ~2 seconds max) for IOC doorbell interrupt (MPI_HIS_DOORBELL_INTERRUPT) to be set in the IntStatus register.

Returns a negative value on failure, else wait loop count.

#### LINUX

Kernel Hackers Manual January 2008
WaitForDoorbellReply
9
2.6.24-rc6-git8

#### WaitForDoorbellReply

Wait for and capture an IOC handshake reply.

##### Synopsis

       int WaitForDoorbellReply
       MPT_ADAPTER * ioc
       int howlong
       int sleepFlag

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`howlong`

  How long to wait (in seconds)

`sleepFlag`

  Specifies whether the process can sleep

##### Description

This routine polls the IOC for a handshake reply, 16 bits at a time. Reply is cached to IOC private area large enough to hold a maximum of 128 bytes of reply data.

Returns a negative value on failure, else size of reply in WORDS.

#### LINUX

Kernel Hackers Manual January 2008
GetLanConfigPages
9
2.6.24-rc6-git8

#### GetLanConfigPages

Fetch LANConfig pages.

##### Synopsis

       int GetLanConfigPages
       MPT_ADAPTER * ioc

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

##### Return

0 for success -ENOMEM if no memory available -EPERM if not allowed due to ISR context -EAGAIN if no msg frames currently available -EFAULT for non-successful reply or no reply (timeout)

#### LINUX

Kernel Hackers Manual January 2008
GetIoUnitPage2
9
2.6.24-rc6-git8

#### GetIoUnitPage2

Retrieve BIOS version and boot order information.

##### Synopsis

       int GetIoUnitPage2
       MPT_ADAPTER * ioc

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

##### Returns

0 for success -ENOMEM if no memory available -EPERM if not allowed due to ISR context -EAGAIN if no msg frames currently available -EFAULT for non-successful reply or no reply (timeout)

#### LINUX

Kernel Hackers Manual January 2008
mpt_GetScsiPortSettings
9
2.6.24-rc6-git8

#### mpt_GetScsiPortSettings

read SCSI Port Page 0 and 2

##### Synopsis

       int mpt_GetScsiPortSettings
       MPT_ADAPTER * ioc
       int portnum

##### Arguments

`ioc`

  Pointer to a Adapter Strucutre

`portnum`

  IOC port number

##### Return

-EFAULT if read of config page header fails or if no nvram If read of SCSI Port Page 0 fails, NVRAM = MPT_HOST_NVRAM_INVALID (0xFFFFFFFF)

##### Adapter settings

async, narrow Return 1 If read of SCSI Port Page 2 fails, Adapter settings valid NVRAM = MPT_HOST_NVRAM_INVALID (0xFFFFFFFF) Return 1 Else Both valid Return 0 CHECK - what type of locking mechanisms should be used????

#### LINUX

Kernel Hackers Manual January 2008
mpt_readScsiDevicePageHeaders
9
2.6.24-rc6-git8

#### mpt_readScsiDevicePageHeaders

save version and length of SDP1

##### Synopsis

       int mpt_readScsiDevicePageHeaders
       MPT_ADAPTER * ioc
       int portnum

##### Arguments

`ioc`

  Pointer to a Adapter Strucutre

`portnum`

  IOC port number

##### Return

-EFAULT if read of config page header fails or 0 if success.

#### LINUX

Kernel Hackers Manual January 2008
mpt_inactive_raid_list_free
9
2.6.24-rc6-git8

#### mpt_inactive_raid_list_free

This clears this link list.

##### Synopsis

       void mpt_inactive_raid_list_free
       MPT_ADAPTER * ioc

##### Arguments

`ioc`

  pointer to per adapter structure

#### LINUX

Kernel Hackers Manual January 2008
mpt_inactive_raid_volumes
9
2.6.24-rc6-git8

#### mpt_inactive_raid_volumes

sets up link list of phy_disk_nums for devices belonging in an inactive volume

##### Synopsis

       void mpt_inactive_raid_volumes
       MPT_ADAPTER * ioc
       u8 channel
       u8 id

##### Arguments

`ioc`

  pointer to per adapter structure

`channel`

  volume channel

`id`

  volume target id

##### Description

#### LINUX

Kernel Hackers Manual January 2008
SendEventNotification
9
2.6.24-rc6-git8

#### SendEventNotification

Send EventNotification (on or off) request to adapter

##### Synopsis

       int SendEventNotification
       MPT_ADAPTER * ioc
       u8 EvSwitch

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`EvSwitch`

  Event switch flags

#### LINUX

Kernel Hackers Manual January 2008
SendEventAck
9
2.6.24-rc6-git8

#### SendEventAck

Send EventAck request to MPT adapter.

##### Synopsis

       int SendEventAck
       MPT_ADAPTER * ioc
       EventNotificationReply_t * evnp

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`evnp`

  Pointer to original EventNotification request

#### LINUX

Kernel Hackers Manual January 2008
mpt_timer_expired
9
2.6.24-rc6-git8

#### mpt_timer_expired

Callback for timer process.

##### Synopsis

       void mpt_timer_expired
       unsigned long data

##### Arguments

`data`

  Pointer to MPT_SCSI_HOST recast as an unsigned long

##### Description

Used only internal config functionality.

#### LINUX

Kernel Hackers Manual January 2008
mpt_ioc_reset
9
2.6.24-rc6-git8

#### mpt_ioc_reset

Base cleanup for hard reset

##### Synopsis

       int mpt_ioc_reset
       MPT_ADAPTER * ioc
       int reset_phase

##### Arguments

`ioc`

  Pointer to the adapter structure

`reset_phase`

  Indicates pre- or post-reset functionality

##### Remark

Frees resources with internally generated commands.

#### LINUX

Kernel Hackers Manual January 2008
procmpt_create
9
2.6.24-rc6-git8

#### procmpt_create

Create `MPT_PROCFS_MPTBASEDIR` entries.

##### Synopsis

       int procmpt_create
        void

##### Arguments

`void`

  no arguments

##### Description

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
procmpt_destroy
9
2.6.24-rc6-git8

#### procmpt_destroy

Tear down `MPT_PROCFS_MPTBASEDIR` entries.

##### Synopsis

       void procmpt_destroy
        void

##### Arguments

`void`

  no arguments

##### Description

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
procmpt_summary_read
9
2.6.24-rc6-git8

#### procmpt_summary_read

Handle read request of a summary file

##### Synopsis

       int procmpt_summary_read
       char * buf
       char ** start
       off_t offset
       int request
       int * eof
       void * data

##### Arguments

`buf`

  Pointer to area to write information

`start`

  Pointer to start pointer

`offset`

  Offset to start writing

`request`

  Amount of read data requested

`eof`

  Pointer to EOF integer

`data`

  Pointer

##### Description

Handles read request from /proc/mpt/summary or /proc/mpt/iocN/summary. Returns number of characters written to process performing the read.

#### LINUX

Kernel Hackers Manual January 2008
procmpt_version_read
9
2.6.24-rc6-git8

#### procmpt_version_read

Handle read request from /proc/mpt/version.

##### Synopsis

       int procmpt_version_read
       char * buf
       char ** start
       off_t offset
       int request
       int * eof
       void * data

##### Arguments

`buf`

  Pointer to area to write information

`start`

  Pointer to start pointer

`offset`

  Offset to start writing

`request`

  Amount of read data requested

`eof`

  Pointer to EOF integer

`data`

  Pointer

##### Description

Returns number of characters written to process performing the read.

#### LINUX

Kernel Hackers Manual January 2008
procmpt_iocinfo_read
9
2.6.24-rc6-git8

#### procmpt_iocinfo_read

Handle read request from /proc/mpt/iocN/info.

##### Synopsis

       int procmpt_iocinfo_read
       char * buf
       char ** start
       off_t offset
       int request
       int * eof
       void * data

##### Arguments

`buf`

  Pointer to area to write information

`start`

  Pointer to start pointer

`offset`

  Offset to start writing

`request`

  Amount of read data requested

`eof`

  Pointer to EOF integer

`data`

  Pointer

##### Description

Returns number of characters written to process performing the read.

#### LINUX

Kernel Hackers Manual January 2008
ProcessEventNotification
9
2.6.24-rc6-git8

#### ProcessEventNotification

Route EventNotificationReply to all event handlers

##### Synopsis

       int ProcessEventNotification
       MPT_ADAPTER * ioc
       EventNotificationReply_t * pEventReply
       int * evHandlers

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`pEventReply`

  Pointer to EventNotification reply frame

`evHandlers`

  Pointer to integer, number of event handlers

##### Description

Routes a received EventNotificationReply to all currently registered event handlers. Returns sum of event handlers return values.

#### LINUX

Kernel Hackers Manual January 2008
mpt_fc_log_info
9
2.6.24-rc6-git8

#### mpt_fc_log_info

Log information returned from Fibre Channel IOC.

##### Synopsis

       void mpt_fc_log_info
       MPT_ADAPTER * ioc
       u32 log_info

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`log_info`

  U32 LogInfo reply word from the IOC

##### Description

Refer to lsi/mpi_log_fc.h.

#### LINUX

Kernel Hackers Manual January 2008
mpt_spi_log_info
9
2.6.24-rc6-git8

#### mpt_spi_log_info

Log information returned from SCSI Parallel IOC.

##### Synopsis

       void mpt_spi_log_info
       MPT_ADAPTER * ioc
       u32 log_info

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`log_info`

  U32 LogInfo word from the IOC

##### Description

Refer to lsi/sp_log.h.

#### LINUX

Kernel Hackers Manual January 2008
mpt_sas_log_info
9
2.6.24-rc6-git8

#### mpt_sas_log_info

Log information returned from SAS IOC.

##### Synopsis

       void mpt_sas_log_info
       MPT_ADAPTER * ioc
       u32 log_info

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`log_info`

  U32 LogInfo reply word from the IOC

##### Description

Refer to lsi/mpi_log_sas.h.

#### LINUX

Kernel Hackers Manual January 2008
mpt_iocstatus_info_config
9
2.6.24-rc6-git8

#### mpt_iocstatus_info_config

IOCSTATUS information for config pages

##### Synopsis

       void mpt_iocstatus_info_config
       MPT_ADAPTER * ioc
       u32 ioc_status
       MPT_FRAME_HDR * mf

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`ioc_status`

  U32 IOCStatus word from IOC

`mf`

  Pointer to MPT request frame

##### Description

Refer to lsi/mpi.h.

#### LINUX

Kernel Hackers Manual January 2008
mpt_iocstatus_info
9
2.6.24-rc6-git8

#### mpt_iocstatus_info

IOCSTATUS information returned from IOC.

##### Synopsis

       void mpt_iocstatus_info
       MPT_ADAPTER * ioc
       u32 ioc_status
       MPT_FRAME_HDR * mf

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`ioc_status`

  U32 IOCStatus word from IOC

`mf`

  Pointer to MPT request frame

##### Description

Refer to lsi/mpi.h.

#### LINUX

Kernel Hackers Manual January 2008
fusion_init
9
2.6.24-rc6-git8

#### fusion_init

Fusion MPT base driver initialization routine.

##### Synopsis

       int __init fusion_init
        void

##### Arguments

`void`

  no arguments

##### Description

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
fusion_exit
9
2.6.24-rc6-git8

#### fusion_exit

Perform driver unload cleanup.

##### Synopsis

       void __exit fusion_exit
        void

##### Arguments

`void`

  no arguments

##### Description

This routine frees all resources associated with each MPT adapter and removes all `MPT_PROCFS_MPTBASEDIR` entries.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_info
9
2.6.24-rc6-git8

#### mptscsih_info

Return information about MPT adapter

##### Synopsis

       const char * mptscsih_info
       struct Scsi_Host * SChost

##### Arguments

`SChost`

  Pointer to Scsi_Host structure

##### Description

(linux scsi_host_template.info routine)

Returns pointer to buffer where information was written.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_proc_info
9
2.6.24-rc6-git8

#### mptscsih_proc_info

Return information about MPT adapter

##### Synopsis

       int mptscsih_proc_info
       struct Scsi_Host * host
       char * buffer
       char ** start
       off_t offset
       int length
       int func

##### Arguments

`host`

  scsi host struct

`buffer`

  if write, user data; if read, buffer for user

`start`

  returns the buffer address

`offset`

  if write, 0; if read, the current offset into the buffer from the previous read.

`length`

  if write, return length;

`func`

  write = 1; read = 0

##### Description

(linux scsi_host_template.info routine)

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_qcmd
9
2.6.24-rc6-git8

#### mptscsih_qcmd

Primary Fusion MPT SCSI initiator IO start routine.

##### Synopsis

       int mptscsih_qcmd
       struct scsi_cmnd * SCpnt
       void (*done)
         struct scsi_cmnd *

##### Arguments

`SCpnt`

  Pointer to scsi_cmnd structure

`done`

  Pointer SCSI mid-layer IO completion function

##### Description

(linux scsi_host_template.queuecommand routine) This is the primary SCSI IO start routine. Create a MPI SCSIIORequest from a linux scsi_cmnd request and send it to the IOC.

Returns 0. (rtn value discarded by linux scsi mid-layer)

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_TMHandler
9
2.6.24-rc6-git8

#### mptscsih_TMHandler

Generic handler for SCSI Task Management.

##### Synopsis

       int mptscsih_TMHandler
       MPT_SCSI_HOST * hd
       u8 type
       u8 channel
       u8 id
       int lun
       int ctx2abort
       ulong timeout

##### Arguments

`hd`

  Pointer to MPT SCSI HOST structure

`type`

  Task Management type

`channel`

  channel number for task management

`id`

  Logical Target ID for reset (if appropriate)

`lun`

  Logical Unit for reset (if appropriate)

`ctx2abort`

  Context for the task to be aborted (if appropriate)

`timeout`

  timeout for task management control

##### Fall through to mpt_HardResetHandler if

not operational, too many failed TM requests or handshake failure.

##### Remark

With old EH code, at most 1 SCSI TaskMgmt function per IOC will be active.

Returns 0 for SUCCESS, or `FAILED`.

##### Remark

With old EH code, at most 1 SCSI TaskMgmt function per IOC will be active.

Returns 0 for SUCCESS, or `FAILED`.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_abort
9
2.6.24-rc6-git8

#### mptscsih_abort

Abort linux scsi_cmnd routine, new_eh variant

##### Synopsis

       int mptscsih_abort
       struct scsi_cmnd * SCpnt

##### Arguments

`SCpnt`

  Pointer to scsi_cmnd structure, IO to be aborted

##### Description

(linux scsi_host_template.eh_abort_handler routine)

Returns SUCCESS or FAILED.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_dev_reset
9
2.6.24-rc6-git8

#### mptscsih_dev_reset

Perform a SCSI TARGET_RESET! new_eh variant

##### Synopsis

       int mptscsih_dev_reset
       struct scsi_cmnd * SCpnt

##### Arguments

`SCpnt`

  Pointer to scsi_cmnd structure, IO which reset is due to

##### Description

(linux scsi_host_template.eh_dev_reset_handler routine)

Returns SUCCESS or FAILED.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_bus_reset
9
2.6.24-rc6-git8

#### mptscsih_bus_reset

Perform a SCSI BUS_RESET! new_eh variant

##### Synopsis

       int mptscsih_bus_reset
       struct scsi_cmnd * SCpnt

##### Arguments

`SCpnt`

  Pointer to scsi_cmnd structure, IO which reset is due to

##### Description

(linux scsi_host_template.eh_bus_reset_handler routine)

Returns SUCCESS or FAILED.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_host_reset
9
2.6.24-rc6-git8

#### mptscsih_host_reset

Perform a SCSI host adapter RESET (new_eh variant)

##### Synopsis

       int mptscsih_host_reset
       struct scsi_cmnd * SCpnt

##### Arguments

`SCpnt`

  Pointer to scsi_cmnd structure, IO which reset is due to

##### Description

(linux scsi_host_template.eh_host_reset_handler routine)

Returns SUCCESS or FAILED.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_taskmgmt_complete
9
2.6.24-rc6-git8

#### mptscsih_taskmgmt_complete

Registered with Fusion MPT base driver

##### Synopsis

       int mptscsih_taskmgmt_complete
       MPT_ADAPTER * ioc
       MPT_FRAME_HDR * mf
       MPT_FRAME_HDR * mr

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`mf`

  Pointer to SCSI task mgmt request frame

`mr`

  Pointer to SCSI task mgmt reply frame

##### Description

This routine is called from mptbase.c::`mpt_interrupt` at the completion of any SCSI task management request. This routine is registered with the MPT (base) driver at driver load/init time via the `mpt_register` API call.

Returns 1 indicating alloc'd request frame ptr should be freed.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_add_sge
9
2.6.24-rc6-git8

#### mptscsih_add_sge

Place a simple SGE at address pAddr.

##### Synopsis

       void mptscsih_add_sge
       char * pAddr
       u32 flagslength
       dma_addr_t dma_addr

##### Arguments

`pAddr`

  virtual address for SGE

`flagslength`

  SGE flags and data transfer length

`dma_addr`

  Physical address

##### Description

This routine places a MPT request frame back on the MPT adapter's FreeQ.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_add_chain
9
2.6.24-rc6-git8

#### mptscsih_add_chain

Place a chain SGE at address pAddr.

##### Synopsis

       void mptscsih_add_chain
       char * pAddr
       u8 next
       u16 length
       dma_addr_t dma_addr

##### Arguments

`pAddr`

  virtual address for SGE

`next`

  nextChainOffset value (u32's)

`length`

  length of next SGL segment

`dma_addr`

  Physical address

##### Description

This routine places a MPT request frame back on the MPT adapter's FreeQ.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_info_scsiio
9
2.6.24-rc6-git8

#### mptscsih_info_scsiio

debug print info on reply frame

##### Synopsis

       void mptscsih_info_scsiio
       MPT_ADAPTER * ioc
       struct scsi_cmnd * sc
       SCSIIOReply_t * pScsiReply

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`sc`

  original scsi cmnd pointer

`pScsiReply`

  Pointer to MPT reply frame

##### Description

MPT_DEBUG_REPLY needs to be enabled to obtain this info

Refer to lsi/mpi.h.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_IssueTaskMgmt
9
2.6.24-rc6-git8

#### mptscsih_IssueTaskMgmt

Generic send Task Management function.

##### Synopsis

       int mptscsih_IssueTaskMgmt
       MPT_SCSI_HOST * hd
       u8 type
       u8 channel
       u8 id
       int lun
       int ctx2abort
       ulong timeout

##### Arguments

`hd`

  Pointer to MPT_SCSI_HOST structure

`type`

  Task Management type

`channel`

  channel number for task management

`id`

  Logical Target ID for reset (if appropriate)

`lun`

  Logical Unit for reset (if appropriate)

`ctx2abort`

  Context for the task to be aborted (if appropriate)

`timeout`

  timeout for task management control

##### Remark

_HardResetHandler can be invoked from an interrupt thread (timer) or a non-interrupt thread. In the former, must not call `schedule`.

Not all fields are meaningfull for all task types.

Returns 0 for SUCCESS, or FAILED.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_tm_pending_wait
9
2.6.24-rc6-git8

#### mptscsih_tm_pending_wait

wait for pending task management request to complete

##### Synopsis

       int mptscsih_tm_pending_wait
       MPT_SCSI_HOST * hd

##### Arguments

`hd`

  Pointer to MPT host structure.

##### Description

Returns {SUCCESS,FAILED}.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_tm_wait_for_completion
9
2.6.24-rc6-git8

#### mptscsih_tm_wait_for_completion

wait for completion of TM task

##### Synopsis

       int mptscsih_tm_wait_for_completion
       MPT_SCSI_HOST * hd
       ulong timeout

##### Arguments

`hd`

  Pointer to MPT host structure.

`timeout`

  timeout value

##### Description

Returns {SUCCESS,FAILED}.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_get_scsi_lookup
9
2.6.24-rc6-git8

#### mptscsih_get_scsi_lookup

##### Synopsis

       struct scsi_cmnd * mptscsih_get_scsi_lookup
       MPT_ADAPTER * ioc
       int i

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`i`

  index into the array

##### Description

Returns the scsi_cmd pointer

##### Description

Returns the scsi_cmd pointer

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_getclear_scsi_lookup
9
2.6.24-rc6-git8

#### mptscsih_getclear_scsi_lookup

##### Synopsis

       struct scsi_cmnd * mptscsih_getclear_scsi_lookup
       MPT_ADAPTER * ioc
       int i

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`i`

  index into the array

##### Description

Returns the scsi_cmd pointer

##### Description

Returns the scsi_cmd pointer

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_set_scsi_lookup
9
2.6.24-rc6-git8

#### mptscsih_set_scsi_lookup

##### Synopsis

       void mptscsih_set_scsi_lookup
       MPT_ADAPTER * ioc
       int i
       struct scsi_cmnd * scmd

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`i`

  index into the array

`scmd`

  scsi_cmnd pointer

##### Description

writes a scmd entry into the ScsiLookup[] array list

#### LINUX

Kernel Hackers Manual January 2008
SCPNT_TO_LOOKUP_IDX
9
2.6.24-rc6-git8

#### SCPNT_TO_LOOKUP_IDX

searches for a given scmd in the ScsiLookup[] array list

##### Synopsis

       int SCPNT_TO_LOOKUP_IDX
       MPT_ADAPTER * ioc
       struct scsi_cmnd * sc

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`sc`

  scsi_cmnd pointer

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_do_cmd
9
2.6.24-rc6-git8

#### mptscsih_do_cmd

Do internal command.

##### Synopsis

       int mptscsih_do_cmd
       MPT_SCSI_HOST * hd
       INTERNAL_CMD * io

##### Arguments

`hd`

  MPT_SCSI_HOST pointer

`io`

  INTERNAL_CMD pointer.

##### Description

Issue the specified internally generated command and do command specific cleanup. For bus scan / DV only.

##### NOTES

If command is Inquiry and status is good, initialize a target structure, save the data

##### Remark

Single threaded access only.

##### Return

< 0 if an illegal command or no resources

0 if good

> 0 if command complete but some type of completion error.

#### LINUX

Kernel Hackers Manual January 2008
mptscsih_synchronize_cache
9
2.6.24-rc6-git8

#### mptscsih_synchronize_cache

Send SYNCHRONIZE_CACHE to all disks.

##### Synopsis

       void mptscsih_synchronize_cache
       MPT_SCSI_HOST * hd
       VirtDevice * vdevice

##### Arguments

`hd`

  Pointer to a SCSI HOST structure

`vdevice`

  virtual target device

##### Description

Uses the ISR, but with special processing. MUST be single-threaded.

#### LINUX

Kernel Hackers Manual January 2008
mptctl_syscall_down
9
2.6.24-rc6-git8

#### mptctl_syscall_down

Down the MPT adapter syscall semaphore.

##### Synopsis

       int mptctl_syscall_down
       MPT_ADAPTER * ioc
       int nonblock

##### Arguments

`ioc`

  Pointer to MPT adapter

`nonblock`

  boolean, non-zero if O_NONBLOCK is set

##### Description

All of the ioctl commands can potentially sleep, which is illegal with a spinlock held, thus we perform mutual exclusion here.

Returns negative errno on error, or zero for success.

#### LINUX

Kernel Hackers Manual January 2008
mptspi_setTargetNegoParms
9
2.6.24-rc6-git8

#### mptspi_setTargetNegoParms

Update the target negotiation parameters

##### Synopsis

       void mptspi_setTargetNegoParms
       MPT_SCSI_HOST * hd
       VirtTarget * target
       struct scsi_device * sdev

##### Arguments

`hd`

  Pointer to a SCSI Host Structure

`target`

  per target private data

`sdev`

  SCSI device

##### Description

Update the target negotiation parameters based on the the Inquiry data, adapter capabilities, and NVRAM settings.

#### LINUX

Kernel Hackers Manual January 2008
mptspi_writeIOCPage4
9
2.6.24-rc6-git8

#### mptspi_writeIOCPage4

write IOC Page 4

##### Synopsis

       int mptspi_writeIOCPage4
       MPT_SCSI_HOST * hd
       u8 channel
       u8 id

##### Arguments

`hd`

  Pointer to a SCSI Host Structure

`channel`

  channel number

`id`

  write IOC Page4 for this ID & Bus

##### Return

-EAGAIN if unable to obtain a Message Frame or 0 if success.

##### Remark

We do not wait for a return, write pages sequentially.

#### LINUX

Kernel Hackers Manual January 2008
mptspi_initTarget
9
2.6.24-rc6-git8

#### mptspi_initTarget

Target, LUN alloc/free functionality.

##### Synopsis

       void mptspi_initTarget
       MPT_SCSI_HOST * hd
       VirtTarget * vtarget
       struct scsi_device * sdev

##### Arguments

`hd`

  Pointer to MPT_SCSI_HOST structure

`vtarget`

  per target private data

`sdev`

  SCSI device

##### NOTE

It's only SAFE to call this routine if data points to sane & valid STANDARD INQUIRY data!

Allocate and initialize memory for this target. Save inquiry data.

#### LINUX

Kernel Hackers Manual January 2008
mptspi_is_raid
9
2.6.24-rc6-git8

#### mptspi_is_raid

Determines whether target is belonging to volume

##### Synopsis

       int mptspi_is_raid
       struct _MPT_SCSI_HOST * hd
       u32 id

##### Arguments

`hd`

  Pointer to a SCSI HOST structure

`id`

  target device id

##### Return

non-zero = true zero = false

#### LINUX

Kernel Hackers Manual January 2008
mptspi_print_write_nego
9
2.6.24-rc6-git8

#### mptspi_print_write_nego

negotiation parameters debug info that is being sent

##### Synopsis

       void mptspi_print_write_nego
       struct _MPT_SCSI_HOST * hd
       struct scsi_target * starget
       u32 ii

##### Arguments

`hd`

  Pointer to a SCSI HOST structure

`starget`

  SCSI target

`ii`

  negotiation parameters

#### LINUX

Kernel Hackers Manual January 2008
mptspi_print_read_nego
9
2.6.24-rc6-git8

#### mptspi_print_read_nego

negotiation parameters debug info that is being read

##### Synopsis

       void mptspi_print_read_nego
       struct _MPT_SCSI_HOST * hd
       struct scsi_target * starget
       u32 ii

##### Arguments

`hd`

  Pointer to a SCSI HOST structure

`starget`

  SCSI target

`ii`

  negotiation parameters

#### LINUX

Kernel Hackers Manual January 2008
mptspi_init
9
2.6.24-rc6-git8

#### mptspi_init

Register MPT adapter(s) as SCSI host(s) with SCSI mid-layer.

##### Synopsis

       int __init mptspi_init
        void

##### Arguments

`void`

  no arguments

##### Description

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
mptspi_exit
9
2.6.24-rc6-git8

#### mptspi_exit

Unregisters MPT adapter(s)

##### Synopsis

       void __exit mptspi_exit
        void

##### Arguments

`void`

  no arguments

#### LINUX

Kernel Hackers Manual January 2008
mptfc_init
9
2.6.24-rc6-git8

#### mptfc_init

Register MPT adapter(s) as SCSI host(s) with SCSI mid-layer.

##### Synopsis

       int __init mptfc_init
        void

##### Arguments

`void`

  no arguments

##### Description

Returns 0 for success, non-zero for failure.

#### LINUX

Kernel Hackers Manual January 2008
mptfc_remove
9
2.6.24-rc6-git8

#### mptfc_remove

Remove fc infrastructure for devices

##### Synopsis

       void __devexit mptfc_remove
       struct pci_dev * pdev

##### Arguments

`pdev`

  Pointer to pci_dev structure

#### LINUX

Kernel Hackers Manual January 2008
mptfc_exit
9
2.6.24-rc6-git8

#### mptfc_exit

Unregisters MPT adapter(s)

##### Synopsis

       void __exit mptfc_exit
        void

##### Arguments

`void`

  no arguments

##### Description

#### LINUX

Kernel Hackers Manual January 2008
lan_reply
9
2.6.24-rc6-git8

#### lan_reply

Handle all data sent from the hardware.

##### Synopsis

       int lan_reply
       MPT_ADAPTER * ioc
       MPT_FRAME_HDR * mf
       MPT_FRAME_HDR * reply

##### Arguments

`ioc`

  Pointer to MPT_ADAPTER structure

`mf`

  Pointer to original MPT request frame (NULL if TurboReply)

`reply`

  Pointer to MPT reply frame

##### Description

Returns 1 indicating original alloc'd request frame ptr should be freed, or 0 if it shouldn't.

### I2O message devices

#### LINUX

Kernel Hackers Manual January 2008
i2o_sg_tablesize
9
2.6.24-rc6-git8

#### i2o_sg_tablesize

Calculate the maximum number of elements in a SGL

##### Synopsis

       u16 i2o_sg_tablesize
       struct i2o_controller * c
       u16 body_size

##### Arguments

`c`

  I2O controller for which the calculation should be done

`body_size`

  maximum body size used for message in 32-bit words.

##### Description

Return the maximum number of SG elements in a SG list.

#### LINUX

Kernel Hackers Manual January 2008
i2o_dma_map_single
9
2.6.24-rc6-git8

#### i2o_dma_map_single

Map pointer to controller and fill in I2O message.

##### Synopsis

       dma_addr_t i2o_dma_map_single
       struct i2o_controller * c
       void * ptr
       size_t size
       enum dma_data_direction direction
       u32 ** sg_ptr

##### Arguments

`c`

  I2O controller

`ptr`

  pointer to the data which should be mapped

`size`

  size of data in bytes

`direction`

  DMA_TO_DEVICE / DMA_FROM_DEVICE

`sg_ptr`

  pointer to the SG list inside the I2O message

##### Description

This function does all necessary DMA handling and also writes the I2O SGL elements into the I2O message. For details on DMA handling see also `dma_map_single`. The pointer sg_ptr will only be set to the end of the SG list if the allocation was successful.

Returns DMA address which must be checked for failures using `dma_mapping_error`.

#### LINUX

Kernel Hackers Manual January 2008
i2o_dma_map_sg
9
2.6.24-rc6-git8

#### i2o_dma_map_sg

Map a SG List to controller and fill in I2O message.

##### Synopsis

       int i2o_dma_map_sg
       struct i2o_controller * c
       struct scatterlist * sg
       int sg_count
       enum dma_data_direction direction
       u32 ** sg_ptr

##### Arguments

`c`

  I2O controller

`sg`

  SG list to be mapped

`sg_count`

  number of elements in the SG list

`direction`

  DMA_TO_DEVICE / DMA_FROM_DEVICE

`sg_ptr`

  pointer to the SG list inside the I2O message

##### Description

This function does all necessary DMA handling and also writes the I2O SGL elements into the I2O message. For details on DMA handling see also `dma_map_sg`. The pointer sg_ptr will only be set to the end of the SG list if the allocation was successful.

Returns 0 on failure or 1 on success.

#### LINUX

Kernel Hackers Manual January 2008
i2o_dma_alloc
9
2.6.24-rc6-git8

#### i2o_dma_alloc

Allocate DMA memory

##### Synopsis

       int i2o_dma_alloc
       struct device * dev
       struct i2o_dma * addr
       size_t len
       gfp_t gfp_mask

##### Arguments

`dev`

  struct device pointer to the PCI device of the I2O controller

`addr`

  i2o_dma struct which should get the DMA buffer

`len`

  length of the new DMA memory

`gfp_mask`

  GFP mask

##### Description

Allocate a coherent DMA memory and write the pointers into addr.

Returns 0 on success or -ENOMEM on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_dma_free
9
2.6.24-rc6-git8

#### i2o_dma_free

Free DMA memory

##### Synopsis

       void i2o_dma_free
       struct device * dev
       struct i2o_dma * addr

##### Arguments

`dev`

  struct device pointer to the PCI device of the I2O controller

`addr`

  i2o_dma struct which contains the DMA buffer

##### Description

Free a coherent DMA memory and set virtual address of addr to NULL.

#### LINUX

Kernel Hackers Manual January 2008
i2o_dma_realloc
9
2.6.24-rc6-git8

#### i2o_dma_realloc

Realloc DMA memory

##### Synopsis

       int i2o_dma_realloc
       struct device * dev
       struct i2o_dma * addr
       size_t len
       gfp_t gfp_mask

##### Arguments

`dev`

  struct device pointer to the PCI device of the I2O controller

`addr`

  pointer to a i2o_dma struct DMA buffer

`len`

  new length of memory

`gfp_mask`

  GFP mask

##### Description

If there was something allocated in the addr, free it first. If len > 0 than try to allocate it and write the addresses back to the addr structure. If len == 0 set the virtual address to NULL.

Returns the 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_driver_notify_controller_add
9
2.6.24-rc6-git8

#### i2o_driver_notify_controller_add

Send notification of added controller

##### Synopsis

       void i2o_driver_notify_controller_add
       struct i2o_driver * drv
       struct i2o_controller * c

##### Arguments

`drv`

  I2O driver

`c`

  I2O controller

##### Description

Send notification of added controller to a single registered driver.

#### LINUX

Kernel Hackers Manual January 2008
i2o_driver_notify_controller_remove
9
2.6.24-rc6-git8

#### i2o_driver_notify_controller_remove

Send notification of removed controller

##### Synopsis

       void i2o_driver_notify_controller_remove
       struct i2o_driver * drv
       struct i2o_controller * c

##### Arguments

`drv`

  I2O driver

`c`

  I2O controller

##### Description

Send notification of removed controller to a single registered driver.

#### LINUX

Kernel Hackers Manual January 2008
i2o_driver_notify_device_add
9
2.6.24-rc6-git8

#### i2o_driver_notify_device_add

Send notification of added device

##### Synopsis

       void i2o_driver_notify_device_add
       struct i2o_driver * drv
       struct i2o_device * i2o_dev

##### Arguments

`drv`

  I2O driver

`i2o_dev`

  the added i2o_device

##### Description

Send notification of added device to a single registered driver.

#### LINUX

Kernel Hackers Manual January 2008
i2o_driver_notify_device_remove
9
2.6.24-rc6-git8

#### i2o_driver_notify_device_remove

Send notification of removed device

##### Synopsis

       void i2o_driver_notify_device_remove
       struct i2o_driver * drv
       struct i2o_device * i2o_dev

##### Arguments

`drv`

  I2O driver

`i2o_dev`

  the added i2o_device

##### Description

Send notification of removed device to a single registered driver.

#### LINUX

Kernel Hackers Manual January 2008
i2o_msg_out_to_virt
9
2.6.24-rc6-git8

#### i2o_msg_out_to_virt

Turn an I2O message to a virtual address

##### Synopsis

       struct i2o_message * i2o_msg_out_to_virt
       struct i2o_controller * c
       u32 m

##### Arguments

`c`

  controller

`m`

  message engine value

##### Description

Turn a receive message from an I2O controller bus address into a Linux virtual address. The shared page frame is a linear block so we simply have to shift the offset. This function does not work for sender side messages as they are ioremap objects provided by the I2O controller.

#### LINUX

Kernel Hackers Manual January 2008
i2o_msg_in_to_virt
9
2.6.24-rc6-git8

#### i2o_msg_in_to_virt

Turn an I2O message to a virtual address

##### Synopsis

       struct i2o_message __iomem * i2o_msg_in_to_virt
       struct i2o_controller * c
       u32 m

##### Arguments

`c`

  controller

`m`

  message engine value

##### Description

Turn a send message from an I2O controller bus address into a Linux virtual address. The shared page frame is a linear block so we simply have to shift the offset. This function does not work for receive side messages as they are kmalloc objects in a different pool.

#### LINUX

Kernel Hackers Manual January 2008
i2o_msg_get
9
2.6.24-rc6-git8

#### i2o_msg_get

obtain an I2O message from the IOP

##### Synopsis

       struct i2o_message * i2o_msg_get
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller

##### Description

This function tries to get a message frame. If no message frame is available do not wait until one is availabe (see also i2o_msg_get_wait). The returned pointer to the message frame is not in I/O memory, it is allocated from a mempool. But because a MFA is allocated from the controller too it is guaranteed that `i2o_msg_post` will never fail.

On a success a pointer to the message frame is returned. If the message queue is empty -EBUSY is returned and if no memory is available -ENOMEM is returned.

#### LINUX

Kernel Hackers Manual January 2008
i2o_msg_post
9
2.6.24-rc6-git8

#### i2o_msg_post

Post I2O message to I2O controller

##### Synopsis

       void i2o_msg_post
       struct i2o_controller * c
       struct i2o_message * msg

##### Arguments

`c`

  I2O controller to which the message should be send

`msg`

  message returned by `i2o_msg_get`

##### Description

Post the message to the I2O controller and return immediately.

#### LINUX

Kernel Hackers Manual January 2008
i2o_msg_post_wait
9
2.6.24-rc6-git8

#### i2o_msg_post_wait

Post and wait a message and wait until return

##### Synopsis

       int i2o_msg_post_wait
       struct i2o_controller * c
       struct i2o_message * msg
       unsigned long timeout

##### Arguments

`c`

  controller

`msg`

  message to post

`timeout`

  time in seconds to wait

##### Description

This API allows an OSM to post a message and then be told whether or not the system received a successful reply. If the message times out then the value '-ETIMEDOUT' is returned.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_msg_nop_mfa
9
2.6.24-rc6-git8

#### i2o_msg_nop_mfa

Returns a fetched MFA back to the controller

##### Synopsis

       void i2o_msg_nop_mfa
       struct i2o_controller * c
       u32 mfa

##### Arguments

`c`

  I2O controller from which the MFA was fetched

`mfa`

  MFA which should be returned

##### Description

This function must be used for preserved messages, because `i2o_msg_nop` also returns the allocated memory back to the msg_pool mempool.

#### LINUX

Kernel Hackers Manual January 2008
i2o_msg_nop
9
2.6.24-rc6-git8

#### i2o_msg_nop

Returns a message which is not used

##### Synopsis

       void i2o_msg_nop
       struct i2o_controller * c
       struct i2o_message * msg

##### Arguments

`c`

  I2O controller from which the message was created

`msg`

  message which should be returned

##### Description

If you fetch a message via i2o_msg_get, and can't use it, you must return the message with this function. Otherwise the MFA is lost as well as the allocated memory from the mempool.

#### LINUX

Kernel Hackers Manual January 2008
i2o_flush_reply
9
2.6.24-rc6-git8

#### i2o_flush_reply

Flush reply from I2O controller

##### Synopsis

       void i2o_flush_reply
       struct i2o_controller * c
       u32 m

##### Arguments

`c`

  I2O controller

`m`

  the message identifier

##### Description

The I2O controller must be informed that the reply message is not needed anymore. If you forget to flush the reply, the message frame can't be used by the controller anymore and is therefore lost.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_free
9
2.6.24-rc6-git8

#### i2o_iop_free

Free the i2o_controller struct

##### Synopsis

       void i2o_iop_free
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller to free

#### LINUX

Kernel Hackers Manual January 2008
i2o_msg_get_wait
9
2.6.24-rc6-git8

#### i2o_msg_get_wait

obtain an I2O message from the IOP

##### Synopsis

       struct i2o_message * i2o_msg_get_wait
       struct i2o_controller * c
       int wait

##### Arguments

`c`

  I2O controller

`wait`

  how long to wait until timeout

##### Description

This function waits up to wait seconds for a message slot to be available.

On a success the message is returned and the pointer to the message is set in msg. The returned message is the physical page frame offset address from the read port (see the i2o spec). If no message is available returns I2O_QUEUE_EMPTY and msg is leaved untouched.

#### LINUX

Kernel Hackers Manual January 2008
i2o_cntxt_list_add
9
2.6.24-rc6-git8

#### i2o_cntxt_list_add

Append a pointer to context list and return a id

##### Synopsis

       u32 i2o_cntxt_list_add
       struct i2o_controller * c
       void * ptr

##### Arguments

`c`

  controller to which the context list belong

`ptr`

  pointer to add to the context list

##### Description

Because the context field in I2O is only 32-bit large, on 64-bit the pointer is to large to fit in the context field. The i2o_cntxt_list functions therefore map pointers to context fields.

Returns context id > 0 on success or 0 on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_cntxt_list_remove
9
2.6.24-rc6-git8

#### i2o_cntxt_list_remove

Remove a pointer from the context list

##### Synopsis

       u32 i2o_cntxt_list_remove
       struct i2o_controller * c
       void * ptr

##### Arguments

`c`

  controller to which the context list belong

`ptr`

  pointer which should be removed from the context list

##### Description

Removes a previously added pointer from the context list and returns the matching context id.

Returns context id on succes or 0 on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_cntxt_list_get
9
2.6.24-rc6-git8

#### i2o_cntxt_list_get

Get a pointer from the context list and remove it

##### Synopsis

       void * i2o_cntxt_list_get
       struct i2o_controller * c
       u32 context

##### Arguments

`c`

  controller to which the context list belong

`context`

  context id to which the pointer belong

##### Description

Returns pointer to the matching context id on success or NULL on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_cntxt_list_get_ptr
9
2.6.24-rc6-git8

#### i2o_cntxt_list_get_ptr

Get a context id from the context list

##### Synopsis

       u32 i2o_cntxt_list_get_ptr
       struct i2o_controller * c
       void * ptr

##### Arguments

`c`

  controller to which the context list belong

`ptr`

  pointer to which the context id should be fetched

##### Description

Returns context id which matches to the pointer on succes or 0 on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_find_iop
9
2.6.24-rc6-git8

#### i2o_find_iop

Find an I2O controller by id

##### Synopsis

       struct i2o_controller * i2o_find_iop
       int unit

##### Arguments

`unit`

  unit number of the I2O controller to search for

##### Description

Lookup the I2O controller on the controller list.

Returns pointer to the I2O controller on success or NULL if not found.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_find_device
9
2.6.24-rc6-git8

#### i2o_iop_find_device

Find a I2O device on an I2O controller

##### Synopsis

       struct i2o_device * i2o_iop_find_device
       struct i2o_controller * c
       u16 tid

##### Arguments

`c`

  I2O controller where the I2O device hangs on

`tid`

  TID of the I2O device to search for

##### Description

Searches the devices of the I2O controller for a device with TID tid and returns it.

Returns a pointer to the I2O device if found, otherwise NULL.

#### LINUX

Kernel Hackers Manual January 2008
i2o_status_get
9
2.6.24-rc6-git8

#### i2o_status_get

Get the status block from the I2O controller

##### Synopsis

       int i2o_status_get
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller

##### Description

Issue a status query on the controller. This updates the attached status block. The status block could then be accessed through c->status_block.

Returns 0 on sucess or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_event_register
9
2.6.24-rc6-git8

#### i2o_event_register

Turn on/off event notification for a I2O device

##### Synopsis

       int i2o_event_register
       struct i2o_device * dev
       struct i2o_driver * drv
       int tcntxt
       u32 evt_mask

##### Arguments

`dev`

  I2O device which should receive the event registration request

`drv`

  driver which want to get notified

`tcntxt`

  transaction context to use with this notifier

`evt_mask`

  mask of events

##### Description

Create and posts an event registration message to the task. No reply is waited for, or expected. If you do not want further notifications, call the i2o_event_register again with a evt_mask of 0.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_quiesce
9
2.6.24-rc6-git8

#### i2o_iop_quiesce

quiesce controller

##### Synopsis

       int i2o_iop_quiesce
       struct i2o_controller * c

##### Arguments

`c`

  controller

##### Description

Quiesce an IOP. Causes IOP to make external operation quiescent (i2o 'READY' state). Internal operation of the IOP continues normally.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_enable
9
2.6.24-rc6-git8

#### i2o_iop_enable

move controller from ready to OPERATIONAL

##### Synopsis

       int i2o_iop_enable
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller

##### Description

Enable IOP. This allows the IOP to resume external operations and reverses the effect of a quiesce. Returns zero or an error code if an error occurs.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_quiesce_all
9
2.6.24-rc6-git8

#### i2o_iop_quiesce_all

Quiesce all I2O controllers on the system

##### Synopsis

       void i2o_iop_quiesce_all
        void

##### Arguments

`void`

  no arguments

##### Description

Quiesce all I2O controllers which are connected to the system.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_enable_all
9
2.6.24-rc6-git8

#### i2o_iop_enable_all

Enables all controllers on the system

##### Synopsis

       void i2o_iop_enable_all
        void

##### Arguments

`void`

  no arguments

##### Description

Enables all I2O controllers which are connected to the system.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_clear
9
2.6.24-rc6-git8

#### i2o_iop_clear

Bring I2O controller into HOLD state

##### Synopsis

       int i2o_iop_clear
       struct i2o_controller * c

##### Arguments

`c`

  controller

##### Description

Clear an IOP to HOLD state, ie. terminate external operations, clear all input queues and prepare for a system restart. IOP's internal operation continues normally and the outbound queue is alive. The IOP is not expected to rebuild its LCT.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_init_outbound_queue
9
2.6.24-rc6-git8

#### i2o_iop_init_outbound_queue

setup the outbound message queue

##### Synopsis

       int i2o_iop_init_outbound_queue
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller

##### Description

Clear and (re)initialize IOP's outbound queue and post the message frames to the IOP.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_reset
9
2.6.24-rc6-git8

#### i2o_iop_reset

reset an I2O controller

##### Synopsis

       int i2o_iop_reset
       struct i2o_controller * c

##### Arguments

`c`

  controller to reset

##### Description

Reset the IOP into INIT state and wait until IOP gets into RESET state. Terminate all external operations, clear IOP's inbound and outbound queues, terminate all DDMs, and reload the IOP's operating environment and all local DDMs. The IOP rebuilds its LCT.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_activate
9
2.6.24-rc6-git8

#### i2o_iop_activate

Bring controller up to HOLD

##### Synopsis

       int i2o_iop_activate
       struct i2o_controller * c

##### Arguments

`c`

  controller

##### Description

This function brings an I2O controller into HOLD state. The adapter is reset if necessary and then the queues and resource table are read.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_systab_set
9
2.6.24-rc6-git8

#### i2o_iop_systab_set

Set the I2O System Table of the specified IOP

##### Synopsis

       int i2o_iop_systab_set
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller to which the system table should be send

##### Description

Before the systab could be set `i2o_systab_build` must be called.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_online
9
2.6.24-rc6-git8

#### i2o_iop_online

Bring a controller online into OPERATIONAL state.

##### Synopsis

       int i2o_iop_online
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller

##### Description

Send the system table and enable the I2O controller.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_remove
9
2.6.24-rc6-git8

#### i2o_iop_remove

Remove the I2O controller from the I2O core

##### Synopsis

       void i2o_iop_remove
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller

##### Description

Remove the I2O controller from the I2O core. If devices are attached to the controller remove these also and finally reset the controller.

#### LINUX

Kernel Hackers Manual January 2008
i2o_systab_build
9
2.6.24-rc6-git8

#### i2o_systab_build

Build system table

##### Synopsis

       int i2o_systab_build
        void

##### Arguments

`void`

  no arguments

##### Description

The system table contains information about all the IOPs in the system (duh) and is used by the Executives on the IOPs to establish peer2peer connections. We're not supporting peer2peer at the moment, but this will be needed down the road for things like lan2lan forwarding.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_parse_hrt
9
2.6.24-rc6-git8

#### i2o_parse_hrt

Parse the hardware resource table.

##### Synopsis

       int i2o_parse_hrt
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller

##### Description

We don't do anything with it except dumping it (in debug mode).

Returns 0.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_release
9
2.6.24-rc6-git8

#### i2o_iop_release

release the memory for a I2O controller

##### Synopsis

       void i2o_iop_release
       struct device * dev

##### Arguments

`dev`

  I2O controller which should be released

##### Description

Release the allocated memory. This function is called if refcount of device reaches 0 automatically.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_alloc
9
2.6.24-rc6-git8

#### i2o_iop_alloc

Allocate and initialize a i2o_controller struct

##### Synopsis

       struct i2o_controller * i2o_iop_alloc
        void

##### Arguments

`void`

  no arguments

##### Description

Allocate the necessary memory for a i2o_controller struct and initialize the lists and message mempool.

Returns a pointer to the I2O controller or a negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_add
9
2.6.24-rc6-git8

#### i2o_iop_add

Initialize the I2O controller and add him to the I2O core

##### Synopsis

       int i2o_iop_add
       struct i2o_controller * c

##### Arguments

`c`

  controller

##### Description

Initialize the I2O controller and if no error occurs add him to the I2O core.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_init
9
2.6.24-rc6-git8

#### i2o_iop_init

I2O main initialization function

##### Synopsis

       int __init i2o_iop_init
        void

##### Arguments

`void`

  no arguments

##### Description

Initialize the I2O drivers (OSM) functions, register the Executive OSM, initialize the I2O PCI part and finally initialize I2O device stuff.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_iop_exit
9
2.6.24-rc6-git8

#### i2o_iop_exit

I2O main exit function

##### Synopsis

       void __exit i2o_iop_exit
        void

##### Arguments

`void`

  no arguments

##### Description

Removes I2O controllers from PCI subsystem and shut down OSMs.

#### LINUX

Kernel Hackers Manual January 2008
i2o_config_init
9
2.6.24-rc6-git8

#### i2o_config_init

Configuration OSM initialization function

##### Synopsis

       int __init i2o_config_init
        void

##### Arguments

`void`

  no arguments

##### Description

Registers Configuration OSM in the I2O core and if old ioctl's are compiled in initialize them.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_config_exit
9
2.6.24-rc6-git8

#### i2o_config_exit

Configuration OSM exit function

##### Synopsis

       void i2o_config_exit
        void

##### Arguments

`void`

  no arguments

##### Description

If old ioctl's are compiled in exit remove them and unregisters Configuration OSM from I2O core.

#### LINUX

Kernel Hackers Manual January 2008
i2o_msg_post_wait_mem
9
2.6.24-rc6-git8

#### i2o_msg_post_wait_mem

Post and wait a message with DMA buffers

##### Synopsis

       int i2o_msg_post_wait_mem
       struct i2o_controller * c
       struct i2o_message * msg
       unsigned long timeout
       struct i2o_dma * dma

##### Arguments

`c`

  controller

`msg`

  message to post

`timeout`

  time in seconds to wait

`dma`

  i2o_dma struct of the DMA buffer to free on failure

##### Description

This API allows an OSM to post a message and then be told whether or not the system received a successful reply. If the message times out then the value '-ETIMEDOUT' is returned. This is a special case. In this situation the message may (should) complete at an indefinite time in the future. When it completes it will use the memory buffer attached to the request. If -ETIMEDOUT is returned then the memory buffer must not be freed. Instead the event completion will free them for you. In all other cases the buffer are your problem.

Returns 0 on success, negative error code on timeout or positive error code from reply.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_lct_get
9
2.6.24-rc6-git8

#### i2o_exec_lct_get

Get the IOP's Logical Configuration Table

##### Synopsis

       int i2o_exec_lct_get
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller from which the LCT should be fetched

##### Description

Send a LCT NOTIFY request to the controller, and wait I2O_TIMEOUT_LCT_GET seconds until arrival of response. If the LCT is to large, retry it.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_wait_alloc
9
2.6.24-rc6-git8

#### i2o_exec_wait_alloc

Allocate a i2o_exec_wait struct an initialize it

##### Synopsis

       struct i2o_exec_wait * i2o_exec_wait_alloc
        void

##### Arguments

`void`

  no arguments

##### Description

Allocate the i2o_exec_wait struct and initialize the wait.

Returns i2o_exec_wait pointer on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_wait_free
9
2.6.24-rc6-git8

#### i2o_exec_wait_free

Free an i2o_exec_wait struct

##### Synopsis

       void i2o_exec_wait_free
       struct i2o_exec_wait * wait

##### Arguments

`wait`

  I2O wait data which should be cleaned up

#### LINUX

Kernel Hackers Manual January 2008
i2o_msg_post_wait_complete
9
2.6.24-rc6-git8

#### i2o_msg_post_wait_complete

Reply to a i2o_msg_post request from IOP

##### Synopsis

       int i2o_msg_post_wait_complete
       struct i2o_controller * c
       u32 m
       struct i2o_message * msg
       u32 context

##### Arguments

`c`

  I2O controller which answers

`m`

  message id

`msg`

  pointer to the I2O reply message

`context`

  transaction context of request

##### Description

This function is called in interrupt context only. If the reply reached before the timeout, the i2o_exec_wait struct is filled with the message and the task will be waked up. The task is now responsible for returning the message m back to the controller! If the message reaches us after the timeout clean up the i2o_exec_wait struct (including allocated DMA buffer).

Return 0 on success and if the message m should not be given back to the I2O controller, or >0 on success and if the message should be given back afterwords. Returns negative error code on failure. In this case the message must also be given back to the controller.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_show_vendor_id
9
2.6.24-rc6-git8

#### i2o_exec_show_vendor_id

Displays Vendor ID of controller

##### Synopsis

       ssize_t i2o_exec_show_vendor_id
       struct device * d
       struct device_attribute * attr
       char * buf

##### Arguments

`d`

  device of which the Vendor ID should be displayed

`attr`

  device_attribute to display

`buf`

  buffer into which the Vendor ID should be printed

##### Description

Returns number of bytes printed into buffer.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_show_product_id
9
2.6.24-rc6-git8

#### i2o_exec_show_product_id

Displays Product ID of controller

##### Synopsis

       ssize_t i2o_exec_show_product_id
       struct device * d
       struct device_attribute * attr
       char * buf

##### Arguments

`d`

  device of which the Product ID should be displayed

`attr`

  device_attribute to display

`buf`

  buffer into which the Product ID should be printed

##### Description

Returns number of bytes printed into buffer.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_probe
9
2.6.24-rc6-git8

#### i2o_exec_probe

Called if a new I2O device (executive class) appears

##### Synopsis

       int i2o_exec_probe
       struct device * dev

##### Arguments

`dev`

  I2O device which should be probed

##### Description

Registers event notification for every event from Executive device. The return is always 0, because we want all devices of class Executive.

Returns 0 on success.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_remove
9
2.6.24-rc6-git8

#### i2o_exec_remove

Called on I2O device removal

##### Synopsis

       int i2o_exec_remove
       struct device * dev

##### Arguments

`dev`

  I2O device which was removed

##### Description

Unregisters event notification from Executive I2O device.

Returns 0 on success.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_lct_notify
9
2.6.24-rc6-git8

#### i2o_exec_lct_notify

Send a asynchronus LCT NOTIFY request

##### Synopsis

       int i2o_exec_lct_notify
       struct i2o_controller * c
       u32 change_ind

##### Arguments

`c`

  I2O controller to which the request should be send

`change_ind`

  change indicator

##### Description

This function sends a LCT NOTIFY request to the I2O controller with the change indicator change_ind. If the change_ind == 0 the controller replies immediately after the request. If change_ind > 0 the reply is send after change indicator of the LCT is > change_ind.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_lct_modified
9
2.6.24-rc6-git8

#### i2o_exec_lct_modified

Called on LCT NOTIFY reply

##### Synopsis

       void i2o_exec_lct_modified
       struct work_struct * _work

##### Arguments

`_work`

  work struct for a specific controller

##### Description

This function handles asynchronus LCT NOTIFY replies. It parses the new LCT and if the buffer for the LCT was to small sends a LCT NOTIFY again, otherwise send LCT NOTIFY to get informed on next LCT change.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_reply
9
2.6.24-rc6-git8

#### i2o_exec_reply

I2O Executive reply handler

##### Synopsis

       int i2o_exec_reply
       struct i2o_controller * c
       u32 m
       struct i2o_message * msg

##### Arguments

`c`

  I2O controller from which the reply comes

`m`

  message id

`msg`

  pointer to the I2O reply message

##### Description

This function is always called from interrupt context. If a POST WAIT reply was received, pass it to the complete function. If a LCT NOTIFY reply was received, a new event is created to handle the update.

Returns 0 on success and if the reply should not be flushed or > 0 on success and if the reply should be flushed. Returns negative error code on failure and if the reply should be flushed.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_event
9
2.6.24-rc6-git8

#### i2o_exec_event

Event handling function

##### Synopsis

       void i2o_exec_event
       struct work_struct * work

##### Arguments

`work`

  Work item in occurring event

##### Description

Handles events send by the Executive device. At the moment does not do anything useful.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_init
9
2.6.24-rc6-git8

#### i2o_exec_init

Registers the Exec OSM

##### Synopsis

       int __init i2o_exec_init
        void

##### Arguments

`void`

  no arguments

##### Description

Registers the Exec OSM in the I2O core.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_exec_exit
9
2.6.24-rc6-git8

#### i2o_exec_exit

Removes the Exec OSM

##### Synopsis

       void i2o_exec_exit
        void

##### Arguments

`void`

  no arguments

##### Description

Unregisters the Exec OSM from the I2O core.

#### LINUX

Kernel Hackers Manual January 2008
i2o_bus_scan
9
2.6.24-rc6-git8

#### i2o_bus_scan

Scan the bus for new devices

##### Synopsis

       int i2o_bus_scan
       struct i2o_device * dev

##### Arguments

`dev`

  I2O device of the bus, which should be scanned

##### Description

Scans the bus dev for new / removed devices. After the scan a new LCT will be fetched automatically.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_bus_store_scan
9
2.6.24-rc6-git8

#### i2o_bus_store_scan

Scan the I2O Bus Adapter

##### Synopsis

       ssize_t i2o_bus_store_scan
       struct device * d
       struct device_attribute * attr
       const char * buf
       size_t count

##### Arguments

`d`

  device which should be scanned

`attr`

  device_attribute

`buf`

  output buffer

`count`

  buffer size

##### Description

Returns count.

#### LINUX

Kernel Hackers Manual January 2008
i2o_bus_probe
9
2.6.24-rc6-git8

#### i2o_bus_probe

verify if dev is a I2O Bus Adapter device and install it

##### Synopsis

       int i2o_bus_probe
       struct device * dev

##### Arguments

`dev`

  device to verify if it is a I2O Bus Adapter device

##### Description

Because we want all Bus Adapters always return 0. Except when we fail. Then we are sad.

Returns 0, except when we fail to excel.

#### LINUX

Kernel Hackers Manual January 2008
i2o_bus_remove
9
2.6.24-rc6-git8

#### i2o_bus_remove

remove the I2O Bus Adapter device from the system again

##### Synopsis

       int i2o_bus_remove
       struct device * dev

##### Arguments

`dev`

  I2O Bus Adapter device which should be removed

##### Description

Always returns 0.

#### LINUX

Kernel Hackers Manual January 2008
i2o_bus_init
9
2.6.24-rc6-git8

#### i2o_bus_init

Bus Adapter OSM initialization function

##### Synopsis

       int __init i2o_bus_init
        void

##### Arguments

`void`

  no arguments

##### Description

Only register the Bus Adapter OSM in the I2O core.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_bus_exit
9
2.6.24-rc6-git8

#### i2o_bus_exit

Bus Adapter OSM exit function

##### Synopsis

       void __exit i2o_bus_exit
        void

##### Arguments

`void`

  no arguments

##### Description

Unregisters Bus Adapter OSM from I2O core.

#### LINUX

Kernel Hackers Manual January 2008
i2o_device_claim
9
2.6.24-rc6-git8

#### i2o_device_claim

claim a device for use by an OSM

##### Synopsis

       int i2o_device_claim
       struct i2o_device * dev

##### Arguments

`dev`

  I2O device to claim

##### Description

Do the leg work to assign a device to a given OSM. If the claim succeeds, the owner is the primary. If the attempt fails a negative errno code is returned. On success zero is returned.

#### LINUX

Kernel Hackers Manual January 2008
i2o_device_claim_release
9
2.6.24-rc6-git8

#### i2o_device_claim_release

release a device that the OSM is using

##### Synopsis

       int i2o_device_claim_release
       struct i2o_device * dev

##### Arguments

`dev`

  device to release

##### Description

Drop a claim by an OSM on a given I2O device.

AC - some devices seem to want to refuse an unclaim until they have finished internal processing. It makes sense since you don't want a new device to go reconfiguring the entire system until you are done. Thus we are prepared to wait briefly.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_device_issue_claim
9
2.6.24-rc6-git8

#### i2o_device_issue_claim

claim or release a device

##### Synopsis

       int i2o_device_issue_claim
       struct i2o_device * dev
       u32 cmd
       u32 type

##### Arguments

`dev`

  I2O device to claim or release

`cmd`

  claim or release command

`type`

  type of claim

##### Description

Issue I2O UTIL_CLAIM or UTIL_RELEASE messages. The message to be sent is set by cmd. dev is the I2O device which should be claim or released and the type is the claim type (see the I2O spec).

Returs 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_device_release
9
2.6.24-rc6-git8

#### i2o_device_release

release the memory for a I2O device

##### Synopsis

       void i2o_device_release
       struct device * dev

##### Arguments

`dev`

  I2O device which should be released

##### Description

Release the allocated memory. This function is called if refcount of device reaches 0 automatically.

#### LINUX

Kernel Hackers Manual January 2008
i2o_device_show_class_id
9
2.6.24-rc6-git8

#### i2o_device_show_class_id

Displays class id of I2O device

##### Synopsis

       ssize_t i2o_device_show_class_id
       struct device * dev
       struct device_attribute * attr
       char * buf

##### Arguments

`dev`

  device of which the class id should be displayed

`attr`

  pointer to device attribute

`buf`

  buffer into which the class id should be printed

##### Description

Returns the number of bytes which are printed into the buffer.

#### LINUX

Kernel Hackers Manual January 2008
i2o_device_show_tid
9
2.6.24-rc6-git8

#### i2o_device_show_tid

Displays TID of I2O device

##### Synopsis

       ssize_t i2o_device_show_tid
       struct device * dev
       struct device_attribute * attr
       char * buf

##### Arguments

`dev`

  device of which the TID should be displayed

`attr`

  pointer to device attribute

`buf`

  buffer into which the TID should be printed

##### Description

Returns the number of bytes which are printed into the buffer.

#### LINUX

Kernel Hackers Manual January 2008
i2o_device_alloc
9
2.6.24-rc6-git8

#### i2o_device_alloc

Allocate a I2O device and initialize it

##### Synopsis

       struct i2o_device * i2o_device_alloc
        void

##### Arguments

`void`

  no arguments

##### Description

Allocate the memory for a I2O device and initialize locks and lists

Returns the allocated I2O device or a negative error code if the device could not be allocated.

#### LINUX

Kernel Hackers Manual January 2008
i2o_device_add
9
2.6.24-rc6-git8

#### i2o_device_add

allocate a new I2O device and add it to the IOP

##### Synopsis

       int i2o_device_add
       struct i2o_controller * c
       i2o_lct_entry * entry

##### Arguments

`c`

  I2O controller that the device is on

`entry`

  LCT entry of the I2O device

##### Description

Allocate a new I2O device and initialize it with the LCT entry. The device is appended to the device list of the controller.

Returns zero on success, or a -ve errno.

#### LINUX

Kernel Hackers Manual January 2008
i2o_device_remove
9
2.6.24-rc6-git8

#### i2o_device_remove

remove an I2O device from the I2O core

##### Synopsis

       void i2o_device_remove
       struct i2o_device * i2o_dev

##### Arguments

`i2o_dev`

  I2O device which should be released

##### Description

Is used on I2O controller removal or LCT modification, when the device is removed from the system. Note that the device could still hang around until the refcount reaches 0.

#### LINUX

Kernel Hackers Manual January 2008
i2o_device_parse_lct
9
2.6.24-rc6-git8

#### i2o_device_parse_lct

Parse a previously fetched LCT and create devices

##### Synopsis

       int i2o_device_parse_lct
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller from which the LCT should be parsed.

##### Description

The Logical Configuration Table tells us what we can talk to on the board. For every entry we create an I2O device, which is registered in the I2O core.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_bus_match
9
2.6.24-rc6-git8

#### i2o_bus_match

Tell if I2O device class id matches the class ids of the I2O driver (OSM)

##### Synopsis

       int i2o_bus_match
       struct device * dev
       struct device_driver * drv

##### Arguments

`dev`

  device which should be verified

`drv`

  the driver to match against

##### Description

Used by the bus to check if the driver wants to handle the device.

Returns 1 if the class ids of the driver match the class id of the device, otherwise 0.

#### LINUX

Kernel Hackers Manual January 2008
i2o_driver_dispatch
9
2.6.24-rc6-git8

#### i2o_driver_dispatch

dispatch an I2O reply message

##### Synopsis

       int i2o_driver_dispatch
       struct i2o_controller * c
       u32 m

##### Arguments

`c`

  I2O controller of the message

`m`

  I2O message number

##### Description

The reply is delivered to the driver from which the original message was. This function is only called from interrupt context.

Returns 0 on success and the message should not be flushed. Returns > 0 on success and if the message should be flushed afterwords. Returns negative error code on failure (the message will be flushed too).

#### LINUX

Kernel Hackers Manual January 2008
i2o_driver_init
9
2.6.24-rc6-git8

#### i2o_driver_init

initialize I2O drivers (OSMs)

##### Synopsis

       int __init i2o_driver_init
        void

##### Arguments

`void`

  no arguments

##### Description

Registers the I2O bus and allocate memory for the array of OSMs.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_driver_exit
9
2.6.24-rc6-git8

#### i2o_driver_exit

clean up I2O drivers (OSMs)

##### Synopsis

       void i2o_driver_exit
        void

##### Arguments

`void`

  no arguments

##### Description

Unregisters the I2O bus and frees driver array.

#### LINUX

Kernel Hackers Manual January 2008
i2o_pci_free
9
2.6.24-rc6-git8

#### i2o_pci_free

Frees the DMA memory for the I2O controller

##### Synopsis

       void i2o_pci_free
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller to free

##### Description

Remove all allocated DMA memory and unmap memory IO regions. If MTRR is enabled, also remove it again.

#### LINUX

Kernel Hackers Manual January 2008
i2o_pci_alloc
9
2.6.24-rc6-git8

#### i2o_pci_alloc

Allocate DMA memory, map IO memory for I2O controller

##### Synopsis

       int i2o_pci_alloc
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller

##### Description

Allocate DMA memory for a PCI (or in theory AGP) I2O controller. All IO mappings are also done here. If MTRR is enabled, also do add memory regions here.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_pci_interrupt
9
2.6.24-rc6-git8

#### i2o_pci_interrupt

Interrupt handler for I2O controller

##### Synopsis

       irqreturn_t i2o_pci_interrupt
       int irq
       void * dev_id

##### Arguments

`irq`

  interrupt line

`dev_id`

  pointer to the I2O controller

##### Description

Handle an interrupt from a PCI based I2O controller. This turns out to be rather simple. We keep the controller pointer in the cookie.

#### LINUX

Kernel Hackers Manual January 2008
i2o_pci_irq_enable
9
2.6.24-rc6-git8

#### i2o_pci_irq_enable

Allocate interrupt for I2O controller

##### Synopsis

       int i2o_pci_irq_enable
       struct i2o_controller * c

##### Arguments

`c`

  i2o_controller that the request is for

##### Description

Allocate an interrupt for the I2O controller, and activate interrupts on the I2O controller.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_pci_irq_disable
9
2.6.24-rc6-git8

#### i2o_pci_irq_disable

Free interrupt for I2O controller

##### Synopsis

       void i2o_pci_irq_disable
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller

##### Description

Disable interrupts in I2O controller and then free interrupt.

#### LINUX

Kernel Hackers Manual January 2008
i2o_pci_probe
9
2.6.24-rc6-git8

#### i2o_pci_probe

Probe the PCI device for an I2O controller

##### Synopsis

       int i2o_pci_probe
       struct pci_dev * pdev
       const struct pci_device_id * id

##### Arguments

`pdev`

  PCI device to test

`id`

  id which matched with the PCI device id table

##### Description

Probe the PCI device for any device which is a memory of the Intelligent, I2O class or an Adaptec Zero Channel Controller. We attempt to set up each such device and register it with the core.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_pci_remove
9
2.6.24-rc6-git8

#### i2o_pci_remove

Removes a I2O controller from the system

##### Synopsis

       void __devexit i2o_pci_remove
       struct pci_dev * pdev

##### Arguments

`pdev`

  I2O controller which should be removed

##### Description

Reset the I2O controller, disable interrupts and remove all allocated resources.

#### LINUX

Kernel Hackers Manual January 2008
i2o_pci_init
9
2.6.24-rc6-git8

#### i2o_pci_init

registers I2O PCI driver in PCI subsystem

##### Synopsis

       int __init i2o_pci_init
        void

##### Arguments

`void`

  no arguments

##### Description

Returns > 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_pci_exit
9
2.6.24-rc6-git8

#### i2o_pci_exit

unregisters I2O PCI driver from PCI subsystem

##### Synopsis

       void __exit i2o_pci_exit
        void

##### Arguments

`void`

  no arguments

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_device_free
9
2.6.24-rc6-git8

#### i2o_block_device_free

free the memory of the I2O Block device

##### Synopsis

       void i2o_block_device_free
       struct i2o_block_device * dev

##### Arguments

`dev`

  I2O Block device, which should be cleaned up

##### Description

Frees the request queue, gendisk and the i2o_block_device structure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_remove
9
2.6.24-rc6-git8

#### i2o_block_remove

remove the I2O Block device from the system again

##### Synopsis

       int i2o_block_remove
       struct device * dev

##### Arguments

`dev`

  I2O Block device which should be removed

##### Description

Remove gendisk from system and free all allocated memory.

Always returns 0.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_device_flush
9
2.6.24-rc6-git8

#### i2o_block_device_flush

Flush all dirty data of I2O device dev

##### Synopsis

       int i2o_block_device_flush
       struct i2o_device * dev

##### Arguments

`dev`

  I2O device which should be flushed

##### Description

Flushes all dirty data on device dev.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_device_mount
9
2.6.24-rc6-git8

#### i2o_block_device_mount

Mount (load) the media of device dev

##### Synopsis

       int i2o_block_device_mount
       struct i2o_device * dev
       u32 media_id

##### Arguments

`dev`

  I2O device which should receive the mount request

`media_id`

  Media Identifier

##### Description

Load a media into drive. Identifier should be set to -1, because the spec does not support any other value.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_device_lock
9
2.6.24-rc6-git8

#### i2o_block_device_lock

Locks the media of device dev

##### Synopsis

       int i2o_block_device_lock
       struct i2o_device * dev
       u32 media_id

##### Arguments

`dev`

  I2O device which should receive the lock request

`media_id`

  Media Identifier

##### Description

Lock media of device dev to prevent removal. The media identifier should be set to -1, because the spec does not support any other value.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_device_unlock
9
2.6.24-rc6-git8

#### i2o_block_device_unlock

Unlocks the media of device dev

##### Synopsis

       int i2o_block_device_unlock
       struct i2o_device * dev
       u32 media_id

##### Arguments

`dev`

  I2O device which should receive the unlocked request

`media_id`

  Media Identifier

##### Description

Unlocks the media in device dev. The media identifier should be set to -1, because the spec does not support any other value.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_device_power
9
2.6.24-rc6-git8

#### i2o_block_device_power

Power management for device dev

##### Synopsis

       int i2o_block_device_power
       struct i2o_block_device * dev
       u8 op

##### Arguments

`dev`

  I2O device which should receive the power management request

`op`

  Operation to send

##### Description

Send a power management request to the device dev.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_request_alloc
9
2.6.24-rc6-git8

#### i2o_block_request_alloc

Allocate an I2O block request struct

##### Synopsis

       struct i2o_block_request * i2o_block_request_alloc
        void

##### Arguments

`void`

  no arguments

##### Description

Allocates an I2O block request struct and initialize the list.

Returns a i2o_block_request pointer on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_request_free
9
2.6.24-rc6-git8

#### i2o_block_request_free

Frees a I2O block request

##### Synopsis

       void i2o_block_request_free
       struct i2o_block_request * ireq

##### Arguments

`ireq`

  I2O block request which should be freed

##### Description

Frees the allocated memory (give it back to the request mempool).

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_sglist_alloc
9
2.6.24-rc6-git8

#### i2o_block_sglist_alloc

Allocate the SG list and map it

##### Synopsis

       int i2o_block_sglist_alloc
       struct i2o_controller * c
       struct i2o_block_request * ireq
       u32 ** mptr

##### Arguments

`c`

  I2O controller to which the request belongs

`ireq`

  I2O block request

`mptr`

  message body pointer

##### Description

Builds the SG list and map it to be accessable by the controller.

Returns 0 on failure or 1 on success.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_sglist_free
9
2.6.24-rc6-git8

#### i2o_block_sglist_free

Frees the SG list

##### Synopsis

       void i2o_block_sglist_free
       struct i2o_block_request * ireq

##### Arguments

`ireq`

  I2O block request from which the SG should be freed

##### Description

Frees the SG list from the I2O block request.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_prep_req_fn
9
2.6.24-rc6-git8

#### i2o_block_prep_req_fn

Allocates I2O block device specific struct

##### Synopsis

       int i2o_block_prep_req_fn
       struct request_queue * q
       struct request * req

##### Arguments

`q`

  request queue for the request

`req`

  the request to prepare

##### Description

Allocate the necessary i2o_block_request struct and connect it to the request. This is needed that we not loose the SG list later on.

Returns BLKPREP_OK on success or BLKPREP_DEFER on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_delayed_request_fn
9
2.6.24-rc6-git8

#### i2o_block_delayed_request_fn

delayed request queue function

##### Synopsis

       void i2o_block_delayed_request_fn
       struct work_struct * work

##### Arguments

`work`

  the delayed request with the queue to start

##### Description

If the request queue is stopped for a disk, and there is no open request, a new event is created, which calls this function to start the queue after I2O_BLOCK_REQUEST_TIME. Otherwise the queue will never be started again.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_end_request
9
2.6.24-rc6-git8

#### i2o_block_end_request

Post-processing of completed commands

##### Synopsis

       void i2o_block_end_request
       struct request * req
       int uptodate
       int nr_bytes

##### Arguments

`req`

  request which should be completed

`uptodate`

  1 for success, 0 for I/O error, < 0 for specific error

`nr_bytes`

  number of bytes to complete

##### Description

Mark the request as complete. The lock must not be held when entering.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_reply
9
2.6.24-rc6-git8

#### i2o_block_reply

Block OSM reply handler.

##### Synopsis

       int i2o_block_reply
       struct i2o_controller * c
       u32 m
       struct i2o_message * msg

##### Arguments

`c`

  I2O controller from which the message arrives

`m`

  message id of reply

`msg`

  the actual I2O message reply

##### Description

This function gets all the message replies.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_open
9
2.6.24-rc6-git8

#### i2o_block_open

Open the block device

##### Synopsis

       int i2o_block_open
       struct inode * inode
       struct file * file

##### Arguments

`inode`

  inode for block device being opened

`file`

  file to open

##### Description

Power up the device, mount and lock the media. This function is called, if the block device is opened for access.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_release
9
2.6.24-rc6-git8

#### i2o_block_release

Release the I2O block device

##### Synopsis

       int i2o_block_release
       struct inode * inode
       struct file * file

##### Arguments

`inode`

  inode for block device being released

`file`

  file to close

##### Description

Unlock and unmount the media, and power down the device. Gets called if the block device is closed.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_ioctl
9
2.6.24-rc6-git8

#### i2o_block_ioctl

Issue device specific ioctl calls.

##### Synopsis

       int i2o_block_ioctl
       struct inode * inode
       struct file * file
       unsigned int cmd
       unsigned long arg

##### Arguments

`inode`

  inode for block device ioctl

`file`

  file for ioctl

`cmd`

  ioctl command

`arg`

  arg

##### Description

Handles ioctl request for the block device.

Return 0 on success or negative error on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_media_changed
9
2.6.24-rc6-git8

#### i2o_block_media_changed

Have we seen a media change?

##### Synopsis

       int i2o_block_media_changed
       struct gendisk * disk

##### Arguments

`disk`

  gendisk which should be verified

##### Description

Verifies if the media has changed.

Returns 1 if the media was changed or 0 otherwise.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_transfer
9
2.6.24-rc6-git8

#### i2o_block_transfer

Transfer a request to/from the I2O controller

##### Synopsis

       int i2o_block_transfer
       struct request * req

##### Arguments

`req`

  the request which should be transfered

##### Description

This function converts the request into a I2O message. The necessary DMA buffers are allocated and after everything is setup post the message to the I2O controller. No cleanup is done by this function. It is done on the interrupt side when the reply arrives.

Return 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_request_fn
9
2.6.24-rc6-git8

#### i2o_block_request_fn

request queue handling function

##### Synopsis

       void i2o_block_request_fn
       struct request_queue * q

##### Arguments

`q`

  request queue from which the request could be fetched

##### Description

Takes the next request from the queue, transfers it and if no error occurs dequeue it from the queue. On arrival of the reply the message will be processed further. If an error occurs requeue the request.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_device_alloc
9
2.6.24-rc6-git8

#### i2o_block_device_alloc

Allocate memory for a I2O Block device

##### Synopsis

       struct i2o_block_device * i2o_block_device_alloc
        void

##### Arguments

`void`

  no arguments

##### Description

Allocate memory for the i2o_block_device struct, gendisk and request queue and initialize them as far as no additional information is needed.

Returns a pointer to the allocated I2O Block device on succes or a negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_probe
9
2.6.24-rc6-git8

#### i2o_block_probe

verify if dev is a I2O Block device and install it

##### Synopsis

       int i2o_block_probe
       struct device * dev

##### Arguments

`dev`

  device to verify if it is a I2O Block device

##### Description

We only verify if the user_tid of the device is 0xfff and then install the device. Otherwise it is used by some other device (e. g. RAID).

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_init
9
2.6.24-rc6-git8

#### i2o_block_init

Block OSM initialization function

##### Synopsis

       int __init i2o_block_init
        void

##### Arguments

`void`

  no arguments

##### Description

Allocate the slab and mempool for request structs, registers i2o_block block device and finally register the Block OSM in the I2O core.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_block_exit
9
2.6.24-rc6-git8

#### i2o_block_exit

Block OSM exit function

##### Synopsis

       void __exit i2o_block_exit
        void

##### Arguments

`void`

  no arguments

##### Description

Unregisters Block OSM from I2O core, unregisters i2o_block block device and frees the mempool and slab.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_get_host
9
2.6.24-rc6-git8

#### i2o_scsi_get_host

Get an I2O SCSI host

##### Synopsis

       struct i2o_scsi_host * i2o_scsi_get_host
       struct i2o_controller * c

##### Arguments

`c`

  I2O controller to for which to get the SCSI host

##### Description

If the I2O controller already exists as SCSI host, the SCSI host is returned, otherwise the I2O controller is added to the SCSI core.

Returns pointer to the I2O SCSI host on success or NULL on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_remove
9
2.6.24-rc6-git8

#### i2o_scsi_remove

Remove I2O device from SCSI core

##### Synopsis

       int i2o_scsi_remove
       struct device * dev

##### Arguments

`dev`

  device which should be removed

##### Description

Removes the I2O device from the SCSI core again.

Returns 0 on success.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_probe
9
2.6.24-rc6-git8

#### i2o_scsi_probe

verify if dev is a I2O SCSI device and install it

##### Synopsis

       int i2o_scsi_probe
       struct device * dev

##### Arguments

`dev`

  device to verify if it is a I2O SCSI device

##### Description

Retrieve channel, id and lun for I2O device. If everthing goes well register the I2O device as SCSI device on the I2O SCSI controller.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_reply
9
2.6.24-rc6-git8

#### i2o_scsi_reply

SCSI OSM message reply handler

##### Synopsis

       int i2o_scsi_reply
       struct i2o_controller * c
       u32 m
       struct i2o_message * msg

##### Arguments

`c`

  controller issuing the reply

`m`

  message id for flushing

`msg`

  the message from the controller

##### Description

Process reply messages (interrupts in normal scsi controller think). We can get a variety of messages to process. The normal path is scsi command completions. We must also deal with IOP failures, the reply to a bus reset and the reply to a LUN query.

Returns 0 on success and if the reply should not be flushed or > 0 on success and if the reply should be flushed. Returns negative error code on failure and if the reply should be flushed.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_notify_device_add
9
2.6.24-rc6-git8

#### i2o_scsi_notify_device_add

Retrieve notifications of added devices

##### Synopsis

       void i2o_scsi_notify_device_add
       struct i2o_device * i2o_dev

##### Arguments

`i2o_dev`

  the I2O device which was added

##### Description

If a I2O device is added we catch the notification, because I2O classes other then SCSI peripheral will not be received through `i2o_scsi_probe`.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_notify_device_remove
9
2.6.24-rc6-git8

#### i2o_scsi_notify_device_remove

Retrieve notifications of removed devices

##### Synopsis

       void i2o_scsi_notify_device_remove
       struct i2o_device * i2o_dev

##### Arguments

`i2o_dev`

  the I2O device which was removed

##### Description

If a I2O device is removed, we catch the notification to remove the corresponding SCSI device.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_notify_controller_add
9
2.6.24-rc6-git8

#### i2o_scsi_notify_controller_add

Retrieve notifications of added controllers

##### Synopsis

       void i2o_scsi_notify_controller_add
       struct i2o_controller * c

##### Arguments

`c`

  the controller which was added

##### Description

If a I2O controller is added, we catch the notification to add a corresponding Scsi_Host.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_notify_controller_remove
9
2.6.24-rc6-git8

#### i2o_scsi_notify_controller_remove

Retrieve notifications of removed controllers

##### Synopsis

       void i2o_scsi_notify_controller_remove
       struct i2o_controller * c

##### Arguments

`c`

  the controller which was removed

##### Description

If a I2O controller is removed, we catch the notification to remove the corresponding Scsi_Host.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_queuecommand
9
2.6.24-rc6-git8

#### i2o_scsi_queuecommand

queue a SCSI command

##### Synopsis

       int i2o_scsi_queuecommand
       struct scsi_cmnd * SCpnt
       void (*done)
         struct scsi_cmnd *

##### Arguments

`SCpnt`

  scsi command pointer

`done`

  callback for completion

##### Description

Issue a scsi command asynchronously. Return 0 on success or 1 if we hit an error (normally message queue congestion). The only minor complication here is that I2O deals with the device addressing so we have to map the bus/dev/lun back to an I2O handle as well as faking absent devices ourself.

##### Locks

takes the controller lock on error path only

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_abort
9
2.6.24-rc6-git8

#### i2o_scsi_abort

abort a running command

##### Synopsis

       int i2o_scsi_abort
       struct scsi_cmnd * SCpnt

##### Arguments

`SCpnt`

  command to abort

##### Description

Ask the I2O controller to abort a command. This is an asynchrnous process and our callback handler will see the command complete with an aborted message if it succeeds.

Returns 0 if the command is successfully aborted or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_bios_param
9
2.6.24-rc6-git8

#### i2o_scsi_bios_param

Invent disk geometry

##### Synopsis

       int i2o_scsi_bios_param
       struct scsi_device * sdev
       struct block_device * dev
       sector_t capacity
       int * ip

##### Arguments

`sdev`

  scsi device

`dev`

  block layer device

`capacity`

  size in sectors

`ip`

  geometry array

##### Description

This is anyone's guess quite frankly. We use the same rules everyone else appears to and hope. It seems to work.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_init
9
2.6.24-rc6-git8

#### i2o_scsi_init

SCSI OSM initialization function

##### Synopsis

       int __init i2o_scsi_init
        void

##### Arguments

`void`

  no arguments

##### Description

Register SCSI OSM into I2O core.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_scsi_exit
9
2.6.24-rc6-git8

#### i2o_scsi_exit

SCSI OSM exit function

##### Synopsis

       void __exit i2o_scsi_exit
        void

##### Arguments

`void`

  no arguments

##### Description

Unregisters SCSI OSM from I2O core.

#### LINUX

Kernel Hackers Manual January 2008
i2o_get_class_name
9
2.6.24-rc6-git8

#### i2o_get_class_name

do i2o class name lookup

##### Synopsis

       const char * i2o_get_class_name
       int class

##### Arguments

`class`

  class number

##### Description

Return a descriptive string for an i2o class.

#### LINUX

Kernel Hackers Manual January 2008
i2o_proc_create_entries
9
2.6.24-rc6-git8

#### i2o_proc_create_entries

Creates proc dir entries

##### Synopsis

       int i2o_proc_create_entries
       struct proc_dir_entry * dir
       i2o_proc_entry * i2o_pe
       void * data

##### Arguments

`dir`

  proc dir entry under which the entries should be placed

`i2o_pe`

  pointer to the entries which should be added

`data`

  pointer to I2O controller or device

##### Description

Create proc dir entries for a I2O controller or I2O device.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_proc_subdir_remove
9
2.6.24-rc6-git8

#### i2o_proc_subdir_remove

Remove child entries from a proc entry

##### Synopsis

       void i2o_proc_subdir_remove
       struct proc_dir_entry * dir

##### Arguments

`dir`

  proc dir entry from which the childs should be removed

##### Description

Iterate over each i2o proc entry under dir and remove it. If the child also has entries, remove them too.

#### LINUX

Kernel Hackers Manual January 2008
i2o_proc_device_add
9
2.6.24-rc6-git8

#### i2o_proc_device_add

Add an I2O device to the proc dir

##### Synopsis

       void i2o_proc_device_add
       struct proc_dir_entry * dir
       struct i2o_device * dev

##### Arguments

`dir`

  proc dir entry to which the device should be added

`dev`

  I2O device which should be added

##### Description

Add an I2O device to the proc dir entry dir and create the entries for the device depending on the class of the I2O device.

#### LINUX

Kernel Hackers Manual January 2008
i2o_proc_iop_add
9
2.6.24-rc6-git8

#### i2o_proc_iop_add

Add an I2O controller to the i2o proc tree

##### Synopsis

       int i2o_proc_iop_add
       struct proc_dir_entry * dir
       struct i2o_controller * c

##### Arguments

`dir`

  parent proc dir entry

`c`

  I2O controller which should be added

##### Description

Add the entries to the parent proc dir entry. Also each device is added to the controllers proc dir entry.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_proc_iop_remove
9
2.6.24-rc6-git8

#### i2o_proc_iop_remove

Removes an I2O controller from the i2o proc tree

##### Synopsis

       void i2o_proc_iop_remove
       struct proc_dir_entry * dir
       struct i2o_controller * c

##### Arguments

`dir`

  parent proc dir entry

`c`

  I2O controller which should be removed

##### Description

Iterate over each i2o proc entry and search controller c. If it is found remove it from the tree.

#### LINUX

Kernel Hackers Manual January 2008
i2o_proc_fs_create
9
2.6.24-rc6-git8

#### i2o_proc_fs_create

Create the i2o proc fs.

##### Synopsis

       int __init i2o_proc_fs_create
        void

##### Arguments

`void`

  no arguments

##### Description

Iterate over each I2O controller and create the entries for it.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_proc_fs_destroy
9
2.6.24-rc6-git8

#### i2o_proc_fs_destroy

Cleanup the all i2o proc entries

##### Synopsis

       int __exit i2o_proc_fs_destroy
        void

##### Arguments

`void`

  no arguments

##### Description

Iterate over each I2O controller and remove the entries for it.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_proc_init
9
2.6.24-rc6-git8

#### i2o_proc_init

Init function for procfs

##### Synopsis

       int __init i2o_proc_init
        void

##### Arguments

`void`

  no arguments

##### Description

Registers Proc OSM and creates procfs entries.

Returns 0 on success or negative error code on failure.

#### LINUX

Kernel Hackers Manual January 2008
i2o_proc_exit
9
2.6.24-rc6-git8

#### i2o_proc_exit

Exit function for procfs

##### Synopsis

       void __exit i2o_proc_exit
        void

##### Arguments

`void`

  no arguments

##### Description

Unregisters Proc OSM and removes procfs entries.

## Sound Devices

### LINUX

Kernel Hackers Manual January 2008
snd_register_device
9
2.6.24-rc6-git8

### snd_register_device

Register the ALSA device file for the card

#### Synopsis

       int snd_register_device
       int type
       struct snd_card * card
       int dev
       const struct file_operations * f_ops
       void * private_data
       const char * name

#### Arguments

`type`

  the device type, SNDRV_DEVICE_TYPE_XXX

`card`

  the card instance

`dev`

  the device index

`f_ops`

  the file operations

`private_data`

  user pointer for f_ops->`open`

`name`

  the device file name

#### Description

Registers an ALSA device file for the given card. The operators have to be set in reg parameter.

This function uses the card's device pointer to link to the correct &struct device.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_printk
9
2.6.24-rc6-git8

### snd_printk

printk wrapper

#### Synopsis

        snd_printk
        fmt
        args...

#### Arguments

`fmt`

  format string

`args...`

  variable arguments

#### Description

Works like `print` but prints the file and the line of the caller when configured with CONFIG_SND_VERBOSE_PRINTK.

### LINUX

Kernel Hackers Manual January 2008
snd_printd
9
2.6.24-rc6-git8

### snd_printd

debug printk

#### Synopsis

        snd_printd
        fmt
        args...

#### Arguments

`fmt`

  format string

`args...`

  variable arguments

#### Description

Compiled only when Works like `snd_printk` for debugging purpose. Ignored when CONFIG_SND_DEBUG is not set.

### LINUX

Kernel Hackers Manual January 2008
snd_assert
9
2.6.24-rc6-git8

### snd_assert

run-time assertion macro

#### Synopsis

        snd_assert
        expr
        args...

#### Arguments

`expr`

  expression

`args...`

  variable arguments

#### Description

This macro checks the expression in run-time and invokes the commands given in the rest arguments if the assertion is failed. When CONFIG_SND_DEBUG is not set, the expression is executed but not checked.

### LINUX

Kernel Hackers Manual January 2008
snd_printdd
9
2.6.24-rc6-git8

### snd_printdd

debug printk

#### Synopsis

        snd_printdd
        format
        args...

#### Arguments

`format`

  format string

`args...`

  variable arguments

#### Description

Compiled only when Works like `snd_printk` for debugging purpose. Ignored when CONFIG_SND_DEBUG_DETECT is not set.

### LINUX

Kernel Hackers Manual January 2008
register_sound_special_device
9
2.6.24-rc6-git8

### register_sound_special_device

register a special sound node

#### Synopsis

       int register_sound_special_device
       const struct file_operations * fops
       int unit
       struct device * dev

#### Arguments

`fops`

  File operations for the driver

`unit`

  Unit number to allocate

`dev`

  device pointer

#### Description

Allocate a special sound device by minor number from the sound subsystem. The allocated number is returned on succes. On failure a negative error code is returned.

### LINUX

Kernel Hackers Manual January 2008
register_sound_mixer
9
2.6.24-rc6-git8

### register_sound_mixer

register a mixer device

#### Synopsis

       int register_sound_mixer
       const struct file_operations * fops
       int dev

#### Arguments

`fops`

  File operations for the driver

`dev`

  Unit number to allocate

#### Description

Allocate a mixer device. Unit is the number of the mixer requested. Pass -1 to request the next free mixer unit. On success the allocated number is returned, on failure a negative error code is returned.

### LINUX

Kernel Hackers Manual January 2008
register_sound_midi
9
2.6.24-rc6-git8

### register_sound_midi

register a midi device

#### Synopsis

       int register_sound_midi
       const struct file_operations * fops
       int dev

#### Arguments

`fops`

  File operations for the driver

`dev`

  Unit number to allocate

#### Description

Allocate a midi device. Unit is the number of the midi device requested. Pass -1 to request the next free midi unit. On success the allocated number is returned, on failure a negative error code is returned.

### LINUX

Kernel Hackers Manual January 2008
register_sound_dsp
9
2.6.24-rc6-git8

### register_sound_dsp

register a DSP device

#### Synopsis

       int register_sound_dsp
       const struct file_operations * fops
       int dev

#### Arguments

`fops`

  File operations for the driver

`dev`

  Unit number to allocate

#### Description

Allocate a DSP device. Unit is the number of the DSP requested. Pass -1 to request the next free DSP unit. On success the allocated number is returned, on failure a negative error code is returned.

This function allocates both the audio and dsp device entries together and will always allocate them as a matching pair - eg dsp3/audio3

### LINUX

Kernel Hackers Manual January 2008
unregister_sound_special
9
2.6.24-rc6-git8

### unregister_sound_special

unregister a special sound device

#### Synopsis

       void unregister_sound_special
       int unit

#### Arguments

`unit`

  unit number to allocate

#### Description

Release a sound device that was allocated with `register_sound_special`. The unit passed is the return value from the register function.

### LINUX

Kernel Hackers Manual January 2008
unregister_sound_mixer
9
2.6.24-rc6-git8

### unregister_sound_mixer

unregister a mixer

#### Synopsis

       void unregister_sound_mixer
       int unit

#### Arguments

`unit`

  unit number to allocate

#### Description

Release a sound device that was allocated with `register_sound_mixer`. The unit passed is the return value from the register function.

### LINUX

Kernel Hackers Manual January 2008
unregister_sound_midi
9
2.6.24-rc6-git8

### unregister_sound_midi

unregister a midi device

#### Synopsis

       void unregister_sound_midi
       int unit

#### Arguments

`unit`

  unit number to allocate

#### Description

Release a sound device that was allocated with `register_sound_midi`. The unit passed is the return value from the register function.

### LINUX

Kernel Hackers Manual January 2008
unregister_sound_dsp
9
2.6.24-rc6-git8

### unregister_sound_dsp

unregister a DSP device

#### Synopsis

       void unregister_sound_dsp
       int unit

#### Arguments

`unit`

  unit number to allocate

#### Description

Release a sound device that was allocated with `register_sound_dsp`. The unit passed is the return value from the register function.

Both of the allocated units are released together automatically.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_playback_ready
9
2.6.24-rc6-git8

### snd_pcm_playback_ready

check whether the playback buffer is available

#### Synopsis

       int snd_pcm_playback_ready
       struct snd_pcm_substream * substream

#### Arguments

`substream`

  the pcm substream instance

#### Description

Checks whether enough free space is available on the playback buffer.

Returns non-zero if available, or zero if not.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_capture_ready
9
2.6.24-rc6-git8

### snd_pcm_capture_ready

check whether the capture buffer is available

#### Synopsis

       int snd_pcm_capture_ready
       struct snd_pcm_substream * substream

#### Arguments

`substream`

  the pcm substream instance

#### Description

Checks whether enough capture data is available on the capture buffer.

Returns non-zero if available, or zero if not.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_playback_data
9
2.6.24-rc6-git8

### snd_pcm_playback_data

check whether any data exists on the playback buffer

#### Synopsis

       int snd_pcm_playback_data
       struct snd_pcm_substream * substream

#### Arguments

`substream`

  the pcm substream instance

#### Description

Checks whether any data exists on the playback buffer. If stop_threshold is bigger or equal to boundary, then this function returns always non-zero.

Returns non-zero if exists, or zero if not.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_playback_empty
9
2.6.24-rc6-git8

### snd_pcm_playback_empty

check whether the playback buffer is empty

#### Synopsis

       int snd_pcm_playback_empty
       struct snd_pcm_substream * substream

#### Arguments

`substream`

  the pcm substream instance

#### Description

Checks whether the playback buffer is empty.

Returns non-zero if empty, or zero if not.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_capture_empty
9
2.6.24-rc6-git8

### snd_pcm_capture_empty

check whether the capture buffer is empty

#### Synopsis

       int snd_pcm_capture_empty
       struct snd_pcm_substream * substream

#### Arguments

`substream`

  the pcm substream instance

#### Description

Checks whether the capture buffer is empty.

Returns non-zero if empty, or zero if not.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_format_cpu_endian
9
2.6.24-rc6-git8

### snd_pcm_format_cpu_endian

Check the PCM format is CPU-endian

#### Synopsis

       int snd_pcm_format_cpu_endian
       snd_pcm_format_t format

#### Arguments

`format`

  the format to check

#### Description

Returns 1 if the given PCM format is CPU-endian, 0 if opposite, or a negative error code if endian not specified.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_new_stream
9
2.6.24-rc6-git8

### snd_pcm_new_stream

create a new PCM stream

#### Synopsis

       int snd_pcm_new_stream
       struct snd_pcm * pcm
       int stream
       int substream_count

#### Arguments

`pcm`

  the pcm instance

`stream`

  the stream direction, SNDRV_PCM_STREAM_XXX

`substream_count`

  the number of substreams

#### Description

Creates a new stream for the pcm. The corresponding stream on the pcm must have been empty before calling this, i.e. zero must be given to the argument of `snd_pcm_new`.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_new
9
2.6.24-rc6-git8

### snd_pcm_new

create a new PCM instance

#### Synopsis

       int snd_pcm_new
       struct snd_card * card
       char * id
       int device
       int playback_count
       int capture_count
       struct snd_pcm ** rpcm

#### Arguments

`card`

  the card instance

`id`

  the id string

`device`

  the device index (zero based)

`playback_count`

  the number of substreams for playback

`capture_count`

  the number of substreams for capture

`rpcm`

  the pointer to store the new pcm instance

#### Description

Creates a new PCM instance.

The pcm operators have to be set afterwards to the new instance via `snd_pcm_set_ops`.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_device_new
9
2.6.24-rc6-git8

### snd_device_new

create an ALSA device component

#### Synopsis

       int snd_device_new
       struct snd_card * card
       snd_device_type_t type
       void * device_data
       struct snd_device_ops * ops

#### Arguments

`card`

  the card instance

`type`

  the device type, SNDRV_DEV_XXX

`device_data`

  the data pointer of this device

`ops`

  the operator table

#### Description

Creates a new device component for the given data pointer. The device will be assigned to the card and managed together by the card.

The data pointer plays a role as the identifier, too, so the pointer address must be unique and unchanged.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_device_free
9
2.6.24-rc6-git8

### snd_device_free

release the device from the card

#### Synopsis

       int snd_device_free
       struct snd_card * card
       void * device_data

#### Arguments

`card`

  the card instance

`device_data`

  the data pointer to release

#### Description

Removes the device from the list on the card and invokes the callbacks, dev_disconnect and dev_free, corresponding to the state. Then release the device.

Returns zero if successful, or a negative error code on failure or if the device not found.

### LINUX

Kernel Hackers Manual January 2008
snd_device_register
9
2.6.24-rc6-git8

### snd_device_register

register the device

#### Synopsis

       int snd_device_register
       struct snd_card * card
       void * device_data

#### Arguments

`card`

  the card instance

`device_data`

  the data pointer to register

#### Description

Registers the device which was already created via `snd_device_new`. Usually this is called from `snd_card_register`, but it can be called later if any new devices are created after invocation of `snd_card_register`.

Returns zero if successful, or a negative error code on failure or if the device not found.

### LINUX

Kernel Hackers Manual January 2008
snd_iprintf
9
2.6.24-rc6-git8

### snd_iprintf

printf on the procfs buffer

#### Synopsis

       int snd_iprintf
       struct snd_info_buffer * buffer
       char * fmt
        ...

#### Arguments

`buffer`

  the procfs buffer

`fmt`

  the printf format

`...`

  variable arguments

#### Description

Outputs the string on the procfs buffer just like `printf`.

Returns the size of output string.

### LINUX

Kernel Hackers Manual January 2008
snd_info_get_line
9
2.6.24-rc6-git8

### snd_info_get_line

read one line from the procfs buffer

#### Synopsis

       int snd_info_get_line
       struct snd_info_buffer * buffer
       char * line
       int len

#### Arguments

`buffer`

  the procfs buffer

`line`

  the buffer to store

`len`

  the max. buffer size - 1

#### Description

Reads one line from the buffer and stores the string.

Returns zero if successful, or 1 if error or EOF.

### LINUX

Kernel Hackers Manual January 2008
snd_info_get_str
9
2.6.24-rc6-git8

### snd_info_get_str

parse a string token

#### Synopsis

       char * snd_info_get_str
       char * dest
       char * src
       int len

#### Arguments

`dest`

  the buffer to store the string token

`src`

  the original string

`len`

  the max. length of token - 1

#### Description

Parses the original string and copy a token to the given string buffer.

Returns the updated pointer of the original string so that it can be used for the next call.

### LINUX

Kernel Hackers Manual January 2008
snd_info_create_module_entry
9
2.6.24-rc6-git8

### snd_info_create_module_entry

create an info entry for the given module

#### Synopsis

       struct snd_info_entry * snd_info_create_module_entry
       struct module * module
       const char * name
       struct snd_info_entry * parent

#### Arguments

`module`

  the module pointer

`name`

  the file name

`parent`

  the parent directory

#### Description

Creates a new info entry and assigns it to the given module.

Returns the pointer of the new instance, or NULL on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_info_create_card_entry
9
2.6.24-rc6-git8

### snd_info_create_card_entry

create an info entry for the given card

#### Synopsis

       struct snd_info_entry * snd_info_create_card_entry
       struct snd_card * card
       const char * name
       struct snd_info_entry * parent

#### Arguments

`card`

  the card instance

`name`

  the file name

`parent`

  the parent directory

#### Description

Creates a new info entry and assigns it to the given card.

Returns the pointer of the new instance, or NULL on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_card_proc_new
9
2.6.24-rc6-git8

### snd_card_proc_new

create an info entry for the given card

#### Synopsis

       int snd_card_proc_new
       struct snd_card * card
       const char * name
       struct snd_info_entry ** entryp

#### Arguments

`card`

  the card instance

`name`

  the file name

`entryp`

  the pointer to store the new info entry

#### Description

Creates a new info entry and assigns it to the given card. Unlike `snd_info_create_card_entry`, this function registers the info entry as an ALSA device component, so that it can be unregistered/released without explicit call. Also, you don't have to register this entry via `snd_info_register`, since this will be registered by `snd_card_register` automatically.

The parent is assumed as card->proc_root.

For releasing this entry, use `snd_device_free` instead of `snd_info_free_entry`.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_info_free_entry
9
2.6.24-rc6-git8

### snd_info_free_entry

release the info entry

#### Synopsis

       void snd_info_free_entry
       struct snd_info_entry * entry

#### Arguments

`entry`

  the info entry

#### Description

Releases the info entry. Don't call this after registered.

### LINUX

Kernel Hackers Manual January 2008
snd_info_register
9
2.6.24-rc6-git8

### snd_info_register

register the info entry

#### Synopsis

       int snd_info_register
       struct snd_info_entry * entry

#### Arguments

`entry`

  the info entry

#### Description

Registers the proc info entry.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_rawmidi_receive
9
2.6.24-rc6-git8

### snd_rawmidi_receive

receive the input data from the device

#### Synopsis

       int snd_rawmidi_receive
       struct snd_rawmidi_substream * substream
       const unsigned char * buffer
       int count

#### Arguments

`substream`

  the rawmidi substream

`buffer`

  the buffer pointer

`count`

  the data size to read

#### Description

Reads the data from the internal buffer.

Returns the size of read data, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_rawmidi_transmit_empty
9
2.6.24-rc6-git8

### snd_rawmidi_transmit_empty

check whether the output buffer is empty

#### Synopsis

       int snd_rawmidi_transmit_empty
       struct snd_rawmidi_substream * substream

#### Arguments

`substream`

  the rawmidi substream

#### Description

Returns 1 if the internal output buffer is empty, 0 if not.

### LINUX

Kernel Hackers Manual January 2008
snd_rawmidi_transmit_peek
9
2.6.24-rc6-git8

### snd_rawmidi_transmit_peek

copy data from the internal buffer

#### Synopsis

       int snd_rawmidi_transmit_peek
       struct snd_rawmidi_substream * substream
       unsigned char * buffer
       int count

#### Arguments

`substream`

  the rawmidi substream

`buffer`

  the buffer pointer

`count`

  data size to transfer

#### Description

Copies data from the internal output buffer to the given buffer.

Call this in the interrupt handler when the midi output is ready, and call `snd_rawmidi_transmit_ack` after the transmission is finished.

Returns the size of copied data, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_rawmidi_transmit_ack
9
2.6.24-rc6-git8

### snd_rawmidi_transmit_ack

acknowledge the transmission

#### Synopsis

       int snd_rawmidi_transmit_ack
       struct snd_rawmidi_substream * substream
       int count

#### Arguments

`substream`

  the rawmidi substream

`count`

  the tranferred count

#### Description

Advances the hardware pointer for the internal output buffer with the given size and updates the condition. Call after the transmission is finished.

Returns the advanced size if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_rawmidi_transmit
9
2.6.24-rc6-git8

### snd_rawmidi_transmit

copy from the buffer to the device

#### Synopsis

       int snd_rawmidi_transmit
       struct snd_rawmidi_substream * substream
       unsigned char * buffer
       int count

#### Arguments

`substream`

  the rawmidi substream

`buffer`

  the buffer pointer

`count`

  the data size to transfer

#### Description

Copies data from the buffer to the device and advances the pointer.

Returns the copied size if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_rawmidi_new
9
2.6.24-rc6-git8

### snd_rawmidi_new

create a rawmidi instance

#### Synopsis

       int snd_rawmidi_new
       struct snd_card * card
       char * id
       int device
       int output_count
       int input_count
       struct snd_rawmidi ** rrawmidi

#### Arguments

`card`

  the card instance

`id`

  the id string

`device`

  the device index

`output_count`

  the number of output streams

`input_count`

  the number of input streams

`rrawmidi`

  the pointer to store the new rawmidi instance

#### Description

Creates a new rawmidi instance. Use `snd_rawmidi_set_ops` to set the operators to the new instance.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_rawmidi_set_ops
9
2.6.24-rc6-git8

### snd_rawmidi_set_ops

set the rawmidi operators

#### Synopsis

       void snd_rawmidi_set_ops
       struct snd_rawmidi * rmidi
       int stream
       struct snd_rawmidi_ops * ops

#### Arguments

`rmidi`

  the rawmidi instance

`stream`

  the stream direction, SNDRV_RAWMIDI_STREAM_XXX

`ops`

  the operator table

#### Description

Sets the rawmidi operators for the given stream direction.

### LINUX

Kernel Hackers Manual January 2008
snd_request_card
9
2.6.24-rc6-git8

### snd_request_card

try to load the card module

#### Synopsis

       void snd_request_card
       int card

#### Arguments

`card`

  the card number

#### Description

Tries to load the module snd-card-X for the given card number via KMOD. Returns immediately if already loaded.

### LINUX

Kernel Hackers Manual January 2008
snd_lookup_minor_data
9
2.6.24-rc6-git8

### snd_lookup_minor_data

get user data of a registered device

#### Synopsis

       void * snd_lookup_minor_data
       unsigned int minor
       int type

#### Arguments

`minor`

  the minor number

`type`

  device type (SNDRV_DEVICE_TYPE_XXX)

#### Description

Checks that a minor device with the specified type is registered, and returns its user data pointer.

### LINUX

Kernel Hackers Manual January 2008
snd_register_device_for_dev
9
2.6.24-rc6-git8

### snd_register_device_for_dev

Register the ALSA device file for the card

#### Synopsis

       int snd_register_device_for_dev
       int type
       struct snd_card * card
       int dev
       const struct file_operations * f_ops
       void * private_data
       const char * name
       struct device * device

#### Arguments

`type`

  the device type, SNDRV_DEVICE_TYPE_XXX

`card`

  the card instance

`dev`

  the device index

`f_ops`

  the file operations

`private_data`

  user pointer for f_ops->`open`

`name`

  the device file name

`device`

  the &struct device to link this new device to

#### Description

Registers an ALSA device file for the given card. The operators have to be set in reg parameter.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_unregister_device
9
2.6.24-rc6-git8

### snd_unregister_device

unregister the device on the given card

#### Synopsis

       int snd_unregister_device
       int type
       struct snd_card * card
       int dev

#### Arguments

`type`

  the device type, SNDRV_DEVICE_TYPE_XXX

`card`

  the card instance

`dev`

  the device index

#### Description

Unregisters the device file already registered via `snd_register_device`.

Returns zero if sucecessful, or a negative error code on failure

### LINUX

Kernel Hackers Manual January 2008
copy_to_user_fromio
9
2.6.24-rc6-git8

### copy_to_user_fromio

copy data from mmio-space to user-space

#### Synopsis

       int copy_to_user_fromio
       void __user * dst
       const volatile void __iomem * src
       size_t count

#### Arguments

`dst`

  the destination pointer on user-space

`src`

  the source pointer on mmio

`count`

  the data size to copy in bytes

#### Description

Copies the data from mmio-space to user-space.

Returns zero if successful, or non-zero on failure.

### LINUX

Kernel Hackers Manual January 2008
copy_from_user_toio
9
2.6.24-rc6-git8

### copy_from_user_toio

copy data from user-space to mmio-space

#### Synopsis

       int copy_from_user_toio
       volatile void __iomem * dst
       const void __user * src
       size_t count

#### Arguments

`dst`

  the destination pointer on mmio-space

`src`

  the source pointer on user-space

`count`

  the data size to copy in bytes

#### Description

Copies the data from user-space to mmio-space.

Returns zero if successful, or non-zero on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_lib_preallocate_free_for_all
9
2.6.24-rc6-git8

### snd_pcm_lib_preallocate_free_for_all

release all pre-allocated buffers on the pcm

#### Synopsis

       int snd_pcm_lib_preallocate_free_for_all
       struct snd_pcm * pcm

#### Arguments

`pcm`

  the pcm instance

#### Description

Releases all the pre-allocated buffers on the given pcm.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_lib_preallocate_pages
9
2.6.24-rc6-git8

### snd_pcm_lib_preallocate_pages

pre-allocation for the given DMA type

#### Synopsis

       int snd_pcm_lib_preallocate_pages
       struct snd_pcm_substream * substream
       int type
       struct device * data
       size_t size
       size_t max

#### Arguments

`substream`

  the pcm substream instance

`type`

  DMA type (SNDRV_DMA_TYPE_*)

`data`

  DMA type dependant data

`size`

  the requested pre-allocation size in bytes

`max`

  the max. allowed pre-allocation size

#### Description

Do pre-allocation for the given DMA buffer type.

When substream->dma_buf_id is set, the function tries to look for the reserved buffer, and the buffer is not freed but reserved at destruction time. The dma_buf_id must be unique for all systems (in the same DMA buffer type) e.g. using `snd_dma_pci_buf_id`.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_lib_preallocate_pages_for_all
9
2.6.24-rc6-git8

### snd_pcm_lib_preallocate_pages_for_all

pre-allocation for continous memory type (all substreams)

#### Synopsis

       int snd_pcm_lib_preallocate_pages_for_all
       struct snd_pcm * pcm
       int type
       void * data
       size_t size
       size_t max

#### Arguments

`pcm`

  the pcm instance

`type`

  DMA type (SNDRV_DMA_TYPE_*)

`data`

  DMA type dependant data

`size`

  the requested pre-allocation size in bytes

`max`

  the max. allowed pre-allocation size

#### Description

Do pre-allocation to all substreams of the given pcm for the specified DMA type.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_sgbuf_ops_page
9
2.6.24-rc6-git8

### snd_pcm_sgbuf_ops_page

get the page struct at the given offset

#### Synopsis

       struct page * snd_pcm_sgbuf_ops_page
       struct snd_pcm_substream * substream
       unsigned long offset

#### Arguments

`substream`

  the pcm substream instance

`offset`

  the buffer offset

#### Description

Returns the page struct at the given buffer offset. Used as the page callback of PCM ops.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_lib_malloc_pages
9
2.6.24-rc6-git8

### snd_pcm_lib_malloc_pages

allocate the DMA buffer

#### Synopsis

       int snd_pcm_lib_malloc_pages
       struct snd_pcm_substream * substream
       size_t size

#### Arguments

`substream`

  the substream to allocate the DMA buffer to

`size`

  the requested buffer size in bytes

#### Description

Allocates the DMA buffer on the BUS type given earlier to `snd_pcm_lib_preallocate_xxx_pages`.

Returns 1 if the buffer is changed, 0 if not changed, or a negative code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_lib_free_pages
9
2.6.24-rc6-git8

### snd_pcm_lib_free_pages

release the allocated DMA buffer.

#### Synopsis

       int snd_pcm_lib_free_pages
       struct snd_pcm_substream * substream

#### Arguments

`substream`

  the substream to release the DMA buffer

#### Description

Releases the DMA buffer allocated via `snd_pcm_lib_malloc_pages`.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_card_new
9
2.6.24-rc6-git8

### snd_card_new

create and initialize a soundcard structure

#### Synopsis

       struct snd_card * snd_card_new
       int idx
       const char * xid
       struct module * module
       int extra_size

#### Arguments

`idx`

  card index (address) [0 ... (SNDRV_CARDS-1)]

`xid`

  card identification (ASCII string)

`module`

  top level module for locking

`extra_size`

  allocate this extra size after the main soundcard structure

#### Description

Creates and initializes a soundcard structure.

Returns kmallocated snd_card structure. Creates the ALSA control interface (which is blocked until snd_card_register function is called).

### LINUX

Kernel Hackers Manual January 2008
snd_card_disconnect
9
2.6.24-rc6-git8

### snd_card_disconnect

disconnect all APIs from the file-operations (user space)

#### Synopsis

       int snd_card_disconnect
       struct snd_card * card

#### Arguments

`card`

  soundcard structure

#### Description

Disconnects all APIs from the file-operations (user space).

Returns zero, otherwise a negative error code.

#### Note

The current implementation replaces all active file->f_op with special dummy file operations (they do nothing except release).

### LINUX

Kernel Hackers Manual January 2008
snd_card_register
9
2.6.24-rc6-git8

### snd_card_register

register the soundcard

#### Synopsis

       int snd_card_register
       struct snd_card * card

#### Arguments

`card`

  soundcard structure

#### Description

This function registers all the devices assigned to the soundcard. Until calling this, the ALSA control interface is blocked from the external accesses. Thus, you should call this function at the end of the initialization of the card.

Returns zero otherwise a negative error code if the registrain failed.

### LINUX

Kernel Hackers Manual January 2008
snd_component_add
9
2.6.24-rc6-git8

### snd_component_add

add a component string

#### Synopsis

       int snd_component_add
       struct snd_card * card
       const char * component

#### Arguments

`card`

  soundcard structure

`component`

  the component id string

#### Description

This function adds the component id string to the supported list. The component can be referred from the alsa-lib.

Returns zero otherwise a negative error code.

### LINUX

Kernel Hackers Manual January 2008
snd_card_file_add
9
2.6.24-rc6-git8

### snd_card_file_add

add the file to the file list of the card

#### Synopsis

       int snd_card_file_add
       struct snd_card * card
       struct file * file

#### Arguments

`card`

  soundcard structure

`file`

  file pointer

#### Description

This function adds the file to the file linked-list of the card. This linked-list is used to keep tracking the connection state, and to avoid the release of busy resources by hotplug.

Returns zero or a negative error code.

### LINUX

Kernel Hackers Manual January 2008
snd_card_file_remove
9
2.6.24-rc6-git8

### snd_card_file_remove

remove the file from the file list

#### Synopsis

       int snd_card_file_remove
       struct snd_card * card
       struct file * file

#### Arguments

`card`

  soundcard structure

`file`

  file pointer

#### Description

This function removes the file formerly added to the card via `snd_card_file_add` function. If all files are removed and `snd_card_free_when_closed` was called beforehand, it processes the pending release of resources.

Returns zero or a negative error code.

### LINUX

Kernel Hackers Manual January 2008
snd_power_wait
9
2.6.24-rc6-git8

### snd_power_wait

wait until the power-state is changed.

#### Synopsis

       int snd_power_wait
       struct snd_card * card
       unsigned int power_state

#### Arguments

`card`

  soundcard structure

`power_state`

  expected power state

#### Description

Waits until the power-state is changed.

#### Note

the power lock must be active before call.

### LINUX

Kernel Hackers Manual January 2008
snd_dma_program
9
2.6.24-rc6-git8

### snd_dma_program

program an ISA DMA transfer

#### Synopsis

       void snd_dma_program
       unsigned long dma
       unsigned long addr
       unsigned int size
       unsigned short mode

#### Arguments

`dma`

  the dma number

`addr`

  the physical address of the buffer

`size`

  the DMA transfer size

`mode`

  the DMA transfer mode, DMA_MODE_XXX

#### Description

Programs an ISA DMA transfer for the given buffer.

### LINUX

Kernel Hackers Manual January 2008
snd_dma_disable
9
2.6.24-rc6-git8

### snd_dma_disable

stop the ISA DMA transfer

#### Synopsis

       void snd_dma_disable
       unsigned long dma

#### Arguments

`dma`

  the dma number

#### Description

Stops the ISA DMA transfer.

### LINUX

Kernel Hackers Manual January 2008
snd_dma_pointer
9
2.6.24-rc6-git8

### snd_dma_pointer

return the current pointer to DMA transfer buffer in bytes

#### Synopsis

       unsigned int snd_dma_pointer
       unsigned long dma
       unsigned int size

#### Arguments

`dma`

  the dma number

`size`

  the dma transfer size

#### Description

Returns the current pointer in DMA tranfer buffer in bytes

### LINUX

Kernel Hackers Manual January 2008
snd_ctl_new1
9
2.6.24-rc6-git8

### snd_ctl_new1

create a control instance from the template

#### Synopsis

       struct snd_kcontrol * snd_ctl_new1
       const struct snd_kcontrol_new * ncontrol
       void * private_data

#### Arguments

`ncontrol`

  the initialization record

`private_data`

  the private data to set

#### Description

Allocates a new struct snd_kcontrol instance and initialize from the given template. When the access field of ncontrol is 0, it's assumed as READWRITE access. When the count field is 0, it's assumes as one.

Returns the pointer of the newly generated instance, or NULL on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_ctl_free_one
9
2.6.24-rc6-git8

### snd_ctl_free_one

release the control instance

#### Synopsis

       void snd_ctl_free_one
       struct snd_kcontrol * kcontrol

#### Arguments

`kcontrol`

  the control instance

#### Description

Releases the control instance created via `snd_ctl_new` or `snd_ctl_new1`. Don't call this after the control was added to the card.

### LINUX

Kernel Hackers Manual January 2008
snd_ctl_add
9
2.6.24-rc6-git8

### snd_ctl_add

add the control instance to the card

#### Synopsis

       int snd_ctl_add
       struct snd_card * card
       struct snd_kcontrol * kcontrol

#### Arguments

`card`

  the card instance

`kcontrol`

  the control instance to add

#### Description

Adds the control instance created via `snd_ctl_new` or `snd_ctl_new1` to the given card. Assigns also an unique numid used for fast search.

Returns zero if successful, or a negative error code on failure.

It frees automatically the control which cannot be added.

### LINUX

Kernel Hackers Manual January 2008
snd_ctl_remove
9
2.6.24-rc6-git8

### snd_ctl_remove

remove the control from the card and release it

#### Synopsis

       int snd_ctl_remove
       struct snd_card * card
       struct snd_kcontrol * kcontrol

#### Arguments

`card`

  the card instance

`kcontrol`

  the control instance to remove

#### Description

Removes the control from the card and then releases the instance. You don't need to call `snd_ctl_free_one`. You must be in the write lock - down_write(&card->controls_rwsem).

Returns 0 if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_ctl_remove_id
9
2.6.24-rc6-git8

### snd_ctl_remove_id

remove the control of the given id and release it

#### Synopsis

       int snd_ctl_remove_id
       struct snd_card * card
       struct snd_ctl_elem_id * id

#### Arguments

`card`

  the card instance

`id`

  the control id to remove

#### Description

Finds the control instance with the given id, removes it from the card list and releases it.

Returns 0 if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_ctl_rename_id
9
2.6.24-rc6-git8

### snd_ctl_rename_id

replace the id of a control on the card

#### Synopsis

       int snd_ctl_rename_id
       struct snd_card * card
       struct snd_ctl_elem_id * src_id
       struct snd_ctl_elem_id * dst_id

#### Arguments

`card`

  the card instance

`src_id`

  the old id

`dst_id`

  the new id

#### Description

Finds the control with the old id from the card, and replaces the id with the new one.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_ctl_find_numid
9
2.6.24-rc6-git8

### snd_ctl_find_numid

find the control instance with the given number-id

#### Synopsis

       struct snd_kcontrol * snd_ctl_find_numid
       struct snd_card * card
       unsigned int numid

#### Arguments

`card`

  the card instance

`numid`

  the number-id to search

#### Description

Finds the control instance with the given number-id from the card.

Returns the pointer of the instance if found, or NULL if not.

The caller must down card->controls_rwsem before calling this function (if the race condition can happen).

### LINUX

Kernel Hackers Manual January 2008
snd_ctl_find_id
9
2.6.24-rc6-git8

### snd_ctl_find_id

find the control instance with the given id

#### Synopsis

       struct snd_kcontrol * snd_ctl_find_id
       struct snd_card * card
       struct snd_ctl_elem_id * id

#### Arguments

`card`

  the card instance

`id`

  the id to search

#### Description

Finds the control instance with the given id from the card.

Returns the pointer of the instance if found, or NULL if not.

The caller must down card->controls_rwsem before calling this function (if the race condition can happen).

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_set_ops
9
2.6.24-rc6-git8

### snd_pcm_set_ops

set the PCM operators

#### Synopsis

       void snd_pcm_set_ops
       struct snd_pcm * pcm
       int direction
       struct snd_pcm_ops * ops

#### Arguments

`pcm`

  the pcm instance

`direction`

  stream direction, SNDRV_PCM_STREAM_XXX

`ops`

  the operator table

#### Description

Sets the given PCM operators to the pcm instance.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_set_sync
9
2.6.24-rc6-git8

### snd_pcm_set_sync

set the PCM sync id

#### Synopsis

       void snd_pcm_set_sync
       struct snd_pcm_substream * substream

#### Arguments

`substream`

  the pcm substream

#### Description

Sets the PCM sync identifier for the card.

### LINUX

Kernel Hackers Manual January 2008
snd_interval_refine
9
2.6.24-rc6-git8

### snd_interval_refine

refine the interval value of configurator

#### Synopsis

       int snd_interval_refine
       struct snd_interval * i
       const struct snd_interval * v

#### Arguments

`i`

  the interval value to refine

`v`

  the interval value to refer to

#### Description

Refines the interval value with the reference value. The interval is changed to the range satisfying both intervals. The interval status (min, max, integer, etc.) are evaluated.

Returns non-zero if the value is changed, zero if not changed.

### LINUX

Kernel Hackers Manual January 2008
snd_interval_ratnum
9
2.6.24-rc6-git8

### snd_interval_ratnum

refine the interval value

#### Synopsis

       int snd_interval_ratnum
       struct snd_interval * i
       unsigned int rats_count
       struct snd_ratnum * rats
       unsigned int * nump
       unsigned int * denp

#### Arguments

`i`

  interval to refine

`rats_count`

  number of ratnum_t

`rats`

  ratnum_t array

`nump`

  pointer to store the resultant numerator

`denp`

  pointer to store the resultant denominator

#### Description

Returns non-zero if the value is changed, zero if not changed.

### LINUX

Kernel Hackers Manual January 2008
snd_interval_list
9
2.6.24-rc6-git8

### snd_interval_list

refine the interval value from the list

#### Synopsis

       int snd_interval_list
       struct snd_interval * i
       unsigned int count
       unsigned int * list
       unsigned int mask

#### Arguments

`i`

  the interval value to refine

`count`

  the number of elements in the list

`list`

  the value list

`mask`

  the bit-mask to evaluate

#### Description

Refines the interval value from the list. When mask is non-zero, only the elements corresponding to bit 1 are evaluated.

Returns non-zero if the value is changed, zero if not changed.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_rule_add
9
2.6.24-rc6-git8

### snd_pcm_hw_rule_add

add the hw-constraint rule

#### Synopsis

       int snd_pcm_hw_rule_add
       struct snd_pcm_runtime * runtime
       unsigned int cond
       int var
       snd_pcm_hw_rule_func_t func
       void * private
       int dep
        ...

#### Arguments

`runtime`

  the pcm runtime instance

`cond`

  condition bits

`var`

  the variable to evaluate

`func`

  the evaluation function

`private`

  the private data pointer passed to function

`dep`

  the dependent variables

`...`

  variable arguments

#### Description

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_constraint_integer
9
2.6.24-rc6-git8

### snd_pcm_hw_constraint_integer

#### Synopsis

       int snd_pcm_hw_constraint_integer
       struct snd_pcm_runtime * runtime
       snd_pcm_hw_param_t var

#### Arguments

`runtime`

  PCM runtime instance

`var`

  hw_params variable to apply the integer constraint

#### Description

Apply the constraint of integer to an interval parameter.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_constraint_minmax
9
2.6.24-rc6-git8

### snd_pcm_hw_constraint_minmax

#### Synopsis

       int snd_pcm_hw_constraint_minmax
       struct snd_pcm_runtime * runtime
       snd_pcm_hw_param_t var
       unsigned int min
       unsigned int max

#### Arguments

`runtime`

  PCM runtime instance

`var`

  hw_params variable to apply the range

`min`

  the minimal value

`max`

  the maximal value

#### Description

Apply the min/max range constraint to an interval parameter.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_constraint_list
9
2.6.24-rc6-git8

### snd_pcm_hw_constraint_list

#### Synopsis

       int snd_pcm_hw_constraint_list
       struct snd_pcm_runtime * runtime
       unsigned int cond
       snd_pcm_hw_param_t var
       struct snd_pcm_hw_constraint_list * l

#### Arguments

`runtime`

  PCM runtime instance

`cond`

  condition bits

`var`

  hw_params variable to apply the list constraint

`l`

  list

#### Description

Apply the list of constraints to an interval parameter.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_constraint_ratnums
9
2.6.24-rc6-git8

### snd_pcm_hw_constraint_ratnums

#### Synopsis

       int snd_pcm_hw_constraint_ratnums
       struct snd_pcm_runtime * runtime
       unsigned int cond
       snd_pcm_hw_param_t var
       struct snd_pcm_hw_constraint_ratnums * r

#### Arguments

`runtime`

  PCM runtime instance

`cond`

  condition bits

`var`

  hw_params variable to apply the ratnums constraint

`r`

  struct snd_ratnums constriants

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_constraint_ratdens
9
2.6.24-rc6-git8

### snd_pcm_hw_constraint_ratdens

#### Synopsis

       int snd_pcm_hw_constraint_ratdens
       struct snd_pcm_runtime * runtime
       unsigned int cond
       snd_pcm_hw_param_t var
       struct snd_pcm_hw_constraint_ratdens * r

#### Arguments

`runtime`

  PCM runtime instance

`cond`

  condition bits

`var`

  hw_params variable to apply the ratdens constraint

`r`

  struct snd_ratdens constriants

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_constraint_msbits
9
2.6.24-rc6-git8

### snd_pcm_hw_constraint_msbits

#### Synopsis

       int snd_pcm_hw_constraint_msbits
       struct snd_pcm_runtime * runtime
       unsigned int cond
       unsigned int width
       unsigned int msbits

#### Arguments

`runtime`

  PCM runtime instance

`cond`

  condition bits

`width`

  sample bits width

`msbits`

  msbits width

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_constraint_step
9
2.6.24-rc6-git8

### snd_pcm_hw_constraint_step

#### Synopsis

       int snd_pcm_hw_constraint_step
       struct snd_pcm_runtime * runtime
       unsigned int cond
       snd_pcm_hw_param_t var
       unsigned long step

#### Arguments

`runtime`

  PCM runtime instance

`cond`

  condition bits

`var`

  hw_params variable to apply the step constraint

`step`

  step size

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_constraint_pow2
9
2.6.24-rc6-git8

### snd_pcm_hw_constraint_pow2

#### Synopsis

       int snd_pcm_hw_constraint_pow2
       struct snd_pcm_runtime * runtime
       unsigned int cond
       snd_pcm_hw_param_t var

#### Arguments

`runtime`

  PCM runtime instance

`cond`

  condition bits

`var`

  hw_params variable to apply the power-of-2 constraint

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_param_value
9
2.6.24-rc6-git8

### snd_pcm_hw_param_value

#### Synopsis

       int snd_pcm_hw_param_value
       const struct snd_pcm_hw_params * params
       snd_pcm_hw_param_t var
       int * dir

#### Arguments

`params`

  the hw_params instance

`var`

  parameter to retrieve

`dir`

  pointer to the direction (-1,0,1) or NULL

#### Description

Return the value for field PAR if it's fixed in configuration space defined by PARAMS. Return -EINVAL otherwise

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_param_first
9
2.6.24-rc6-git8

### snd_pcm_hw_param_first

#### Synopsis

       int snd_pcm_hw_param_first
       struct snd_pcm_substream * pcm
       struct snd_pcm_hw_params * params
       snd_pcm_hw_param_t var
       int * dir

#### Arguments

`pcm`

  PCM instance

`params`

  the hw_params instance

`var`

  parameter to retrieve

`dir`

  pointer to the direction (-1,0,1) or NULL

#### Description

Inside configuration space defined by PARAMS remove from PAR all values > minimum. Reduce configuration space accordingly. Return the minimum.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_hw_param_last
9
2.6.24-rc6-git8

### snd_pcm_hw_param_last

#### Synopsis

       int snd_pcm_hw_param_last
       struct snd_pcm_substream * pcm
       struct snd_pcm_hw_params * params
       snd_pcm_hw_param_t var
       int * dir

#### Arguments

`pcm`

  PCM instance

`params`

  the hw_params instance

`var`

  parameter to retrieve

`dir`

  pointer to the direction (-1,0,1) or NULL

#### Description

Inside configuration space defined by PARAMS remove from PAR all values < maximum. Reduce configuration space accordingly. Return the maximum.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_lib_ioctl
9
2.6.24-rc6-git8

### snd_pcm_lib_ioctl

a generic PCM ioctl callback

#### Synopsis

       int snd_pcm_lib_ioctl
       struct snd_pcm_substream * substream
       unsigned int cmd
       void * arg

#### Arguments

`substream`

  the pcm substream instance

`cmd`

  ioctl command

`arg`

  ioctl argument

#### Description

Processes the generic ioctl commands for PCM. Can be passed as the ioctl callback for PCM ops.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_period_elapsed
9
2.6.24-rc6-git8

### snd_pcm_period_elapsed

update the pcm status for the next period

#### Synopsis

       void snd_pcm_period_elapsed
       struct snd_pcm_substream * substream

#### Arguments

`substream`

  the pcm substream instance

#### Description

This function is called from the interrupt handler when the PCM has processed the period size. It will update the current pointer, set up the tick, wake up sleepers, etc.

Even if more than one periods have elapsed since the last call, you have to call this only once.

### LINUX

Kernel Hackers Manual January 2008
snd_hwdep_new
9
2.6.24-rc6-git8

### snd_hwdep_new

create a new hwdep instance

#### Synopsis

       int snd_hwdep_new
       struct snd_card * card
       char * id
       int device
       struct snd_hwdep ** rhwdep

#### Arguments

`card`

  the card instance

`id`

  the id string

`device`

  the device index (zero-based)

`rhwdep`

  the pointer to store the new hwdep instance

#### Description

Creates a new hwdep instance with the given index on the card. The callbacks (hwdep->ops) must be set on the returned instance after this call manually by the caller.

Returns zero if successful, or a negative error code on failure.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_stop
9
2.6.24-rc6-git8

### snd_pcm_stop

#### Synopsis

       int snd_pcm_stop
       struct snd_pcm_substream * substream
       int state

#### Arguments

`substream`

  the PCM substream instance

`state`

  PCM state after stopping the stream

#### Description

Try to stop all running streams in the substream group. The state of each stream is changed to the given value after that unconditionally.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_suspend
9
2.6.24-rc6-git8

### snd_pcm_suspend

#### Synopsis

       int snd_pcm_suspend
       struct snd_pcm_substream * substream

#### Arguments

`substream`

  the PCM substream

#### Description

Trigger SUSPEND to all linked streams. After this call, all streams are changed to SUSPENDED state.

### LINUX

Kernel Hackers Manual January 2008
snd_pcm_suspend_all
9
2.6.24-rc6-git8

### snd_pcm_suspend_all

#### Synopsis

       int snd_pcm_suspend_all
       struct snd_pcm * pcm

#### Arguments

`pcm`

  the PCM instance

#### Description

Trigger SUSPEND to all substreams in the given pcm. After this call, all streams are changed to SUSPENDED state.

### LINUX

Kernel Hackers Manual January 2008
snd_malloc_pages
9
2.6.24-rc6-git8

### snd_malloc_pages

allocate pages with the given size

#### Synopsis

       void * snd_malloc_pages
       size_t size
       gfp_t gfp_flags

#### Arguments

`size`

  the size to allocate in bytes

`gfp_flags`

  the allocation conditions, GFP_XXX

#### Description

Allocates the physically contiguous pages with the given size.

Returns the pointer of the buffer, or NULL if no enoguh memory.

### LINUX

Kernel Hackers Manual January 2008
snd_free_pages
9
2.6.24-rc6-git8

### snd_free_pages

release the pages

#### Synopsis

       void snd_free_pages
       void * ptr
       size_t size

#### Arguments

`ptr`

  the buffer pointer to release

`size`

  the allocated buffer size

#### Description

Releases the buffer allocated via `snd_malloc_pages`.

### LINUX

Kernel Hackers Manual January 2008
snd_dma_alloc_pages
9
2.6.24-rc6-git8

### snd_dma_alloc_pages

allocate the buffer area according to the given type

#### Synopsis

       int snd_dma_alloc_pages
       int type
       struct device * device
       size_t size
       struct snd_dma_buffer * dmab

#### Arguments

`type`

  the DMA buffer type

`device`

  the device pointer

`size`

  the buffer size to allocate

`dmab`

  buffer allocation record to store the allocated data

#### Description

Calls the memory-allocator function for the corresponding buffer type.

Returns zero if the buffer with the given size is allocated successfuly, other a negative value at error.

### LINUX

Kernel Hackers Manual January 2008
snd_dma_alloc_pages_fallback
9
2.6.24-rc6-git8

### snd_dma_alloc_pages_fallback

allocate the buffer area according to the given type with fallback

#### Synopsis

       int snd_dma_alloc_pages_fallback
       int type
       struct device * device
       size_t size
       struct snd_dma_buffer * dmab

#### Arguments

`type`

  the DMA buffer type

`device`

  the device pointer

`size`

  the buffer size to allocate

`dmab`

  buffer allocation record to store the allocated data

#### Description

Calls the memory-allocator function for the corresponding buffer type. When no space is left, this function reduces the size and tries to allocate again. The size actually allocated is stored in res_size argument.

Returns zero if the buffer with the given size is allocated successfuly, other a negative value at error.

### LINUX

Kernel Hackers Manual January 2008
snd_dma_free_pages
9
2.6.24-rc6-git8

### snd_dma_free_pages

release the allocated buffer

#### Synopsis

       void snd_dma_free_pages
       struct snd_dma_buffer * dmab

#### Arguments

`dmab`

  the buffer allocation record to release

#### Description

Releases the allocated buffer via `snd_dma_alloc_pages`.

### LINUX

Kernel Hackers Manual January 2008
snd_dma_get_reserved_buf
9
2.6.24-rc6-git8

### snd_dma_get_reserved_buf

get the reserved buffer for the given device

#### Synopsis

       size_t snd_dma_get_reserved_buf
       struct snd_dma_buffer * dmab
       unsigned int id

#### Arguments

`dmab`

  the buffer allocation record to store

`id`

  the buffer id

#### Description

Looks for the reserved-buffer list and re-uses if the same buffer is found in the list. When the buffer is found, it's removed from the free list.

Returns the size of buffer if the buffer is found, or zero if not found.

### LINUX

Kernel Hackers Manual January 2008
snd_dma_reserve_buf
9
2.6.24-rc6-git8

### snd_dma_reserve_buf

reserve the buffer

#### Synopsis

       int snd_dma_reserve_buf
       struct snd_dma_buffer * dmab
       unsigned int id

#### Arguments

`dmab`

  the buffer to reserve

`id`

  the buffer id

#### Description

Reserves the given buffer as a reserved buffer.

Returns zero if successful, or a negative code at error.

## 16x50 UART Driver

### LINUX

Kernel Hackers Manual January 2008
uart_handle_dcd_change
9
2.6.24-rc6-git8

### uart_handle_dcd_change

handle a change of carrier detect state

#### Synopsis

       void uart_handle_dcd_change
       struct uart_port * port
       unsigned int status

#### Arguments

`port`

  uart_port structure for the open port

`status`

  new carrier detect status, nonzero if active

### LINUX

Kernel Hackers Manual January 2008
uart_handle_cts_change
9
2.6.24-rc6-git8

### uart_handle_cts_change

handle a change of clear-to-send state

#### Synopsis

       void uart_handle_cts_change
       struct uart_port * port
       unsigned int status

#### Arguments

`port`

  uart_port structure for the open port

`status`

  new clear to send status, nonzero if active

### LINUX

Kernel Hackers Manual January 2008
uart_update_timeout
9
2.6.24-rc6-git8

### uart_update_timeout

update per-port FIFO timeout.

#### Synopsis

       void uart_update_timeout
       struct uart_port * port
       unsigned int cflag
       unsigned int baud

#### Arguments

`port`

  uart_port structure describing the port

`cflag`

  termios cflag value

`baud`

  speed of the port

#### Description

Set the port FIFO timeout value. The `cflag` value should reflect the actual hardware settings.

### LINUX

Kernel Hackers Manual January 2008
uart_get_baud_rate
9
2.6.24-rc6-git8

### uart_get_baud_rate

return baud rate for a particular port

#### Synopsis

       unsigned int uart_get_baud_rate
       struct uart_port * port
       struct ktermios * termios
       struct ktermios * old
       unsigned int min
       unsigned int max

#### Arguments

`port`

  uart_port structure describing the port in question.

`termios`

  desired termios settings.

`old`

  old termios (or NULL)

`min`

  minimum acceptable baud rate

`max`

  maximum acceptable baud rate

#### Description

Decode the termios structure into a numeric baud rate, taking account of the magic 38400 baud rate (with spd_* flags), and mapping the `B0` rate to 9600 baud.

If the new baud rate is invalid, try the old termios setting. If it's still invalid, we try 9600 baud.

Update the `termios` structure to reflect the baud rate we're actually going to be using.

### LINUX

Kernel Hackers Manual January 2008
uart_get_divisor
9
2.6.24-rc6-git8

### uart_get_divisor

return uart clock divisor

#### Synopsis

       unsigned int uart_get_divisor
       struct uart_port * port
       unsigned int baud

#### Arguments

`port`

  uart_port structure describing the port.

`baud`

  desired baud rate

#### Description

Calculate the uart clock divisor for the port.

### LINUX

Kernel Hackers Manual January 2008
uart_register_driver
9
2.6.24-rc6-git8

### uart_register_driver

register a driver with the uart core layer

#### Synopsis

       int uart_register_driver
       struct uart_driver * drv

#### Arguments

`drv`

  low level driver structure

#### Description

Register a uart driver with the core driver. We in turn register with the tty layer, and initialise the core driver per-port state.

We have a proc file in /proc/tty/driver which is named after the normal driver.

drv->port should be NULL, and the per-port structures should be registered using uart_add_one_port after this call has succeeded.

### LINUX

Kernel Hackers Manual January 2008
uart_unregister_driver
9
2.6.24-rc6-git8

### uart_unregister_driver

remove a driver from the uart core layer

#### Synopsis

       void uart_unregister_driver
       struct uart_driver * drv

#### Arguments

`drv`

  low level driver structure

#### Description

Remove all references to a driver from the core driver. The low level driver must have removed all its ports via the `uart_remove_one_port` if it registered them with `uart_add_one_port`. (ie, drv->port == NULL)

### LINUX

Kernel Hackers Manual January 2008
uart_add_one_port
9
2.6.24-rc6-git8

### uart_add_one_port

attach a driver-defined port structure

#### Synopsis

       int uart_add_one_port
       struct uart_driver * drv
       struct uart_port * port

#### Arguments

`drv`

  pointer to the uart low level driver structure for this port

`port`

  uart port structure to use for this port.

#### Description

This allows the driver to register its own uart_port structure with the core driver. The main purpose is to allow the low level uart drivers to expand uart_port, rather than having yet more levels of structures.

### LINUX

Kernel Hackers Manual January 2008
uart_remove_one_port
9
2.6.24-rc6-git8

### uart_remove_one_port

detach a driver defined port structure

#### Synopsis

       int uart_remove_one_port
       struct uart_driver * drv
       struct uart_port * port

#### Arguments

`drv`

  pointer to the uart low level driver structure for this port

`port`

  uart port structure for this port

#### Description

This unhooks (and hangs up) the specified port structure from the core driver. No further calls will be made to the low-level code for this port.

### LINUX

Kernel Hackers Manual January 2008
serial8250_suspend_port
9
2.6.24-rc6-git8

### serial8250_suspend_port

suspend one serial port

#### Synopsis

       void serial8250_suspend_port
       int line

#### Arguments

`line`

  serial line number

#### Description

Suspend one serial port.

### LINUX

Kernel Hackers Manual January 2008
serial8250_resume_port
9
2.6.24-rc6-git8

### serial8250_resume_port

resume one serial port

#### Synopsis

       void serial8250_resume_port
       int line

#### Arguments

`line`

  serial line number

#### Description

Resume one serial port.

### LINUX

Kernel Hackers Manual January 2008
serial8250_register_port
9
2.6.24-rc6-git8

### serial8250_register_port

register a serial port

#### Synopsis

       int serial8250_register_port
       struct uart_port * port

#### Arguments

`port`

  serial port template

#### Description

Configure the serial port specified by the request. If the port exists and is in use, it is hung up and unregistered first.

The port is then probed and if necessary the IRQ is autodetected If this fails an error is returned.

On success the port is ready to use and the line number is returned.

### LINUX

Kernel Hackers Manual January 2008
serial8250_unregister_port
9
2.6.24-rc6-git8

### serial8250_unregister_port

remove a 16x50 serial port at runtime

#### Synopsis

       void serial8250_unregister_port
       int line

#### Arguments

`line`

  serial line number

#### Description

Remove one serial port. This may not be called from interrupt context. We hand the port back to the our control.

## Z85230 Support Library

### LINUX

Kernel Hackers Manual January 2008
z8530_interrupt
9
2.6.24-rc6-git8

### z8530_interrupt

Handle an interrupt from a Z8530

#### Synopsis

       irqreturn_t z8530_interrupt
       int irq
       void * dev_id

#### Arguments

`irq`

  Interrupt number

`dev_id`

  The Z8530 device that is interrupting.

#### Description

A Z85[2]30 device has stuck its hand in the air for attention. We scan both the channels on the chip for events and then call the channel specific call backs for each channel that has events. We have to use callback functions because the two channels can be in different modes.

Locking is done for the handlers. Note that locking is done at the chip level (the 5uS delay issue is per chip not per channel). c->lock for both channels points to dev->lock

### LINUX

Kernel Hackers Manual January 2008
z8530_sync_open
9
2.6.24-rc6-git8

### z8530_sync_open

Open a Z8530 channel for PIO

#### Synopsis

       int z8530_sync_open
       struct net_device * dev
       struct z8530_channel * c

#### Arguments

`dev`

  The network interface we are using

`c`

  The Z8530 channel to open in synchronous PIO mode

#### Description

Switch a Z8530 into synchronous mode without DMA assist. We raise the RTS/DTR and commence network operation.

### LINUX

Kernel Hackers Manual January 2008
z8530_sync_close
9
2.6.24-rc6-git8

### z8530_sync_close

Close a PIO Z8530 channel

#### Synopsis

       int z8530_sync_close
       struct net_device * dev
       struct z8530_channel * c

#### Arguments

`dev`

  Network device to close

`c`

  Z8530 channel to disassociate and move to idle

#### Description

Close down a Z8530 interface and switch its interrupt handlers to discard future events.

### LINUX

Kernel Hackers Manual January 2008
z8530_sync_dma_open
9
2.6.24-rc6-git8

### z8530_sync_dma_open

Open a Z8530 for DMA I/O

#### Synopsis

       int z8530_sync_dma_open
       struct net_device * dev
       struct z8530_channel * c

#### Arguments

`dev`

  The network device to attach

`c`

  The Z8530 channel to configure in sync DMA mode.

#### Description

Set up a Z85x30 device for synchronous DMA in both directions. Two ISA DMA channels must be available for this to work. We assume ISA DMA driven I/O and PC limits on access.

### LINUX

Kernel Hackers Manual January 2008
z8530_sync_dma_close
9
2.6.24-rc6-git8

### z8530_sync_dma_close

Close down DMA I/O

#### Synopsis

       int z8530_sync_dma_close
       struct net_device * dev
       struct z8530_channel * c

#### Arguments

`dev`

  Network device to detach

`c`

  Z8530 channel to move into discard mode

#### Description

Shut down a DMA mode synchronous interface. Halt the DMA, and free the buffers.

### LINUX

Kernel Hackers Manual January 2008
z8530_sync_txdma_open
9
2.6.24-rc6-git8

### z8530_sync_txdma_open

Open a Z8530 for TX driven DMA

#### Synopsis

       int z8530_sync_txdma_open
       struct net_device * dev
       struct z8530_channel * c

#### Arguments

`dev`

  The network device to attach

`c`

  The Z8530 channel to configure in sync DMA mode.

#### Description

Set up a Z85x30 device for synchronous DMA tranmission. One ISA DMA channel must be available for this to work. The receive side is run in PIO mode, but then it has the bigger FIFO.

### LINUX

Kernel Hackers Manual January 2008
z8530_sync_txdma_close
9
2.6.24-rc6-git8

### z8530_sync_txdma_close

Close down a TX driven DMA channel

#### Synopsis

       int z8530_sync_txdma_close
       struct net_device * dev
       struct z8530_channel * c

#### Arguments

`dev`

  Network device to detach

`c`

  Z8530 channel to move into discard mode

#### Description

Shut down a DMA/PIO split mode synchronous interface. Halt the DMA, and free the buffers.

### LINUX

Kernel Hackers Manual January 2008
z8530_describe
9
2.6.24-rc6-git8

### z8530_describe

Uniformly describe a Z8530 port

#### Synopsis

       void z8530_describe
       struct z8530_dev * dev
       char * mapping
       unsigned long io

#### Arguments

`dev`

  Z8530 device to describe

`mapping`

  string holding mapping type (eg I/O or Mem)

`io`

  the port value in question

#### Description

Describe a Z8530 in a standard format. We must pass the I/O as the port offset isnt predictable. The main reason for this function is to try and get a common format of report.

### LINUX

Kernel Hackers Manual January 2008
z8530_init
9
2.6.24-rc6-git8

### z8530_init

Initialise a Z8530 device

#### Synopsis

       int z8530_init
       struct z8530_dev * dev

#### Arguments

`dev`

  Z8530 device to initialise.

#### Description

Configure up a Z8530/Z85C30 or Z85230 chip. We check the device is present, identify the type and then program it to hopefully keep quite and behave. This matters a lot, a Z8530 in the wrong state will sometimes get into stupid modes generating 10Khz interrupt streams and the like.

We set the interrupt handler up to discard any events, in case we get them during reset or setp.

Return 0 for success, or a negative value indicating the problem in errno form.

### LINUX

Kernel Hackers Manual January 2008
z8530_shutdown
9
2.6.24-rc6-git8

### z8530_shutdown

Shutdown a Z8530 device

#### Synopsis

       int z8530_shutdown
       struct z8530_dev * dev

#### Arguments

`dev`

  The Z8530 chip to shutdown

#### Description

We set the interrupt handlers to silence any interrupts. We then reset the chip and wait 100uS to be sure the reset completed. Just in case the caller then tries to do stuff.

This is called without the lock held

### LINUX

Kernel Hackers Manual January 2008
z8530_channel_load
9
2.6.24-rc6-git8

### z8530_channel_load

Load channel data

#### Synopsis

       int z8530_channel_load
       struct z8530_channel * c
       u8 * rtable

#### Arguments

`c`

  Z8530 channel to configure

`rtable`

  table of register, value pairs

#### FIXME

ioctl to allow user uploaded tables

Load a Z8530 channel up from the system data. We use +16 to indicate the prime registers. The value 255 terminates the table.

### LINUX

Kernel Hackers Manual January 2008
z8530_null_rx
9
2.6.24-rc6-git8

### z8530_null_rx

Discard a packet

#### Synopsis

       void z8530_null_rx
       struct z8530_channel * c
       struct sk_buff * skb

#### Arguments

`c`

  The channel the packet arrived on

`skb`

  The buffer

#### Description

We point the receive handler at this function when idle. Instead of syncppp processing the frames we get to throw them away.

### LINUX

Kernel Hackers Manual January 2008
z8530_queue_xmit
9
2.6.24-rc6-git8

### z8530_queue_xmit

Queue a packet

#### Synopsis

       int z8530_queue_xmit
       struct z8530_channel * c
       struct sk_buff * skb

#### Arguments

`c`

  The channel to use

`skb`

  The packet to kick down the channel

#### Description

Queue a packet for transmission. Because we have rather hard to hit interrupt latencies for the Z85230 per packet even in DMA mode we do the flip to DMA buffer if needed here not in the IRQ.

Called from the network code. The lock is not held at this point.

### LINUX

Kernel Hackers Manual January 2008
z8530_get_stats
9
2.6.24-rc6-git8

### z8530_get_stats

Get network statistics

#### Synopsis

       struct net_device_stats * z8530_get_stats
       struct z8530_channel * c

#### Arguments

`c`

  The channel to use

#### Description

Get the statistics block. We keep the statistics in software as the chip doesn't do it for us.

Locking is ignored here - we could lock for a copy but its not likely to be that big an issue

## Frame Buffer Library

The frame buffer drivers depend heavily on four data structures. These structures are declared in include/linux/fb.h. They are fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. The last three can be made available to and from userland.

fb_info defines the current state of a particular video card. Inside fb_info, there exists a fb_ops structure which is a collection of needed functions to make fbdev and fbcon work. fb_info is only visible to the kernel.

fb_var_screeninfo is used to describe the features of a video card that are user defined. With fb_var_screeninfo, things such as depth and the resolution may be defined.

The next structure is fb_fix_screeninfo. This defines the properties of a card that are created when a mode is set and can't be changed otherwise. A good example of this is the start of the frame buffer memory. This "locks" the address of the frame buffer memory, so that it cannot be changed or moved.

The last structure is fb_monospecs. In the old API, there was little importance for fb_monospecs. This allowed for forbidden things such as setting a mode of 800x600 on a fix frequency monitor. With the new API, fb_monospecs prevents such things, and if used correctly, can prevent a monitor from being cooked. fb_monospecs will not be useful until kernels 2.5.x.

### Frame Buffer Memory

#### LINUX

Kernel Hackers Manual January 2008
register_framebuffer
9
2.6.24-rc6-git8

#### register_framebuffer

registers a frame buffer device

##### Synopsis

       int register_framebuffer
       struct fb_info * fb_info

##### Arguments

`fb_info`

  frame buffer info structure

##### Description

Registers a frame buffer device `fb_info`.

Returns negative errno on error, or zero for success.

#### LINUX

Kernel Hackers Manual January 2008
unregister_framebuffer
9
2.6.24-rc6-git8

#### unregister_framebuffer

releases a frame buffer device

##### Synopsis

       int unregister_framebuffer
       struct fb_info * fb_info

##### Arguments

`fb_info`

  frame buffer info structure

##### Description

Unregisters a frame buffer device `fb_info`.

Returns negative errno on error, or zero for success.

This function will also notify the framebuffer console to release the driver.

This is meant to be called within a driver's `module_exit` function. If this is called outside `module_exit`, ensure that the driver implements `fb_open` and `fb_release` to check that no processes are using the device.

#### LINUX

Kernel Hackers Manual January 2008
fb_set_suspend
9
2.6.24-rc6-git8

#### fb_set_suspend

low level driver signals suspend

##### Synopsis

       void fb_set_suspend
       struct fb_info * info
       int state

##### Arguments

`info`

  framebuffer affected

`state`

  0 = resuming, !=0 = suspending

##### Description

This is meant to be used by low level drivers to signal suspend/resume to the core & clients. It must be called with the console semaphore held

#### LINUX

Kernel Hackers Manual January 2008
fb_get_options
9
2.6.24-rc6-git8

#### fb_get_options

get kernel boot parameters

##### Synopsis

       int fb_get_options
       char * name
       char ** option

##### Arguments

`name`

  framebuffer name as it would appear in the boot parameter line (video=<name>:<options>)

`option`

  the option will be stored here

##### NOTE

Needed to maintain backwards compatibility

### Frame Buffer Colormap

#### LINUX

Kernel Hackers Manual January 2008
fb_alloc_cmap
9
2.6.24-rc6-git8

#### fb_alloc_cmap

allocate a colormap

##### Synopsis

       int fb_alloc_cmap
       struct fb_cmap * cmap
       int len
       int transp

##### Arguments

`cmap`

  frame buffer colormap structure

`len`

  length of `cmap`

`transp`

  boolean, 1 if there is transparency, 0 otherwise

##### Description

Allocates memory for a colormap `cmap`. `len` is the number of entries in the palette.

Returns negative errno on error, or zero on success.

#### LINUX

Kernel Hackers Manual January 2008
fb_dealloc_cmap
9
2.6.24-rc6-git8

#### fb_dealloc_cmap

deallocate a colormap

##### Synopsis

       void fb_dealloc_cmap
       struct fb_cmap * cmap

##### Arguments

`cmap`

  frame buffer colormap structure

##### Description

Deallocates a colormap that was previously allocated with `fb_alloc_cmap`.

#### LINUX

Kernel Hackers Manual January 2008
fb_copy_cmap
9
2.6.24-rc6-git8

#### fb_copy_cmap

copy a colormap

##### Synopsis

       int fb_copy_cmap
       const struct fb_cmap * from
       struct fb_cmap * to

##### Arguments

`from`

  frame buffer colormap structure

`to`

  frame buffer colormap structure

##### Description

Copy contents of colormap from `from` to `to`.

#### LINUX

Kernel Hackers Manual January 2008
fb_set_cmap
9
2.6.24-rc6-git8

#### fb_set_cmap

set the colormap

##### Synopsis

       int fb_set_cmap
       struct fb_cmap * cmap
       struct fb_info * info

##### Arguments

`cmap`

  frame buffer colormap structure

`info`

  frame buffer info structure

##### Description

Sets the colormap `cmap` for a screen of device `info`.

Returns negative errno on error, or zero on success.

#### LINUX

Kernel Hackers Manual January 2008
fb_default_cmap
9
2.6.24-rc6-git8

#### fb_default_cmap

get default colormap

##### Synopsis

       const struct fb_cmap * fb_default_cmap
       int len

##### Arguments

`len`

  size of palette for a depth

##### Description

Gets the default colormap for a specific screen depth. `len` is the size of the palette for a particular screen depth.

Returns pointer to a frame buffer colormap structure.

#### LINUX

Kernel Hackers Manual January 2008
fb_invert_cmaps
9
2.6.24-rc6-git8

#### fb_invert_cmaps

invert all defaults colormaps

##### Synopsis

       void fb_invert_cmaps
        void

##### Arguments

`void`

  no arguments

##### Description

Invert all default colormaps.

### Frame Buffer Video Mode Database

#### LINUX

Kernel Hackers Manual January 2008
fb_try_mode
9
2.6.24-rc6-git8

#### fb_try_mode

test a video mode

##### Synopsis

       int fb_try_mode
       struct fb_var_screeninfo * var
       struct fb_info * info
       const struct fb_videomode * mode
       unsigned int bpp

##### Arguments

`var`

  frame buffer user defined part of display

`info`

  frame buffer info structure

`mode`

  frame buffer video mode structure

`bpp`

  color depth in bits per pixel

##### Description

Tries a video mode to test it's validity for device `info`.

Returns 1 on success.

#### LINUX

Kernel Hackers Manual January 2008
fb_delete_videomode
9
2.6.24-rc6-git8

#### fb_delete_videomode

##### Synopsis

       void fb_delete_videomode
       const struct fb_videomode * mode
       struct list_head * head

##### Arguments

`mode`

  videomode to remove

`head`

  struct list_head of modelist

##### NOTES

Will remove all matching mode entries

#### LINUX

Kernel Hackers Manual January 2008
fb_find_mode
9
2.6.24-rc6-git8

#### fb_find_mode

finds a valid video mode

##### Synopsis

       int fb_find_mode
       struct fb_var_screeninfo * var
       struct fb_info * info
       const char * mode_option
       const struct fb_videomode * db
       unsigned int dbsize
       const struct fb_videomode * default_mode
       unsigned int default_bpp

##### Arguments

`var`

  frame buffer user defined part of display

`info`

  frame buffer info structure

`mode_option`

  string video mode to find

`db`

  video mode database

`dbsize`

  size of `db`

`default_mode`

  default video mode to fall back to

`default_bpp`

  default color depth in bits per pixel

##### Description

Finds a suitable video mode, starting with the specified mode in `mode_option` with fallback to `default_mode`. If `default_mode` fails, all modes in the video mode database will be tried.

Valid mode specifiers for `mode_option`:

<xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m] or <name>[-<bpp>][@<refresh>]

with <xres>, <yres>, <bpp> and <refresh> decimal numbers and <name> a string.

If 'M' is present after yres (and before refresh/bpp if present), the function will compute the timings using VESA(tm) Coordinated Video Timings (CVT). If 'R' is present after 'M', will compute with reduced blanking (for flatpanels). If 'i' is present, compute interlaced mode. If 'm' is present, add margins equal to 1.8% of xres rounded down to 8 pixels, and 1.8% of yres. The char 'i' and 'm' must be after 'M' and 'R'. Example:

1024x768MR-8`60m` - Reduced blank with margins at 60Hz.

##### NOTE

The passed struct `var` is _not_ cleared! This allows you to supply values for e.g. the grayscale and accel_flags fields.

Returns zero for failure, 1 if using specified `mode_option`, 2 if using specified `mode_option` with an ignored refresh rate, 3 if default mode is used, 4 if fall back to any valid mode.

#### LINUX

Kernel Hackers Manual January 2008
fb_var_to_videomode
9
2.6.24-rc6-git8

#### fb_var_to_videomode

convert fb_var_screeninfo to fb_videomode

##### Synopsis

       void fb_var_to_videomode
       struct fb_videomode * mode
       const struct fb_var_screeninfo * var

##### Arguments

`mode`

  pointer to struct fb_videomode

`var`

  pointer to struct fb_var_screeninfo

#### LINUX

Kernel Hackers Manual January 2008
fb_videomode_to_var
9
2.6.24-rc6-git8

#### fb_videomode_to_var

convert fb_videomode to fb_var_screeninfo

##### Synopsis

       void fb_videomode_to_var
       struct fb_var_screeninfo * var
       const struct fb_videomode * mode

##### Arguments

`var`

  pointer to struct fb_var_screeninfo

`mode`

  pointer to struct fb_videomode

#### LINUX

Kernel Hackers Manual January 2008
fb_mode_is_equal
9
2.6.24-rc6-git8

#### fb_mode_is_equal

compare 2 videomodes

##### Synopsis

       int fb_mode_is_equal
       const struct fb_videomode * mode1
       const struct fb_videomode * mode2

##### Arguments

`mode1`

  first videomode

`mode2`

  second videomode

##### RETURNS

1 if equal, 0 if not

#### LINUX

Kernel Hackers Manual January 2008
fb_find_best_mode
9
2.6.24-rc6-git8

#### fb_find_best_mode

find best matching videomode

##### Synopsis

       const struct fb_videomode * fb_find_best_mode
       const struct fb_var_screeninfo * var
       struct list_head * head

##### Arguments

`var`

  pointer to struct fb_var_screeninfo

`head`

  pointer to struct list_head of modelist

##### RETURNS

struct fb_videomode, NULL if none found

##### IMPORTANT

This function assumes that all modelist entries in info->modelist are valid.

##### NOTES

Finds best matching videomode which has an equal or greater dimension than var->xres and var->yres. If more than 1 videomode is found, will return the videomode with the highest refresh rate

#### LINUX

Kernel Hackers Manual January 2008
fb_find_nearest_mode
9
2.6.24-rc6-git8

#### fb_find_nearest_mode

find closest videomode

##### Synopsis

       const struct fb_videomode * fb_find_nearest_mode
       const struct fb_videomode * mode
       struct list_head * head

##### Arguments

`mode`

  pointer to struct fb_videomode

`head`

  pointer to modelist

##### Description

Finds best matching videomode, smaller or greater in dimension. If more than 1 videomode is found, will return the videomode with the closest refresh rate.

##### Description

Finds best matching videomode, smaller or greater in dimension. If more than 1 videomode is found, will return the videomode with the closest refresh rate.

#### LINUX

Kernel Hackers Manual January 2008
fb_match_mode
9
2.6.24-rc6-git8

#### fb_match_mode

find a videomode which exactly matches the timings in var

##### Synopsis

       const struct fb_videomode * fb_match_mode
       const struct fb_var_screeninfo * var
       struct list_head * head

##### Arguments

`var`

  pointer to struct fb_var_screeninfo

`head`

  pointer to struct list_head of modelist

##### RETURNS

struct fb_videomode, NULL if none found

#### LINUX

Kernel Hackers Manual January 2008
fb_add_videomode
9
2.6.24-rc6-git8

#### fb_add_videomode

##### Synopsis

       int fb_add_videomode
       const struct fb_videomode * mode
       struct list_head * head

##### Arguments

`mode`

  videomode to add

`head`

  struct list_head of modelist

##### NOTES

Will only add unmatched mode entries

#### LINUX

Kernel Hackers Manual January 2008
fb_destroy_modelist
9
2.6.24-rc6-git8

#### fb_destroy_modelist

##### Synopsis

       void fb_destroy_modelist
       struct list_head * head

##### Arguments

`head`

  struct list_head of modelist

#### LINUX

Kernel Hackers Manual January 2008
fb_videomode_to_modelist
9
2.6.24-rc6-git8

#### fb_videomode_to_modelist

##### Synopsis

       void fb_videomode_to_modelist
       const struct fb_videomode * modedb
       int num
       struct list_head * head

##### Arguments

`modedb`

  array of struct fb_videomode

`num`

  number of entries in array

`head`

  struct list_head of modelist

### Frame Buffer Macintosh Video Mode Database

#### LINUX

Kernel Hackers Manual January 2008
mac_vmode_to_var
9
2.6.24-rc6-git8

#### mac_vmode_to_var

converts vmode/cmode pair to var structure

##### Synopsis

       int mac_vmode_to_var
       int vmode
       int cmode
       struct fb_var_screeninfo * var

##### Arguments

`vmode`

  MacOS video mode

`cmode`

  MacOS color mode

`var`

  frame buffer video mode structure

##### Description

Converts a MacOS vmode/cmode pair to a frame buffer video mode structure.

Returns negative errno on error, or zero for success.

#### LINUX

Kernel Hackers Manual January 2008
mac_map_monitor_sense
9
2.6.24-rc6-git8

#### mac_map_monitor_sense

Convert monitor sense to vmode

##### Synopsis

       int mac_map_monitor_sense
       int sense

##### Arguments

`sense`

  Macintosh monitor sense number

##### Description

Converts a Macintosh monitor sense number to a MacOS vmode number.

Returns MacOS vmode video mode number.

#### LINUX

Kernel Hackers Manual January 2008
mac_find_mode
9
2.6.24-rc6-git8

#### mac_find_mode

find a video mode

##### Synopsis

       int mac_find_mode
       struct fb_var_screeninfo * var
       struct fb_info * info
       const char * mode_option
       unsigned int default_bpp

##### Arguments

`var`

  frame buffer user defined part of display

`info`

  frame buffer info structure

`mode_option`

  video mode name (see mac_modedb[])

`default_bpp`

  default color depth in bits per pixel

##### Description

Finds a suitable video mode. Tries to set mode specified by `mode_option`. If the name of the wanted mode begins with 'mac', the Mac video mode database will be used, otherwise it will fall back to the standard video mode database.

##### Note

Function marked as __init and can only be used during system boot.

Returns error code from fb_find_mode (see fb_find_mode function).

### Frame Buffer Fonts

Refer to the file drivers/video/console/fonts.c for more information.

## Input Subsystem

### LINUX

Kernel Hackers Manual January 2008
struct ff_replay
9
2.6.24-rc6-git8

### struct ff_replay

defines scheduling of the force-feedback effect

#### Synopsis

    struct ff_replay {
      __u16 length;
      __u16 delay;
    };

#### Members

length

  duration of the effect

delay

  delay before effect should start playing

### LINUX

Kernel Hackers Manual January 2008
struct ff_trigger
9
2.6.24-rc6-git8

### struct ff_trigger

defines what triggers the force-feedback effect

#### Synopsis

    struct ff_trigger {
      __u16 button;
      __u16 interval;
    };

#### Members

button

  number of the button triggering the effect

interval

  controls how soon the effect can be re-triggered

### LINUX

Kernel Hackers Manual January 2008
struct ff_envelope
9
2.6.24-rc6-git8

### struct ff_envelope

generic force-feedback effect envelope

#### Synopsis

    struct ff_envelope {
      __u16 attack_length;
      __u16 attack_level;
      __u16 fade_length;
      __u16 fade_level;
    };

#### Members

attack_length

  duration of the attack (ms)

attack_level

  level at the beginning of the attack

fade_length

  duration of fade (ms)

fade_level

  level at the end of fade

#### Description

The `attack_level` and `fade_level` are absolute values; when applying envelope force-feedback core will convert to positive/negative value based on polarity of the default level of the effect. Valid range for the attack and fade levels is 0x0000 - 0x7fff

### LINUX

Kernel Hackers Manual January 2008
struct ff_constant_effect
9
2.6.24-rc6-git8

### struct ff_constant_effect

defines parameters of a constant force-feedback effect

#### Synopsis

    struct ff_constant_effect {
      __s16 level;
      struct ff_envelope envelope;
    };

#### Members

level

  strength of the effect; may be negative

envelope

  envelope data

### LINUX

Kernel Hackers Manual January 2008
struct ff_ramp_effect
9
2.6.24-rc6-git8

### struct ff_ramp_effect

defines parameters of a ramp force-feedback effect

#### Synopsis

    struct ff_ramp_effect {
      __s16 start_level;
      __s16 end_level;
      struct ff_envelope envelope;
    };

#### Members

start_level

  beginning strength of the effect; may be negative

end_level

  final strength of the effect; may be negative

envelope

  envelope data

### LINUX

Kernel Hackers Manual January 2008
struct ff_condition_effect
9
2.6.24-rc6-git8

### struct ff_condition_effect

defines a spring or friction force-feedback effect

#### Synopsis

    struct ff_condition_effect {
      __u16 right_saturation;
      __u16 left_saturation;
      __s16 right_coeff;
      __s16 left_coeff;
      __u16 deadband;
      __s16 center;
    };

#### Members

right_saturation

  maximum level when joystick moved all way to the right

left_saturation

  same for the left side

right_coeff

  controls how fast the force grows when the joystick moves to the right

left_coeff

  same for the left side

deadband

  size of the dead zone, where no force is produced

center

  position of the dead zone

### LINUX

Kernel Hackers Manual January 2008
struct ff_periodic_effect
9
2.6.24-rc6-git8

### struct ff_periodic_effect

defines parameters of a periodic force-feedback effect

#### Synopsis

    struct ff_periodic_effect {
      __u16 waveform;
      __u16 period;
      __s16 magnitude;
      __s16 offset;
      __u16 phase;
      struct ff_envelope envelope;
      __u32 custom_len;
      __s16 * custom_data;
    };

#### Members

waveform

  kind of the effect (wave)

period

  period of the wave (ms)

magnitude

  peak value

offset

  mean value of the wave (roughly)

phase

  'horizontal' shift

envelope

  envelope data

custom_len

  number of samples (FF_CUSTOM only)

custom_data

  buffer of samples (FF_CUSTOM only)

#### Description

Known waveforms - FF_SQUARE, FF_TRIANGLE, FF_SINE, FF_SAW_UP, FF_SAW_DOWN, FF_CUSTOM. The exact syntax FF_CUSTOM is undefined for the time being as no driver supports it yet.

#### Note

the data pointed by custom_data is copied by the driver. You can therefore dispose of the memory after the upload/update.

### LINUX

Kernel Hackers Manual January 2008
struct ff_rumble_effect
9
2.6.24-rc6-git8

### struct ff_rumble_effect

defines parameters of a periodic force-feedback effect

#### Synopsis

    struct ff_rumble_effect {
      __u16 strong_magnitude;
      __u16 weak_magnitude;
    };

#### Members

strong_magnitude

  magnitude of the heavy motor

weak_magnitude

  magnitude of the light one

#### Description

Some rumble pads have two motors of different weight. Strong_magnitude represents the magnitude of the vibration generated by the heavy one.

### LINUX

Kernel Hackers Manual January 2008
struct ff_effect
9
2.6.24-rc6-git8

### struct ff_effect

defines force feedback effect

#### Synopsis

    struct ff_effect {
      __u16 type;
      __s16 id;
      __u16 direction;
      struct ff_trigger trigger;
      struct ff_replay replay;
      union u;
    };

#### Members

type

  type of the effect (FF_CONSTANT, FF_PERIODIC, FF_RAMP, FF_SPRING, FF_FRICTION, FF_DAMPER, FF_RUMBLE, FF_INERTIA, or FF_CUSTOM)

id

  an unique id assigned to an effect

direction

  direction of the effect

trigger

  trigger conditions (struct ff_trigger)

replay

  scheduling of the effect (struct ff_replay)

u

  effect-specific structure (one of ff_constant_effect, ff_ramp_effect, ff_periodic_effect, ff_condition_effect, ff_rumble_effect) further defining effect parameters

#### Description

This structure is sent through ioctl from the application to the driver. To create a new effect application should set its `id` to -1; the kernel will return assigned `id` which can later be used to update or delete this effect.

#### Direction of the effect is encoded as follows

0 deg -> 0x0000 (down) 90 deg -> 0x4000 (left) 180 deg -> 0x8000 (up) 270 deg -> 0xC000 (right)

### LINUX

Kernel Hackers Manual January 2008
struct input_dev
9
2.6.24-rc6-git8

### struct input_dev

represents an input device

#### Synopsis

    struct input_dev {
      const char * name;
      const char * phys;
      const char * uniq;
      struct input_id id;
      unsigned long evbit[BITS_TO_LONGS(EV_CNT)];
      unsigned long keybit[BITS_TO_LONGS(KEY_CNT)];
      unsigned long relbit[BITS_TO_LONGS(REL_CNT)];
      unsigned long absbit[BITS_TO_LONGS(ABS_CNT)];
      unsigned long mscbit[BITS_TO_LONGS(MSC_CNT)];
      unsigned long ledbit[BITS_TO_LONGS(LED_CNT)];
      unsigned long sndbit[BITS_TO_LONGS(SND_CNT)];
      unsigned long ffbit[BITS_TO_LONGS(FF_CNT)];
      unsigned long swbit[BITS_TO_LONGS(SW_CNT)];
      unsigned int keycodemax;
      unsigned int keycodesize;
      void * keycode;
      int (* setkeycode) (struct input_dev *dev, int scancode, int keycode);
      int (* getkeycode) (struct input_dev *dev, int scancode, int *keycode);
      struct ff_device * ff;
      unsigned int repeat_key;
      struct timer_list timer;
      int sync;
      int abs[ABS_MAX + 1];
      int rep[REP_MAX + 1];
      unsigned long key[BITS_TO_LONGS(KEY_CNT)];
      unsigned long led[BITS_TO_LONGS(LED_CNT)];
      unsigned long snd[BITS_TO_LONGS(SND_CNT)];
      unsigned long sw[BITS_TO_LONGS(SW_CNT)];
      int absmax[ABS_MAX + 1];
      int absmin[ABS_MAX + 1];
      int absfuzz[ABS_MAX + 1];
      int absflat[ABS_MAX + 1];
      int (* open) (struct input_dev *dev);
      void (* close) (struct input_dev *dev);
      int (* flush) (struct input_dev *dev, struct file *file);
      int (* event) (struct input_dev *dev, unsigned int type, unsigned int code, int value);
      struct input_handle * grab;
      spinlock_t event_lock;
      struct mutex mutex;
      unsigned int users;
      int going_away;
      struct device dev;
      union cdev;
      struct list_head h_list;
      struct list_head node;
    };

#### Members

name

  name of the device

phys

  physical path to the device in the system hierarchy

uniq

  unique identification code for the device (if device has it)

id

  id of the device (struct input_id)

evbit[BITS_TO_LONGS(EV_CNT)]

  bitmap of types of events supported by the device (EV_KEY, EV_REL, etc.)

keybit[BITS_TO_LONGS(KEY_CNT)]

  bitmap of keys/buttons this device has

relbit[BITS_TO_LONGS(REL_CNT)]

  bitmap of relative axes for the device

absbit[BITS_TO_LONGS(ABS_CNT)]

  bitmap of absolute axes for the device

mscbit[BITS_TO_LONGS(MSC_CNT)]

  bitmap of miscellaneous events supported by the device

ledbit[BITS_TO_LONGS(LED_CNT)]

  bitmap of leds present on the device

sndbit[BITS_TO_LONGS(SND_CNT)]

  bitmap of sound effects supported by the device

ffbit[BITS_TO_LONGS(FF_CNT)]

  bitmap of force feedback effects supported by the device

swbit[BITS_TO_LONGS(SW_CNT)]

  bitmap of switches present on the device

keycodemax

  size of keycode table

keycodesize

  size of elements in keycode table

keycode

  map of scancodes to keycodes for this device

setkeycode

  optional method to alter current keymap, used to implement sparse keymaps. If not supplied default mechanism will be used

getkeycode

  optional method to retrieve current keymap. If not supplied default mechanism will be used

ff

  force feedback structure associated with the device if device supports force feedback effects

repeat_key

  stores key code of the last key pressed; used to implement software autorepeat

timer

  timer for software autorepeat

sync

  set to 1 when there were no new events since last EV_SYNC

abs[ABS_MAX + 1]

  current values for reports from absolute axes

rep[REP_MAX + 1]

  current values for autorepeat parameters (delay, rate)

key[BITS_TO_LONGS(KEY_CNT)]

  reflects current state of device's keys/buttons

led[BITS_TO_LONGS(LED_CNT)]

  reflects current state of device's LEDs

snd[BITS_TO_LONGS(SND_CNT)]

  reflects current state of sound effects

sw[BITS_TO_LONGS(SW_CNT)]

  reflects current state of device's switches

absmax[ABS_MAX + 1]

  maximum values for events coming from absolute axes

absmin[ABS_MAX + 1]

  minimum values for events coming from absolute axes

absfuzz[ABS_MAX + 1]

  describes noisiness for axes

absflat[ABS_MAX + 1]

  size of the center flat position (used by joydev)

open

  this method is called when the very first user calls `input_open_device`. The driver must prepare the device to start generating events (start polling thread, request an IRQ, submit URB, etc.)

close

  this method is called when the very last user calls `input_close_device`.

flush

  purges the device. Most commonly used to get rid of force feedback effects loaded into the device when disconnecting from it

event

  event handler for events sent _to_ the device, like EV_LED or EV_SND. The device is expected to carry out the requested action (turn on a LED, play sound, etc.) The call is protected by `event_lock` and must not sleep

grab

  input handle that currently has the device grabbed (via EVIOCGRAB ioctl). When a handle grabs a device it becomes sole recipient for all input events coming from the device

event_lock

  this spinlock is is taken when input core receives and processes a new event for the device (in `input_event`). Code that accesses and/or modifies parameters of a device (such as keymap or absmin, absmax, absfuzz, etc.) after device has been registered with input core must take this lock.

mutex

  serializes calls to `open`, `close` and `flush` methods

users

  stores number of users (input handlers) that opened this device. It is used by `input_open_device` and `input_close_device` to make sure that dev->`open` is only called when the first user opens device and dev->`close` is called when the very last user closes the device

going_away

  marks devices that are in a middle of unregistering and causes input_open_device*() fail with -ENODEV.

dev

  driver model's view of this device

cdev

  union for struct device pointer

h_list

  list of input handles associated with the device. When accessing the list dev->mutex must be held

node

  used to place the device onto input_dev_list

### LINUX

Kernel Hackers Manual January 2008
struct input_handler
9
2.6.24-rc6-git8

### struct input_handler

implements one of interfaces for input devices

#### Synopsis

    struct input_handler {
      void * private;
      void (* event) (struct input_handle *handle, unsigned int type, unsigned int code, int value);
      int (* connect) (struct input_handler *handler, struct input_dev *dev, const struct input_device_id *id);
      void (* disconnect) (struct input_handle *handle);
      void (* start) (struct input_handle *handle);
      const struct file_operations * fops;
      int minor;
      const char * name;
      const struct input_device_id * id_table;
      const struct input_device_id * blacklist;
      struct list_head h_list;
      struct list_head node;
    };

#### Members

private

  driver-specific data

event

  event handler. This method is being called by input core with interrupts disabled and dev->event_lock spinlock held and so it may not sleep

connect

  called when attaching a handler to an input device

disconnect

  disconnects a handler from input device

start

  starts handler for given handle. This function is called by input core right after `connect` method and also when a process that grabbed a device releases it

fops

  file operations this driver implements

minor

  beginning of range of 32 minors for devices this driver can provide

name

  name of the handler, to be shown in /proc/bus/input/handlers

id_table

  pointer to a table of input_device_ids this driver can handle

blacklist

  pointer to a table of input_device_ids this driver should ignore even if they match `id_table`

h_list

  list of input handles associated with the handler

node

  for placing the driver onto input_handler_list

#### Description

Input handlers attach to input devices and create input handles. There are likely several handlers attached to any given input device at the same time. All of them will get their copy of input event generated by the device.

Note that input core serializes calls to `connect` and `disconnect` methods.

### LINUX

Kernel Hackers Manual January 2008
struct input_handle
9
2.6.24-rc6-git8

### struct input_handle

links input device with an input handler

#### Synopsis

    struct input_handle {
      void * private;
      int open;
      const char * name;
      struct input_dev * dev;
      struct input_handler * handler;
      struct list_head d_node;
      struct list_head h_node;
    };

#### Members

private

  handler-specific data

open

  counter showing whether the handle is 'open', i.e. should deliver events from its device

name

  name given to the handle by handler that created it

dev

  input device the handle is attached to

handler

  handler that works with the device through this handle

d_node

  used to put the handle on device's list of attached handles

h_node

  used to put the handle on handler's list of handles from which it gets events

### LINUX

Kernel Hackers Manual January 2008
struct ff_device
9
2.6.24-rc6-git8

### struct ff_device

force-feedback part of an input device

#### Synopsis

    struct ff_device {
      int (* upload) (struct input_dev *dev, struct ff_effect *effect,struct ff_effect *old);
      int (* erase) (struct input_dev *dev, int effect_id);
      int (* playback) (struct input_dev *dev, int effect_id, int value);
      void (* set_gain) (struct input_dev *dev, u16 gain);
      void (* set_autocenter) (struct input_dev *dev, u16 magnitude);
      void (* destroy) (struct ff_device *);
      void * private;
      unsigned long ffbit[BITS_TO_LONGS(FF_CNT)];
      struct mutex mutex;
      int max_effects;
      struct ff_effect * effects;
      struct file * effect_owners[];
    };

#### Members

upload

  Called to upload an new effect into device

erase

  Called to erase an effect from device

playback

  Called to request device to start playing specified effect

set_gain

  Called to set specified gain

set_autocenter

  Called to auto-center device

destroy

  called by input core when parent input device is being destroyed

private

  driver-specific data, will be freed automatically

ffbit[BITS_TO_LONGS(FF_CNT)]

  bitmap of force feedback capabilities truly supported by device (not emulated like ones in input_dev->ffbit)

mutex

  mutex for serializing access to the device

max_effects

  maximum number of effects supported by device

effects

  pointer to an array of effects currently loaded into device

effect_owners[]

  array of effect owners; when file handle owning an effect gets closed the effect is automatically erased

#### Description

Every force-feedback device must implement `upload` and `playback` methods; `erase` is optional. `set_gain` and `set_autocenter` need only be implemented if driver sets up FF_GAIN and FF_AUTOCENTER bits.

### LINUX

Kernel Hackers Manual January 2008
input_event
9
2.6.24-rc6-git8

### input_event

report new input event

#### Synopsis

       void input_event
       struct input_dev * dev
       unsigned int type
       unsigned int code
       int value

#### Arguments

`dev`

  device that generated the event

`type`

  type of the event

`code`

  event code

`value`

  value of the event

#### Description

This function should be used by drivers implementing various input devices. See also `input_inject_event`.

### LINUX

Kernel Hackers Manual January 2008
input_inject_event
9
2.6.24-rc6-git8

### input_inject_event

send input event from input handler

#### Synopsis

       void input_inject_event
       struct input_handle * handle
       unsigned int type
       unsigned int code
       int value

#### Arguments

`handle`

  input handle to send event through

`type`

  type of the event

`code`

  event code

`value`

  value of the event

#### Description

Similar to `input_event` but will ignore event if device is grabbed and handle injecting event is not the one that owns the device.

### LINUX

Kernel Hackers Manual January 2008
input_grab_device
9
2.6.24-rc6-git8

### input_grab_device

grabs device for exclusive use

#### Synopsis

       int input_grab_device
       struct input_handle * handle

#### Arguments

`handle`

  input handle that wants to own the device

#### Description

When a device is grabbed by an input handle all events generated by the device are delivered only to this handle. Also events injected by other input handles are ignored while device is grabbed.

### LINUX

Kernel Hackers Manual January 2008
input_release_device
9
2.6.24-rc6-git8

### input_release_device

release previously grabbed device

#### Synopsis

       void input_release_device
       struct input_handle * handle

#### Arguments

`handle`

  input handle that owns the device

#### Description

Releases previously grabbed device so that other input handles can start receiving input events. Upon release all handlers attached to the device have their `start` method called so they have a change to synchronize device state with the rest of the system.

### LINUX

Kernel Hackers Manual January 2008
input_open_device
9
2.6.24-rc6-git8

### input_open_device

open input device

#### Synopsis

       int input_open_device
       struct input_handle * handle

#### Arguments

`handle`

  handle through which device is being accessed

#### Description

This function should be called by input handlers when they want to start receive events from given input device.

### LINUX

Kernel Hackers Manual January 2008
input_close_device
9
2.6.24-rc6-git8

### input_close_device

close input device

#### Synopsis

       void input_close_device
       struct input_handle * handle

#### Arguments

`handle`

  handle through which device is being accessed

#### Description

This function should be called by input handlers when they want to stop receive events from given input device.

### LINUX

Kernel Hackers Manual January 2008
input_allocate_device
9
2.6.24-rc6-git8

### input_allocate_device

allocate memory for new input device

#### Synopsis

       struct input_dev * input_allocate_device
        void

#### Arguments

`void`

  no arguments

#### Description

Returns prepared struct input_dev or NULL.

#### NOTE

Use `input_free_device` to free devices that have not been registered; `input_unregister_device` should be used for already registered devices.

### LINUX

Kernel Hackers Manual January 2008
input_free_device
9
2.6.24-rc6-git8

### input_free_device

free memory occupied by input_dev structure

#### Synopsis

       void input_free_device
       struct input_dev * dev

#### Arguments

`dev`

  input device to free

#### Description

This function should only be used if `input_register_device` was not called yet or if it failed. Once device was registered use `input_unregister_device` and memory will be freed once last reference to the device is dropped.

Device should be allocated by `input_allocate_device`.

#### NOTE

If there are references to the input device then memory will not be freed until last reference is dropped.

### LINUX

Kernel Hackers Manual January 2008
input_set_capability
9
2.6.24-rc6-git8

### input_set_capability

mark device as capable of a certain event

#### Synopsis

       void input_set_capability
       struct input_dev * dev
       unsigned int type
       unsigned int code

#### Arguments

`dev`

  device that is capable of emitting or accepting event

`type`

  type of the event (EV_KEY, EV_REL, etc...)

`code`

  event code

#### Description

In addition to setting up corresponding bit in appropriate capability bitmap the function also adjusts dev->evbit.

### LINUX

Kernel Hackers Manual January 2008
input_register_device
9
2.6.24-rc6-git8

### input_register_device

register device with input core

#### Synopsis

       int input_register_device
       struct input_dev * dev

#### Arguments

`dev`

  device to be registered

#### Description

This function registers device with input core. The device must be allocated with `input_allocate_device` and all it's capabilities set up before registering. If function fails the device must be freed with `input_free_device`. Once device has been successfully registered it can be unregistered with `input_unregister_device`; `input_free_device` should not be called in this case.

### LINUX

Kernel Hackers Manual January 2008
input_unregister_device
9
2.6.24-rc6-git8

### input_unregister_device

unregister previously registered device

#### Synopsis

       void input_unregister_device
       struct input_dev * dev

#### Arguments

`dev`

  device to be unregistered

#### Description

This function unregisters an input device. Once device is unregistered the caller should not try to access it as it may get freed at any moment.

### LINUX

Kernel Hackers Manual January 2008
input_register_handler
9
2.6.24-rc6-git8

### input_register_handler

register a new input handler

#### Synopsis

       int input_register_handler
       struct input_handler * handler

#### Arguments

`handler`

  handler to be registered

#### Description

This function registers a new input handler (interface) for input devices in the system and attaches it to all input devices that are compatible with the handler.

### LINUX

Kernel Hackers Manual January 2008
input_unregister_handler
9
2.6.24-rc6-git8

### input_unregister_handler

unregisters an input handler

#### Synopsis

       void input_unregister_handler
       struct input_handler * handler

#### Arguments

`handler`

  handler to be unregistered

#### Description

This function disconnects a handler from its input devices and removes it from lists of known handlers.

### LINUX

Kernel Hackers Manual January 2008
input_register_handle
9
2.6.24-rc6-git8

### input_register_handle

register a new input handle

#### Synopsis

       int input_register_handle
       struct input_handle * handle

#### Arguments

`handle`

  handle to register

#### Description

This function puts a new input handle onto device's and handler's lists so that events can flow through it once it is opened using `input_open_device`.

This function is supposed to be called from handler's `connect` method.

### LINUX

Kernel Hackers Manual January 2008
input_unregister_handle
9
2.6.24-rc6-git8

### input_unregister_handle

unregister an input handle

#### Synopsis

       void input_unregister_handle
       struct input_handle * handle

#### Arguments

`handle`

  handle to unregister

#### Description

This function removes input handle from device's and handler's lists.

This function is supposed to be called from handler's `disconnect` method.

### LINUX

Kernel Hackers Manual January 2008
input_ff_upload
9
2.6.24-rc6-git8

### input_ff_upload

upload effect into force-feedback device

#### Synopsis

       int input_ff_upload
       struct input_dev * dev
       struct ff_effect * effect
       struct file * file

#### Arguments

`dev`

  input device

`effect`

  effect to be uploaded

`file`

  owner of the effect

### LINUX

Kernel Hackers Manual January 2008
input_ff_erase
9
2.6.24-rc6-git8

### input_ff_erase

erase a force-feedback effect from device

#### Synopsis

       int input_ff_erase
       struct input_dev * dev
       int effect_id
       struct file * file

#### Arguments

`dev`

  input device to erase effect from

`effect_id`

  id of the ffect to be erased

`file`

  purported owner of the request

#### Description

This function erases a force-feedback effect from specified device. The effect will only be erased if it was uploaded through the same file handle that is requesting erase.

### LINUX

Kernel Hackers Manual January 2008
input_ff_event
9
2.6.24-rc6-git8

### input_ff_event

generic handler for force-feedback events

#### Synopsis

       int input_ff_event
       struct input_dev * dev
       unsigned int type
       unsigned int code
       int value

#### Arguments

`dev`

  input device to send the effect to

`type`

  event type (anything but EV_FF is ignored)

`code`

  event code

`value`

  event value

### LINUX

Kernel Hackers Manual January 2008
input_ff_create
9
2.6.24-rc6-git8

### input_ff_create

create force-feedback device

#### Synopsis

       int input_ff_create
       struct input_dev * dev
       int max_effects

#### Arguments

`dev`

  input device supporting force-feedback

`max_effects`

  maximum number of effects supported by the device

#### Description

This function allocates all necessary memory for a force feedback portion of an input device and installs all default handlers. `dev`->ffbit should be already set up before calling this function. Once ff device is created you need to setup its upload, erase, playback and other handlers before registering input device

### LINUX

Kernel Hackers Manual January 2008
input_ff_destroy
9
2.6.24-rc6-git8

### input_ff_destroy

frees force feedback portion of input device

#### Synopsis

       void input_ff_destroy
       struct input_dev * dev

#### Arguments

`dev`

  input device supporting force feedback

#### Description

This function is only needed in error path as input core will automatically free force feedback structures when device is destroyed.

### LINUX

Kernel Hackers Manual January 2008
input_ff_create_memless
9
2.6.24-rc6-git8

### input_ff_create_memless

create memoryless force-feedback device

#### Synopsis

       int input_ff_create_memless
       struct input_dev * dev
       void * data
       int (*play_effect)
         struct input_dev *, void *, struct ff_effect *

#### Arguments

`dev`

  input device supporting force-feedback

`data`

  driver-specific data to be passed into `play_effect`

`play_effect`

  driver-specific method for playing FF effect

## Serial Peripheral Interface (SPI)

SPI is the "Serial Peripheral Interface", widely used with embedded systems because it is a simple and efficient interface: basically a multiplexed shift register. Its three signal wires hold a clock (SCK, often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and a "Master In, Slave Out" (MISO) data line. SPI is a full duplex protocol; for each bit shifted out the MOSI line (one per clock) another is shifted in on the MISO line. Those bits are assembled into words of various sizes on the way to and from system memory. An additional chipselect line is usually active-low (nCS); four signals are normally used for each peripheral, plus sometimes an interrupt.

The SPI bus facilities listed here provide a generalized interface to declare SPI busses and devices, manage them according to the standard Linux driver model, and perform input/output operations. At this time, only "master" side interfaces are supported, where Linux talks to SPI peripherals and does not implement such a peripheral itself. (Interfaces to support implementing SPI slaves would necessarily look different.)

The programming interface is structured around two kinds of driver, and two kinds of device. A "Controller Driver" abstracts the controller hardware, which may be as simple as a set of GPIO pins or as complex as a pair of FIFOs connected to dual DMA engines on the other side of the SPI shift register (maximizing throughput). Such drivers bridge between whatever bus they sit on (often the platform bus) and SPI, and expose the SPI side of their device as a struct spi_master. SPI devices are children of that master, represented as a struct spi_device and manufactured from struct spi_board_info descriptors which are usually provided by board-specific initialization code. A struct spi_driver is called a "Protocol Driver", and is bound to a spi_device using normal driver model calls.

The I/O model is a set of queued messages. Protocol drivers submit one or more struct spi_message objects, which are processed and completed asynchronously. (There are synchronous wrappers, however.) Messages are built from one or more struct spi_transfer objects, each of which wraps a full duplex SPI transfer. A variety of protocol tweaking options are needed, because different chips adopt very different policies for how they use the bits transferred with SPI.

### LINUX

Kernel Hackers Manual January 2008
struct spi_device
9
2.6.24-rc6-git8

### struct spi_device

Master side proxy for an SPI slave device

#### Synopsis

    struct spi_device {
      struct device dev;
      struct spi_master * master;
      u32 max_speed_hz;
      u8 chip_select;
      u8 mode;
    #define SPI_CPHA	0x01
    #define SPI_CPOL	0x02
    #define SPI_MODE_0	(0|0)
    #define SPI_MODE_1	(0|SPI_CPHA)
    #define SPI_MODE_2	(SPI_CPOL|0)
    #define SPI_MODE_3	(SPI_CPOL|SPI_CPHA)
    #define SPI_CS_HIGH	0x04
    #define SPI_LSB_FIRST	0x08
    #define SPI_3WIRE	0x10
    #define SPI_LOOP	0x20
      u8 bits_per_word;
      int irq;
      void * controller_state;
      void * controller_data;
      const char * modalias;
    };

#### Members

dev

  Driver model representation of the device.

master

  SPI controller used with the device.

max_speed_hz

  Maximum clock rate to be used with this chip (on this board); may be changed by the device's driver. The spi_transfer.speed_hz can override this for each transfer.

chip_select

  Chipselect, distinguishing chips handled by `master`.

mode

  The spi mode defines how data is clocked out and in. This may be changed by the device's driver. The active low default for chipselect mode can be overridden (by specifying SPI_CS_HIGH) as can the MSB first default for each word in a transfer (by specifying SPI_LSB_FIRST).

bits_per_word

  Data transfers involve one or more words; word sizes like eight or 12 bits are common. In-memory wordsizes are powers of two bytes (e.g. 20 bit samples use 32 bits). This may be changed by the device's driver, or left at the default (0) indicating protocol words are eight bit bytes. The spi_transfer.bits_per_word can override this for each transfer.

irq

  Negative, or the number passed to `request_irq` to receive interrupts from this device.

controller_state

  Controller's runtime state

controller_data

  Board-specific definitions for controller, such as FIFO initialization parameters; from board_info.controller_data

modalias

  Name of the driver to use with this device, or an alias for that name. This appears in the sysfs modalias attribute for driver coldplugging, and in uevents used for hotplugging

#### Description

A `spi_device` is used to interchange data between an SPI slave (usually a discrete chip) and CPU memory.

In `dev`, the platform_data is used to hold information about this device that's meaningful to the device's protocol driver, but not to its controller. One example might be an identifier for a chip variant with slightly different functionality; another might be information about how this particular board wires the chip's pins.

### LINUX

Kernel Hackers Manual January 2008
struct spi_driver
9
2.6.24-rc6-git8

### struct spi_driver

Host side protocol driver

#### Synopsis

    struct spi_driver {
      int (* probe) (struct spi_device *spi);
      int (* remove) (struct spi_device *spi);
      void (* shutdown) (struct spi_device *spi);
      int (* suspend) (struct spi_device *spi, pm_message_t mesg);
      int (* resume) (struct spi_device *spi);
      struct device_driver driver;
    };

#### Members

probe

  Binds this driver to the spi device. Drivers can verify that the device is actually present, and may need to configure characteristics (such as bits_per_word) which weren't needed for the initial configuration done during system setup.

remove

  Unbinds this driver from the spi device

shutdown

  Standard shutdown callback used during system state transitions such as powerdown/halt and kexec

suspend

  Standard suspend callback used during system state transitions

resume

  Standard resume callback used during system state transitions

driver

  SPI device drivers should initialize the name and owner field of this structure.

#### Description

This represents the kind of device driver that uses SPI messages to interact with the hardware at the other end of a SPI link. It's called a protocol driver because it works through messages rather than talking directly to SPI hardware (which is what the underlying SPI controller driver does to pass those messages). These protocols are defined in the specification for the device(s) supported by the driver.

As a rule, those device protocols represent the lowest level interface supported by a driver, and it will support upper level interfaces too. Examples of such upper levels include frameworks like MTD, networking, MMC, RTC, filesystem character device nodes, and hardware monitoring.

### LINUX

Kernel Hackers Manual January 2008
spi_unregister_driver
9
2.6.24-rc6-git8

### spi_unregister_driver

reverse effect of spi_register_driver

#### Synopsis

       void spi_unregister_driver
       struct spi_driver * sdrv

#### Arguments

`sdrv`

  the driver to unregister

#### Context

can sleep

### LINUX

Kernel Hackers Manual January 2008
struct spi_master
9
2.6.24-rc6-git8

### struct spi_master

interface to SPI master controller

#### Synopsis

    struct spi_master {
      struct device dev;
      s16 bus_num;
      u16 num_chipselect;
      int (* setup) (struct spi_device *spi);
      int (* transfer) (struct spi_device *spi,struct spi_message *mesg);
      void (* cleanup) (struct spi_device *spi);
    };

#### Members

dev

  device interface to this driver

bus_num

  board-specific (and often SOC-specific) identifier for a given SPI controller.

num_chipselect

  chipselects are used to distinguish individual SPI slaves, and are numbered from zero to num_chipselects. each slave has a chipselect signal, but it's common that not every chipselect is connected to a slave.

setup

  updates the device mode and clocking records used by a device's SPI controller; protocol code may call this. This must fail if an unrecognized or unsupported mode is requested. It's always safe to call this unless transfers are pending on the device whose settings are being modified.

transfer

  adds a message to the controller's transfer queue.

cleanup

  frees controller-specific state

#### Description

Each SPI master controller can communicate with one or more `spi_device` children. These make a small bus, sharing MOSI, MISO and SCK signals but not chip select signals. Each device may be configured to use a different clock rate, since those shared signals are ignored unless the chip is selected.

The driver for an SPI controller manages access to those devices through a queue of spi_message transactions, copying data between CPU memory and an SPI slave device. For each such message it queues, it calls the message's completion function when the transaction completes.

### LINUX

Kernel Hackers Manual January 2008
struct spi_transfer
9
2.6.24-rc6-git8

### struct spi_transfer

a read/write buffer pair

#### Synopsis

    struct spi_transfer {
      const void * tx_buf;
      void * rx_buf;
      unsigned len;
      dma_addr_t tx_dma;
      dma_addr_t rx_dma;
      unsigned cs_change:1;
      u8 bits_per_word;
      u16 delay_usecs;
      u32 speed_hz;
      struct list_head transfer_list;
    };

#### Members

tx_buf

  data to be written (dma-safe memory), or NULL

rx_buf

  data to be read (dma-safe memory), or NULL

len

  size of rx and tx buffers (in bytes)

tx_dma

  DMA address of tx_buf, if `spi_message`.is_dma_mapped

rx_dma

  DMA address of rx_buf, if `spi_message`.is_dma_mapped

cs_change

  affects chipselect after this transfer completes

bits_per_word

  select a bits_per_word other then the device default for this transfer. If 0 the default (from `spi_device`) is used.

delay_usecs

  microseconds to delay after this transfer before (optionally) changing the chipselect status, then starting the next transfer or completing this `spi_message`.

speed_hz

  Select a speed other then the device default for this transfer. If 0 the default (from `spi_device`) is used.

transfer_list

  transfers are sequenced through `spi_message`.transfers

#### Description

SPI transfers always write the same number of bytes as they read. Protocol drivers should always provide `rx_buf` and/or `tx_buf`. In some cases, they may also want to provide DMA addresses for the data being transferred; that may reduce overhead, when the underlying driver uses dma.

If the transmit buffer is null, zeroes will be shifted out while filling `rx_buf`. If the receive buffer is null, the data shifted in will be discarded. Only len bytes shift out (or in). It's an error to try to shift out a partial word. (For example, by shifting out three bytes with word size of sixteen or twenty bits; the former uses two bytes per word, the latter uses four bytes.)

In-memory data values are always in native CPU byte order, translated from the wire byte order (big-endian except with SPI_LSB_FIRST). So for example when bits_per_word is sixteen, buffers are 2N bytes long (`len` = 2N) and hold N sixteen bit words in CPU byte order.

When the word size of the SPI transfer is not a power-of-two multiple of eight bits, those in-memory words include extra bits. In-memory words are always seen by protocol drivers as right-justified, so the undefined (rx) or unused (tx) bits are always the most significant bits.

All SPI transfers start with the relevant chipselect active. Normally it stays selected until after the last transfer in a message. Drivers can affect the chipselect signal using cs_change.

(i) If the transfer isn't the last one in the message, this flag is used to make the chipselect briefly go inactive in the middle of the message. Toggling chipselect in this way may be needed to terminate a chip command, letting a single spi_message perform all of group of chip transactions together.

(ii) When the transfer is the last one in the message, the chip may stay selected until the next transfer. On multi-device SPI busses with nothing blocking messages going to other devices, this is just a performance hint; starting a message to another device deselects this one. But in other cases, this can be used to ensure correctness. Some devices need protocol transactions to be built from a series of spi_message submissions, where the content of one message is determined by the results of previous messages and where the whole transaction ends when the chipselect goes intactive.

The code that submits an spi_message (and its spi_transfers) to the lower layers is responsible for managing its memory. Zero-initialize every field you don't set up explicitly, to insulate against future API updates. After you submit a message and its transfers, ignore them until its completion callback.

### LINUX

Kernel Hackers Manual January 2008
struct spi_message
9
2.6.24-rc6-git8

### struct spi_message

one multi-segment SPI transaction

#### Synopsis

    struct spi_message {
      struct list_head transfers;
      struct spi_device * spi;
      unsigned is_dma_mapped:1;
      void (* complete) (void *context);
      void * context;
      unsigned actual_length;
      int status;
      struct list_head queue;
      void * state;
    };

#### Members

transfers

  list of transfer segments in this transaction

spi

  SPI device to which the transaction is queued

is_dma_mapped

  if true, the caller provided both dma and cpu virtual addresses for each transfer buffer

complete

  called to report transaction completions

context

  the argument to `complete` when it's called

actual_length

  the total number of bytes that were transferred in all successful segments

status

  zero for success, else negative errno

queue

  for use by whichever driver currently owns the message

state

  for use by whichever driver currently owns the message

#### Description

A `spi_message` is used to execute an atomic sequence of data transfers, each represented by a struct spi_transfer. The sequence is atomic in the sense that no other spi_message may use that SPI bus until that sequence completes. On some systems, many such sequences can execute as as single programmed DMA transfer. On all systems, these messages are queued, and might complete after transactions to other devices. Messages sent to a given spi_device are alway executed in FIFO order.

The code that submits an spi_message (and its spi_transfers) to the lower layers is responsible for managing its memory. Zero-initialize every field you don't set up explicitly, to insulate against future API updates. After you submit a message and its transfers, ignore them until its completion callback.

### LINUX

Kernel Hackers Manual January 2008
spi_setup
9
2.6.24-rc6-git8

### spi_setup

setup SPI mode and clock rate

#### Synopsis

       int spi_setup
       struct spi_device * spi

#### Arguments

`spi`

  the device whose settings are being modified

#### Context

can sleep, and no requests are queued to the device

#### Description

SPI protocol drivers may need to update the transfer mode if the device doesn't work with its default. They may likewise need to update clock rates or word sizes from initial values. This function changes those settings, and must be called from a context that can sleep. Except for SPI_CS_HIGH, which takes effect immediately, the changes take effect the next time the device is selected and data is transferred to or from it. When this function returns, the spi device is deselected.

Note that this call will fail if the protocol driver specifies an option that the underlying controller or its driver does not support. For example, not all hardware supports wire transfers using nine bit words, LSB-first wire encoding, or active-high chipselects.

### LINUX

Kernel Hackers Manual January 2008
spi_async
9
2.6.24-rc6-git8

### spi_async

asynchronous SPI transfer

#### Synopsis

       int spi_async
       struct spi_device * spi
       struct spi_message * message

#### Arguments

`spi`

  device with which data will be exchanged

`message`

  describes the data transfers, including completion callback

#### Context

any (irqs may be blocked, etc)

#### Description

This call may be used in_irq and other contexts which can't sleep, as well as from task contexts which can sleep.

The completion callback is invoked in a context which can't sleep. Before that invocation, the value of message->status is undefined. When the callback is issued, message->status holds either zero (to indicate complete success) or a negative error code. After that callback returns, the driver which issued the transfer request may deallocate the associated memory; it's no longer in use by any SPI core or controller driver code.

Note that although all messages to a spi_device are handled in FIFO order, messages may go to different devices in other orders. Some device might be higher priority, or have various hard access time requirements, for example.

On detection of any fault during the transfer, processing of the entire message is aborted, and the device is deselected. Until returning from the associated message completion callback, no other spi_message queued to that device will be processed. (This rule applies equally to all the synchronous transfer calls, which are wrappers around this core asynchronous primitive.)

### LINUX

Kernel Hackers Manual January 2008
spi_write
9
2.6.24-rc6-git8

### spi_write

SPI synchronous write

#### Synopsis

       int spi_write
       struct spi_device * spi
       const u8 * buf
       size_t len

#### Arguments

`spi`

  device to which data will be written

`buf`

  data buffer

`len`

  data buffer size

#### Context

can sleep

#### Description

This writes the buffer and returns zero or a negative error code. Callable only from contexts that can sleep.

### LINUX

Kernel Hackers Manual January 2008
spi_read
9
2.6.24-rc6-git8

### spi_read

SPI synchronous read

#### Synopsis

       int spi_read
       struct spi_device * spi
       u8 * buf
       size_t len

#### Arguments

`spi`

  device from which data will be read

`buf`

  data buffer

`len`

  data buffer size

#### Context

can sleep

#### Description

This reads the buffer and returns zero or a negative error code. Callable only from contexts that can sleep.

### LINUX

Kernel Hackers Manual January 2008
spi_w8r8
9
2.6.24-rc6-git8

### spi_w8r8

SPI synchronous 8 bit write followed by 8 bit read

#### Synopsis

       ssize_t spi_w8r8
       struct spi_device * spi
       u8 cmd

#### Arguments

`spi`

  device with which data will be exchanged

`cmd`

  command to be written before data is read back

#### Context

can sleep

#### Description

This returns the (unsigned) eight bit number returned by the device, or else a negative error code. Callable only from contexts that can sleep.

### LINUX

Kernel Hackers Manual January 2008
spi_w8r16
9
2.6.24-rc6-git8

### spi_w8r16

SPI synchronous 8 bit write followed by 16 bit read

#### Synopsis

       ssize_t spi_w8r16
       struct spi_device * spi
       u8 cmd

#### Arguments

`spi`

  device with which data will be exchanged

`cmd`

  command to be written before data is read back

#### Context

can sleep

#### Description

This returns the (unsigned) sixteen bit number returned by the device, or else a negative error code. Callable only from contexts that can sleep.

The number is returned in wire-order, which is at least sometimes big-endian.

### LINUX

Kernel Hackers Manual January 2008
struct spi_board_info
9
2.6.24-rc6-git8

### struct spi_board_info

board-specific template for a SPI device

#### Synopsis

    struct spi_board_info {
      char modalias[KOBJ_NAME_LEN];
      const void * platform_data;
      void * controller_data;
      int irq;
      u32 max_speed_hz;
      u16 bus_num;
      u16 chip_select;
      u8 mode;
    };

#### Members

modalias[KOBJ_NAME_LEN]

  Initializes spi_device.modalias; identifies the driver.

platform_data

  Initializes spi_device.platform_data; the particular data stored there is driver-specific.

controller_data

  Initializes spi_device.controller_data; some controllers need hints about hardware setup, e.g. for DMA.

irq

  Initializes spi_device.irq; depends on how the board is wired.

max_speed_hz

  Initializes spi_device.max_speed_hz; based on limits from the chip datasheet and board-specific signal quality issues.

bus_num

  Identifies which spi_master parents the spi_device; unused by `spi_new_device`, and otherwise depends on board wiring.

chip_select

  Initializes spi_device.chip_select; depends on how the board is wired.

mode

  Initializes spi_device.mode; based on the chip datasheet, board wiring (some devices support both 3WIRE and standard modes), and possibly presence of an inverter in the chipselect path.

#### Description

When adding new SPI devices to the device tree, these structures serve as a partial device template. They hold information which can't always be determined by drivers. Information that `probe` can establish (such as the default transfer wordsize) is not included here.

These structures are used in two places. Their primary role is to be stored in tables of board-specific device descriptors, which are declared early in board initialization and then used (much later) to populate a controller's device tree after the that controller's driver initializes. A secondary (and atypical) role is as a parameter to `spi_new_device` call, which happens after those controller drivers are active in some dynamic board configuration models.

### LINUX

Kernel Hackers Manual January 2008
spi_register_board_info
9
2.6.24-rc6-git8

### spi_register_board_info

register SPI devices for a given board

#### Synopsis

       int __init spi_register_board_info
       struct spi_board_info const * info
       unsigned n

#### Arguments

`info`

  array of chip descriptors

`n`

  how many descriptors are provided

#### Context

can sleep

#### Description

Board-specific early init code calls this (probably during arch_initcall) with segments of the SPI device table. Any device nodes are created later, after the relevant parent SPI controller (bus_num) is defined. We keep this table of devices forever, so that reloading a controller driver will not make Linux forget about these hard-wired devices.

Other code can also call this, e.g. a particular add-on board might provide SPI devices through its expansion connector, so code initializing that board would naturally declare its SPI devices.

The board info passed can safely be __initdata ... but be careful of any embedded pointers (platform_data, etc), they're copied as-is.

### LINUX

Kernel Hackers Manual January 2008
spi_register_driver
9
2.6.24-rc6-git8

### spi_register_driver

register a SPI driver

#### Synopsis

       int spi_register_driver
       struct spi_driver * sdrv

#### Arguments

`sdrv`

  the driver to register

#### Context

can sleep

### LINUX

Kernel Hackers Manual January 2008
spi_new_device
9
2.6.24-rc6-git8

### spi_new_device

instantiate one new SPI device

#### Synopsis

       struct spi_device * spi_new_device
       struct spi_master * master
       struct spi_board_info * chip

#### Arguments

`master`

  Controller to which device is connected

`chip`

  Describes the SPI device

#### Context

can sleep

#### Description

On typical mainboards, this is purely internal; and it's not needed after board init creates the hard-wired devices. Some development platforms may not be able to use spi_register_board_info though, and this is exported so that for example a USB or parport based adapter driver could add devices (which it would learn about out-of-band).

Returns the new device, or NULL.

### LINUX

Kernel Hackers Manual January 2008
spi_alloc_master
9
2.6.24-rc6-git8

### spi_alloc_master

allocate SPI master controller

#### Synopsis

       struct spi_master * spi_alloc_master
       struct device * dev
       unsigned size

#### Arguments

`dev`

  the controller, possibly using the platform_bus

`size`

  how much zeroed driver-private data to allocate; the pointer to this memory is in the driver_data field of the returned device, accessible with `spi_master_get_devdata`.

#### Context

can sleep

#### Description

This call is used only by SPI master controller drivers, which are the only ones directly touching chip registers. It's how they allocate an spi_master structure, prior to calling `spi_register_master`.

This must be called from context that can sleep. It returns the SPI master structure on success, else NULL.

The caller is responsible for assigning the bus number and initializing the master's methods before calling `spi_register_master`; and (after errors adding the device) calling `spi_master_put` to prevent a memory leak.

### LINUX

Kernel Hackers Manual January 2008
spi_register_master
9
2.6.24-rc6-git8

### spi_register_master

register SPI master controller

#### Synopsis

       int spi_register_master
       struct spi_master * master

#### Arguments

`master`

  initialized master, originally from `spi_alloc_master`

#### Context

can sleep

#### Description

SPI master controllers connect to their drivers using some non-SPI bus, such as the platform bus. The final stage of `probe` in that code includes calling `spi_register_master` to hook up to this SPI bus glue.

SPI controllers use board specific (often SOC specific) bus numbers, and board-specific addressing for SPI devices combines those numbers with chip select numbers. Since SPI does not directly support dynamic device identification, boards need configuration tables telling which chip is at which address.

This must be called from context that can sleep. It returns zero on success, else a negative error code (dropping the master's refcount). After a successful return, the caller is responsible for calling `spi_unregister_master`.

### LINUX

Kernel Hackers Manual January 2008
spi_unregister_master
9
2.6.24-rc6-git8

### spi_unregister_master

unregister SPI master controller

#### Synopsis

       void spi_unregister_master
       struct spi_master * master

#### Arguments

`master`

  the master being unregistered

#### Context

can sleep

#### Description

This call is used only by SPI master controller drivers, which are the only ones directly touching chip registers.

This must be called from context that can sleep.

### LINUX

Kernel Hackers Manual January 2008
spi_busnum_to_master
9
2.6.24-rc6-git8

### spi_busnum_to_master

look up master associated with bus_num

#### Synopsis

       struct spi_master * spi_busnum_to_master
       u16 bus_num

#### Arguments

`bus_num`

  the master's bus number

#### Context

can sleep

#### Description

This call may be used with devices that are registered after arch init time. It returns a refcounted pointer to the relevant spi_master (which the caller must release), or NULL if there is no such master registered.

### LINUX

Kernel Hackers Manual January 2008
spi_sync
9
2.6.24-rc6-git8

### spi_sync

blocking/synchronous SPI data transfers

#### Synopsis

       int spi_sync
       struct spi_device * spi
       struct spi_message * message

#### Arguments

`spi`

  device with which data will be exchanged

`message`

  describes the data transfers

#### Context

can sleep

#### Description

This call may only be used from a context that may sleep. The sleep is non-interruptible, and has no timeout. Low-overhead controller drivers may DMA directly into and out of the message buffers.

Note that the SPI device's chip select is active during the message, and then is normally disabled between messages. Drivers for some frequently-used devices may want to minimize costs of selecting a chip, by leaving it selected in anticipation that the next message will go to the same chip. (That may increase power usage.)

Also, the caller is guaranteeing that the memory associated with the message will not be freed before this call returns.

It returns zero on success, else a negative error code.

### LINUX

Kernel Hackers Manual January 2008
spi_write_then_read
9
2.6.24-rc6-git8

### spi_write_then_read

SPI synchronous write followed by read

#### Synopsis

       int spi_write_then_read
       struct spi_device * spi
       const u8 * txbuf
       unsigned n_tx
       u8 * rxbuf
       unsigned n_rx

#### Arguments

`spi`

  device with which data will be exchanged

`txbuf`

  data to be written (need not be dma-safe)

`n_tx`

  size of txbuf, in bytes

`rxbuf`

  buffer into which data will be read

`n_rx`

  size of rxbuf, in bytes (need not be dma-safe)

#### Context

can sleep

#### Description

This performs a half duplex MicroWire style transaction with the device, sending txbuf and then reading rxbuf. The return value is zero for success, else a negative errno status code. This call may only be used from a context that may sleep.

Parameters to this routine are always copied using a small buffer; portable code should never use this for more than 32 bytes. Performance-sensitive or bulk transfer code should instead use spi_{async,sync}() calls with dma-safe buffers.

## I2C and SMBus Subsystem

I2C (or without fancy typography, "I2C") is an acronym for the "Inter-IC" bus, a simple bus protocol which is widely used where low data rate communications suffice. Since it's also a licensed trademark, some vendors use another name (such as "Two-Wire Interface", TWI) for the same bus. I2C only needs two signals (SCL for clock, SDA for data), conserving board real estate and minimizing signal quality issues. Most I2C devices use seven bit addresses, and bus speeds of up to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet found wide use. I2C is a multi-master bus; open drain signaling is used to arbitrate between masters, as well as to handshake and to synchronize clocks from slower clients.

The Linux I2C programming interfaces support only the master side of bus interactions, not the slave side. The programming interface is structured around two kinds of driver, and two kinds of device. An I2C "Adapter Driver" abstracts the controller hardware; it binds to a physical device (perhaps a PCI device or platform_device) and exposes a struct i2c_adapter representing each I2C bus segment it manages. On each I2C bus segment will be I2C devices represented by a struct i2c_client. Those devices will be bound to a struct i2c_driver, which should follow the standard Linux driver model. (At this writing, a legacy model is more widely used.) There are functions to perform various I2C protocol operations; at this writing all such functions are usable only from task context.

The System Management Bus (SMBus) is a sibling protocol. Most SMBus systems are also I2C conformant. The electrical constraints are tighter for SMBus, and it standardizes particular protocol messages and idioms. Controllers that support I2C can also support most SMBus operations, but SMBus controllers don't support all the protocol options that an I2C controller will. There are functions to perform various SMBus protocol operations, either using I2C primitives or by issuing SMBus commands to i2c_adapter devices which don't support those I2C operations.

### LINUX

Kernel Hackers Manual January 2008
struct i2c_client
9
2.6.24-rc6-git8

### struct i2c_client

represent an I2C slave device

#### Synopsis

    struct i2c_client {
      unsigned short flags;
      unsigned short addr;
      char name[I2C_NAME_SIZE];
      struct i2c_adapter * adapter;
      struct i2c_driver * driver;
      int usage_count;
      struct device dev;
      int irq;
      char driver_name[KOBJ_NAME_LEN];
      struct list_head list;
      struct completion released;
    };

#### Members

flags

  I2C_CLIENT_TEN indicates the device uses a ten bit chip address; I2C_CLIENT_PEC indicates it uses SMBus Packet Error Checking

addr

  Address used on the I2C bus connected to the parent adapter.

name[I2C_NAME_SIZE]

  Indicates the type of the device, usually a chip name that's generic enough to hide second-sourcing and compatible revisions.

adapter

  manages the bus segment hosting this I2C device

driver

  device's driver, hence pointer to access routines

usage_count

  counts current number of users of this client

dev

  Driver model device node for the slave.

irq

  indicates the IRQ generated by this device (if any)

driver_name[KOBJ_NAME_LEN]

  Identifies new-style driver used with this device; also used as the module name for hotplug/coldplug modprobe support.

list

  list of active/busy clients

released

  used to synchronize client releases & detaches and references

#### Description

An i2c_client identifies a single device (i.e. chip) connected to an i2c bus. The behaviour exposed to Linux is defined by the driver managing the device.

### LINUX

Kernel Hackers Manual January 2008
struct i2c_board_info
9
2.6.24-rc6-git8

### struct i2c_board_info

template for device creation

#### Synopsis

    struct i2c_board_info {
      char driver_name[KOBJ_NAME_LEN];
      char type[I2C_NAME_SIZE];
      unsigned short flags;
      unsigned short addr;
      void * platform_data;
      int irq;
    };

#### Members

driver_name[KOBJ_NAME_LEN]

  identifies the driver to be bound to the device

type[I2C_NAME_SIZE]

  optional chip type information, to initialize i2c_client.name

flags

  to initialize i2c_client.flags

addr

  stored in i2c_client.addr

platform_data

  stored in i2c_client.dev.platform_data

irq

  stored in i2c_client.irq

#### Description

I2C doesn't actually support hardware probing, although controllers and devices may be able to use I2C_SMBUS_QUICK to tell whether or not there's a device at a given address. Drivers commonly need more information than that, such as chip type, configuration, associated IRQ, and so on.

i2c_board_info is used to build tables of information listing I2C devices that are present. This information is used to grow the driver model tree for new style I2C drivers. For mainboards this is done statically using `i2c_register_board_info`; bus numbers identify adapters that aren't yet available. For add-on boards, `i2c_new_device` does this dynamically with the adapter already known.

### LINUX

Kernel Hackers Manual January 2008
I2C_BOARD_INFO
9
2.6.24-rc6-git8

### I2C_BOARD_INFO

macro used to list an i2c device and its driver

#### Synopsis

        I2C_BOARD_INFO
        driver
        dev_addr

#### Arguments

`driver`

  identifies the driver to use with the device

`dev_addr`

  the device's address on the bus.

#### Description

This macro initializes essential fields of a struct i2c_board_info, declaring what has been provided on a particular board. Optional fields (such as the chip type, its associated irq, or device-specific platform_data) are provided using conventional syntax.

### LINUX

Kernel Hackers Manual January 2008
struct i2c_msg
9
2.6.24-rc6-git8

### struct i2c_msg

an I2C transaction segment beginning with START

#### Synopsis

    struct i2c_msg {
      __u16 addr;
      __u16 flags;
    #define I2C_M_TEN		0x0010
    #define I2C_M_RD		0x0001
    #define I2C_M_NOSTART		0x4000
    #define I2C_M_REV_DIR_ADDR	0x2000
    #define I2C_M_IGNORE_NAK	0x1000
    #define I2C_M_NO_RD_ACK		0x0800
    #define I2C_M_RECV_LEN		0x0400
      __u16 len;
      __u8 * buf;
    };

#### Members

addr

  Slave address, either seven or ten bits. When this is a ten bit address, I2C_M_TEN must be set in `flags` and the adapter must support I2C_FUNC_10BIT_ADDR.

flags

  I2C_M_RD is handled by all adapters. No other flags may be provided unless the adapter exported the relevant I2C_FUNC_* flags through `i2c_check_functionality`.

len

  Number of data bytes in `buf` being read from or written to the I2C slave address. For read transactions where I2C_M_RECV_LEN is set, the caller guarantees that this buffer can hold up to 32 bytes in addition to the initial length byte sent by the slave (plus, if used, the SMBus PEC); and this value will be incremented by the number of block data bytes received.

buf

  The buffer into which data is read, or from which it's written.

#### Description

An i2c_msg is the low level representation of one segment of an I2C transaction. It is visible to drivers in the `i2c_transfer`() procedure, to userspace from i2c-dev, and to I2C adapter drivers through the `i2c_adapter`.`master_xfer`() method.

Except when I2C protocol mangling is used, all I2C adapters implement the standard rules for I2C transactions. Each transaction begins with a START. That is followed by the slave address, and a bit encoding read versus write. Then follow all the data bytes, possibly including a byte with SMBus PEC. The transfer terminates with a NAK, or when all those bytes have been transferred and ACKed. If this is the last message in a group, it is followed by a STOP. Otherwise it is followed by the next `i2c_msg` transaction segment, beginning with a (repeated) START.

Alternatively, when the adapter supports I2C_FUNC_PROTOCOL_MANGLING then passing certain `flags` may have changed those standard protocol behaviors. Those flags are only for use with broken/nonconforming slaves, and with adapters which are known to support the specific mangling options they need (one or more of IGNORE_NAK, NO_RD_ACK, NOSTART, and REV_DIR_ADDR).

### LINUX

Kernel Hackers Manual January 2008
i2c_register_board_info
9
2.6.24-rc6-git8

### i2c_register_board_info

statically declare I2C devices

#### Synopsis

       int __init i2c_register_board_info
       int busnum
       struct i2c_board_info const * info
       unsigned len

#### Arguments

`busnum`

  identifies the bus to which these devices belong

`info`

  vector of i2c device descriptors

`len`

  how many descriptors in the vector; may be zero to reserve the specified bus number.

#### Description

Systems using the Linux I2C driver stack can declare tables of board info while they initialize. This should be done in board-specific init code near `arch_initcall` time, or equivalent, before any I2C adapter driver is registered. For example, mainboard init code could define several devices, as could the init code for each daughtercard in a board stack.

The I2C devices will be created later, after the adapter for the relevant bus has been registered. After that moment, standard driver model tools are used to bind new style I2C drivers to the devices. The bus number for any device declared using this routine is not available for dynamic allocation.

The board info passed can safely be __initdata, but be careful of embedded pointers (for platform_data, functions, etc) since that won't be copied.

### LINUX

Kernel Hackers Manual January 2008
i2c_new_device
9
2.6.24-rc6-git8

### i2c_new_device

instantiate an i2c device for use with a new style driver

#### Synopsis

       struct i2c_client * i2c_new_device
       struct i2c_adapter * adap
       struct i2c_board_info const * info

#### Arguments

`adap`

  the adapter managing the device

`info`

  describes one I2C device; bus_num is ignored

#### Context

can sleep

#### Description

Create a device to work with a new style i2c driver, where binding is handled through driver model `probe`/`remove` methods. This call is not appropriate for use by mainboad initialization logic, which usually runs during an `arch_initcall` long before any i2c_adapter could exist.

This returns the new i2c client, which may be saved for later use with `i2c_unregister_device`; or NULL to indicate an error.

### LINUX

Kernel Hackers Manual January 2008
i2c_unregister_device
9
2.6.24-rc6-git8

### i2c_unregister_device

reverse effect of `i2c_new_device`

#### Synopsis

       void i2c_unregister_device
       struct i2c_client * client

#### Arguments

`client`

  value returned from `i2c_new_device`

#### Context

can sleep

### LINUX

Kernel Hackers Manual January 2008
i2c_add_adapter
9
2.6.24-rc6-git8

### i2c_add_adapter

declare i2c adapter, use dynamic bus number

#### Synopsis

       int i2c_add_adapter
       struct i2c_adapter * adapter

#### Arguments

`adapter`

  the adapter to add

#### Context

can sleep

#### Description

This routine is used to declare an I2C adapter when its bus number doesn't matter. Examples: for I2C adapters dynamically added by USB links or PCI plugin cards.

When this returns zero, a new bus number was allocated and stored in adap->nr, and the specified adapter became available for clients. Otherwise, a negative errno value is returned.

### LINUX

Kernel Hackers Manual January 2008
i2c_add_numbered_adapter
9
2.6.24-rc6-git8

### i2c_add_numbered_adapter

declare i2c adapter, use static bus number

#### Synopsis

       int i2c_add_numbered_adapter
       struct i2c_adapter * adap

#### Arguments

`adap`

  the adapter to register (with adap->nr initialized)

#### Context

can sleep

#### Description

This routine is used to declare an I2C adapter when its bus number matters. Example: for I2C adapters from system-on-chip CPUs, or otherwise built in to the system's mainboard, and where i2c_board_info is used to properly configure I2C devices.

If no devices have pre-been declared for this bus, then be sure to register the adapter before any dynamically allocated ones. Otherwise the required bus ID may not be available.

When this returns zero, the specified adapter became available for clients using the bus number provided in adap->nr. Also, the table of I2C devices pre-declared using `i2c_register_board_info` is scanned, and the appropriate driver model device nodes are created. Otherwise, a negative errno value is returned.

### LINUX

Kernel Hackers Manual January 2008
i2c_del_adapter
9
2.6.24-rc6-git8

### i2c_del_adapter

unregister I2C adapter

#### Synopsis

       int i2c_del_adapter
       struct i2c_adapter * adap

#### Arguments

`adap`

  the adapter being unregistered

#### Context

can sleep

#### Description

This unregisters an I2C adapter which was previously registered by `i2c_add_adapter` or `i2c_add_numbered_adapter`.

### LINUX

Kernel Hackers Manual January 2008
i2c_del_driver
9
2.6.24-rc6-git8

### i2c_del_driver

unregister I2C driver

#### Synopsis

       void i2c_del_driver
       struct i2c_driver * driver

#### Arguments

`driver`

  the driver being unregistered

#### Context

can sleep

### LINUX

Kernel Hackers Manual January 2008
i2c_smbus_read_block_data
9
2.6.24-rc6-git8

### i2c_smbus_read_block_data

SMBus block read request

#### Synopsis

       s32 i2c_smbus_read_block_data
       struct i2c_client * client
       u8 command
       u8 * values

#### Arguments

`client`

  Handle to slave device

`command`

  Command byte issued to let the slave know what data should be returned

`values`

  Byte array into which data will be read; big enough to hold the data returned by the slave. SMBus allows at most 32 bytes.

#### Description

Returns the number of bytes read in the slave's response, else a negative number to indicate some kind of error.

Note that using this function requires that the client's adapter support the I2C_FUNC_SMBUS_READ_BLOCK_DATA functionality. Not all adapter drivers support this; its emulation through I2C messaging relies on a specific mechanism (I2C_M_RECV_LEN) which may not be implemented.

## splice API

splice is a method for moving blocks of data around inside the kernel, without continually transferring them between the kernel and user space.

### LINUX

Kernel Hackers Manual January 2008
splice_to_pipe
9
2.6.24-rc6-git8

### splice_to_pipe

fill passed data into a pipe

#### Synopsis

       ssize_t splice_to_pipe
       struct pipe_inode_info * pipe
       struct splice_pipe_desc * spd

#### Arguments

`pipe`

  pipe to fill

`spd`

  data to fill

#### Description

`spd` contains a map of pages and len/offset tuples, along with the struct pipe_buf_operations associated with these pages. This function will link that data to the pipe.

### LINUX

Kernel Hackers Manual January 2008
generic_file_splice_read
9
2.6.24-rc6-git8

### generic_file_splice_read

splice data from file to a pipe

#### Synopsis

       ssize_t generic_file_splice_read
       struct file * in
       loff_t * ppos
       struct pipe_inode_info * pipe
       size_t len
       unsigned int flags

#### Arguments

`in`

  file to splice from

`ppos`

  position in `in`

`pipe`

  pipe to splice to

`len`

  number of bytes to splice

`flags`

  splice modifier flags

#### Description

Will read pages from given file and fill them into a pipe. Can be used as long as the address_space operations for the source implements a `readpage` hook.

### LINUX

Kernel Hackers Manual January 2008
__splice_from_pipe
9
2.6.24-rc6-git8

### __splice_from_pipe

splice data from a pipe to given actor

#### Synopsis

       ssize_t __splice_from_pipe
       struct pipe_inode_info * pipe
       struct splice_desc * sd
       splice_actor * actor

#### Arguments

`pipe`

  pipe to splice from

`sd`

  information to `actor`

`actor`

  handler that splices the data

#### Description

This function does little more than loop over the pipe and call `actor` to do the actual moving of a single struct pipe_buffer to the desired destination. See pipe_to_file, pipe_to_sendpage, or pipe_to_user.

### LINUX

Kernel Hackers Manual January 2008
splice_from_pipe
9
2.6.24-rc6-git8

### splice_from_pipe

splice data from a pipe to a file

#### Synopsis

       ssize_t splice_from_pipe
       struct pipe_inode_info * pipe
       struct file * out
       loff_t * ppos
       size_t len
       unsigned int flags
       splice_actor * actor

#### Arguments

`pipe`

  pipe to splice from

`out`

  file to splice to

`ppos`

  position in `out`

`len`

  how many bytes to splice

`flags`

  splice modifier flags

`actor`

  handler that splices the data

#### Description

See __splice_from_pipe. This function locks the input and output inodes, otherwise it's identical to `__splice_from_pipe`.

### LINUX

Kernel Hackers Manual January 2008
generic_file_splice_write_nolock
9
2.6.24-rc6-git8

### generic_file_splice_write_nolock

generic_file_splice_write without mutexes

#### Synopsis

       ssize_t generic_file_splice_write_nolock
       struct pipe_inode_info * pipe
       struct file * out
       loff_t * ppos
       size_t len
       unsigned int flags

#### Arguments

`pipe`

  pipe info

`out`

  file to write to

`ppos`

  position in `out`

`len`

  number of bytes to splice

`flags`

  splice modifier flags

#### Description

Will either move or copy pages (determined by `flags` options) from the given pipe inode to the given file. The caller is responsible for acquiring i_mutex on both inodes.

### LINUX

Kernel Hackers Manual January 2008
generic_file_splice_write
9
2.6.24-rc6-git8

### generic_file_splice_write

splice data from a pipe to a file

#### Synopsis

       ssize_t generic_file_splice_write
       struct pipe_inode_info * pipe
       struct file * out
       loff_t * ppos
       size_t len
       unsigned int flags

#### Arguments

`pipe`

  pipe info

`out`

  file to write to

`ppos`

  position in `out`

`len`

  number of bytes to splice

`flags`

  splice modifier flags

#### Description

Will either move or copy pages (determined by `flags` options) from the given pipe inode to the given file.

### LINUX

Kernel Hackers Manual January 2008
generic_splice_sendpage
9
2.6.24-rc6-git8

### generic_splice_sendpage

splice data from a pipe to a socket

#### Synopsis

       ssize_t generic_splice_sendpage
       struct pipe_inode_info * pipe
       struct file * out
       loff_t * ppos
       size_t len
       unsigned int flags

#### Arguments

`pipe`

  pipe to splice from

`out`

  socket to write to

`ppos`

  position in `out`

`len`

  number of bytes to splice

`flags`

  splice modifier flags

#### Description

Will send `len` bytes from the pipe to a network socket. No data copying is involved.

### LINUX

Kernel Hackers Manual January 2008
splice_direct_to_actor
9
2.6.24-rc6-git8

### splice_direct_to_actor

splices data directly between two non-pipes

#### Synopsis

       ssize_t splice_direct_to_actor
       struct file * in
       struct splice_desc * sd
       splice_direct_actor * actor

#### Arguments

`in`

  file to splice from

`sd`

  actor information on where to splice to

`actor`

  handles the data splicing

#### Description

This is a special case helper to splice directly between two points, without requiring an explicit pipe. Internally an allocated pipe is cached in the process, and reused during the lifetime of that process.

### LINUX

Kernel Hackers Manual January 2008
do_splice_direct
9
2.6.24-rc6-git8

### do_splice_direct

splices data directly between two files

#### Synopsis

       long do_splice_direct
       struct file * in
       loff_t * ppos
       struct file * out
       size_t len
       unsigned int flags

#### Arguments

`in`

  file to splice from

`ppos`

  input file offset

`out`

  file to splice to

`len`

  number of bytes to splice

`flags`

  splice modifier flags

#### Description

For use by `do_sendfile`. splice can easily emulate sendfile, but doing it in the application would incur an extra system call (splice in + splice out, as compared to just `sendfile`). So this helper can splice directly through a process-private pipe.

## pipes API

Pipe interfaces are all for in-kernel (builtin image) use. They are not exported for use by modules.

### LINUX

Kernel Hackers Manual January 2008
struct pipe_buffer
9
2.6.24-rc6-git8

### struct pipe_buffer

a linux kernel pipe buffer

#### Synopsis

    struct pipe_buffer {
      struct page * page;
      unsigned int offset;
      unsigned int len;
      const struct pipe_buf_operations * ops;
      unsigned int flags;
      unsigned long private;
    };

#### Members

page

  the page containing the data for the pipe buffer

offset

  offset of data inside the `page`

len

  length of data inside the `page`

ops

  operations associated with this buffer. See `pipe_buf_operations`.

flags

  pipe buffer flags. See above.

private

  private data owned by the ops.

### LINUX

Kernel Hackers Manual January 2008
struct pipe_inode_info
9
2.6.24-rc6-git8

### struct pipe_inode_info

a linux kernel pipe

#### Synopsis

    struct pipe_inode_info {
      wait_queue_head_t wait;
      unsigned int nrbufs;
      unsigned int curbuf;
      struct page * tmp_page;
      unsigned int readers;
      unsigned int writers;
      unsigned int waiting_writers;
      unsigned int r_counter;
      unsigned int w_counter;
      struct fasync_struct * fasync_readers;
      struct fasync_struct * fasync_writers;
      struct inode * inode;
      struct pipe_buffer bufs[PIPE_BUFFERS];
    };

#### Members

wait

  reader/writer wait point in case of empty/full pipe

nrbufs

  the number of non-empty pipe buffers in this pipe

curbuf

  the current pipe buffer entry

tmp_page

  cached released page

readers

  number of current readers of this pipe

writers

  number of current writers of this pipe

waiting_writers

  number of writers blocked waiting for room

r_counter

  reader counter

w_counter

  writer counter

fasync_readers

  reader side fasync

fasync_writers

  writer side fasync

inode

  inode this pipe is attached to

bufs[PIPE_BUFFERS]

  the circular array of pipe buffers

### LINUX

Kernel Hackers Manual January 2008
generic_pipe_buf_map
9
2.6.24-rc6-git8

### generic_pipe_buf_map

virtually map a pipe buffer

#### Synopsis

       void * generic_pipe_buf_map
       struct pipe_inode_info * pipe
       struct pipe_buffer * buf
       int atomic

#### Arguments

`pipe`

  the pipe that the buffer belongs to

`buf`

  the buffer that should be mapped

`atomic`

  whether to use an atomic map

#### Description

This function returns a kernel virtual address mapping for the passed in `pipe_buffer`. If `atomic` is set, an atomic map is provided and the caller has to be careful not to fault before calling the unmap function.

Note that this function occupies KM_USER0 if `atomic` != 0.

### LINUX

Kernel Hackers Manual January 2008
generic_pipe_buf_unmap
9
2.6.24-rc6-git8

### generic_pipe_buf_unmap

unmap a previously mapped pipe buffer

#### Synopsis

       void generic_pipe_buf_unmap
       struct pipe_inode_info * pipe
       struct pipe_buffer * buf
       void * map_data

#### Arguments

`pipe`

  the pipe that the buffer belongs to

`buf`

  the buffer that should be unmapped

`map_data`

  the data that the mapping function returned

#### Description

This function undoes the mapping that ->`map` provided.

### LINUX

Kernel Hackers Manual January 2008
generic_pipe_buf_steal
9
2.6.24-rc6-git8

### generic_pipe_buf_steal

attempt to take ownership of a `pipe_buffer`

#### Synopsis

       int generic_pipe_buf_steal
       struct pipe_inode_info * pipe
       struct pipe_buffer * buf

#### Arguments

`pipe`

  the pipe that the buffer belongs to

`buf`

  the buffer to attempt to steal

#### Description

This function attempts to steal the `struct` page attached to `buf`. If successful, this function returns 0 and returns with the page locked. The caller may then reuse the page for whatever he wishes, the typical use is insertion into a different file page cache.

### LINUX

Kernel Hackers Manual January 2008
generic_pipe_buf_get
9
2.6.24-rc6-git8

### generic_pipe_buf_get

get a reference to a `struct` pipe_buffer

#### Synopsis

       void generic_pipe_buf_get
       struct pipe_inode_info * pipe
       struct pipe_buffer * buf

#### Arguments

`pipe`

  the pipe that the buffer belongs to

`buf`

  the buffer to get a reference to

#### Description

This function grabs an extra reference to `buf`. It's used in in the `tee` system call, when we duplicate the buffers in one pipe into another.

### LINUX

Kernel Hackers Manual January 2008
generic_pipe_buf_confirm
9
2.6.24-rc6-git8

### generic_pipe_buf_confirm

verify contents of the pipe buffer

#### Synopsis

       int generic_pipe_buf_confirm
       struct pipe_inode_info * info
       struct pipe_buffer * buf

#### Arguments

`info`

  the pipe that the buffer belongs to

`buf`

  the buffer to confirm

#### Description

This function does nothing, because the generic pipe code uses pages that are always good when inserted into the pipe.