This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA For more details see the file COPYING in the source distribution of Linux. Kernel Hackers Manual October 2009 list_add 9 2.6.32-rc5 list_add add a new entry void list_add struct list_head * new struct list_head * head new new entry to be added head list head to add it after Insert a new entry after the specified head. This is good for implementing stacks. Kernel Hackers Manual October 2009 list_add_tail 9 2.6.32-rc5 list_add_tail add a new entry void list_add_tail struct list_head * new struct list_head * head new new entry to be added head list head to add it before Insert a new entry before the specified head. This is useful for implementing queues. Kernel Hackers Manual October 2009 list_del 9 2.6.32-rc5 list_del deletes entry from list. void list_del struct list_head * entry entry the element to delete from the list. list_empty on entry does not return true after this, the entry is in an undefined state. Kernel Hackers Manual October 2009 list_replace 9 2.6.32-rc5 list_replace replace old entry by new one void list_replace struct list_head * old struct list_head * new old the element to be replaced new the new element to insert If old was empty, it will be overwritten. Kernel Hackers Manual October 2009 list_del_init 9 2.6.32-rc5 list_del_init deletes entry from list and reinitialize it. void list_del_init struct list_head * entry entry the element to delete from the list. Kernel Hackers Manual October 2009 list_move 9 2.6.32-rc5 list_move delete from one list and add as another's head void list_move struct list_head * list struct list_head * head list the entry to move head the head that will precede our entry Kernel Hackers Manual October 2009 list_move_tail 9 2.6.32-rc5 list_move_tail delete from one list and add as another's tail void list_move_tail struct list_head * list struct list_head * head list the entry to move head the head that will follow our entry Kernel Hackers Manual October 2009 list_is_last 9 2.6.32-rc5 list_is_last tests whether list is the last entry in list head int list_is_last const struct list_head * list const struct list_head * head list the entry to test head the head of the list Kernel Hackers Manual October 2009 list_empty 9 2.6.32-rc5 list_empty tests whether a list is empty int list_empty const struct list_head * head head the list to test. Kernel Hackers Manual October 2009 list_empty_careful 9 2.6.32-rc5 list_empty_careful tests whether a list is empty and not being modified int list_empty_careful const struct list_head * head head the list to test tests whether a list is empty _and_ checks that no other CPU might be in the process of modifying either member (next or prev) using list_empty_careful without synchronization can only be safe if the only activity that can happen to the list entry is list_del_init. Eg. it cannot be used if another CPU could re-list_add it. Kernel Hackers Manual October 2009 list_is_singular 9 2.6.32-rc5 list_is_singular tests whether a list has just one entry. int list_is_singular const struct list_head * head head the list to test. Kernel Hackers Manual October 2009 list_cut_position 9 2.6.32-rc5 list_cut_position cut a list into two void list_cut_position struct list_head * list struct list_head * head struct list_head * entry list a new list to add all removed entries head a list with entries entry an entry within head, could be the head itself and if so we won't cut the list This helper moves the initial part of head, up to and including entry, from head to list. You should pass on entry an element you know is on head. list should be an empty list or a list you do not care about losing its data. Kernel Hackers Manual October 2009 list_splice 9 2.6.32-rc5 list_splice join two lists, this is designed for stacks void list_splice const struct list_head * list struct list_head * head list the new list to add. head the place to add it in the first list. Kernel Hackers Manual October 2009 list_splice_tail 9 2.6.32-rc5 list_splice_tail join two lists, each list being a queue void list_splice_tail struct list_head * list struct list_head * head list the new list to add. head the place to add it in the first list. Kernel Hackers Manual October 2009 list_splice_init 9 2.6.32-rc5 list_splice_init join two lists and reinitialise the emptied list. void list_splice_init struct list_head * list struct list_head * head list the new list to add. head the place to add it in the first list. The list at list is reinitialised Kernel Hackers Manual October 2009 list_splice_tail_init 9 2.6.32-rc5 list_splice_tail_init join two lists and reinitialise the emptied list void list_splice_tail_init struct list_head * list struct list_head * head list the new list to add. head the place to add it in the first list. Each of the lists is a queue. The list at list is reinitialised Kernel Hackers Manual October 2009 list_entry 9 2.6.32-rc5 list_entry get the struct for this entry list_entry ptr type member ptr the struct list_head pointer. type the type of the struct this is embedded in. member the name of the list_struct within the struct. Kernel Hackers Manual October 2009 list_first_entry 9 2.6.32-rc5 list_first_entry get the first element from a list list_first_entry ptr type member 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. Note, that list is expected to be not empty. Kernel Hackers Manual October 2009 list_for_each 9 2.6.32-rc5 list_for_each iterate over a list list_for_each pos head pos the struct list_head to use as a loop cursor. head the head for your list. Kernel Hackers Manual October 2009 __list_for_each 9 2.6.32-rc5 __list_for_each iterate over a list __list_for_each pos head pos the struct list_head to use as a loop cursor. head the head for your list. This variant differs from list_for_each in that it's the simplest possible list iteration code, no prefetching is done. Use this for code that knows the list to be very short (empty or 1 entry) most of the time. Kernel Hackers Manual October 2009 list_for_each_prev 9 2.6.32-rc5 list_for_each_prev iterate over a list backwards list_for_each_prev pos head pos the struct list_head to use as a loop cursor. head the head for your list. Kernel Hackers Manual October 2009 list_for_each_safe 9 2.6.32-rc5 list_for_each_safe iterate over a list safe against removal of list entry list_for_each_safe pos n head pos the struct list_head to use as a loop cursor. n another struct list_head to use as temporary storage head the head for your list. Kernel Hackers Manual October 2009 list_for_each_prev_safe 9 2.6.32-rc5 list_for_each_prev_safe iterate over a list backwards safe against removal of list entry list_for_each_prev_safe pos n head 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. Kernel Hackers Manual October 2009 list_for_each_entry 9 2.6.32-rc5 list_for_each_entry iterate over list of given type list_for_each_entry pos head member 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. Kernel Hackers Manual October 2009 list_for_each_entry_reverse 9 2.6.32-rc5 list_for_each_entry_reverse iterate backwards over list of given type. list_for_each_entry_reverse pos head member 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. Kernel Hackers Manual October 2009 list_prepare_entry 9 2.6.32-rc5 list_prepare_entry prepare a pos entry for use in list_for_each_entry_continue list_prepare_entry pos head member 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. Prepares a pos entry for use as a start point in list_for_each_entry_continue. Kernel Hackers Manual October 2009 list_for_each_entry_continue 9 2.6.32-rc5 list_for_each_entry_continue continue iteration over list of given type list_for_each_entry_continue pos head member 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. Continue to iterate over list of given type, continuing after the current position. Kernel Hackers Manual October 2009 list_for_each_entry_continue_reverse 9 2.6.32-rc5 list_for_each_entry_continue_reverse iterate backwards from the given point list_for_each_entry_continue_reverse pos head member 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. Start to iterate over list of given type backwards, continuing after the current position. Kernel Hackers Manual October 2009 list_for_each_entry_from 9 2.6.32-rc5 list_for_each_entry_from iterate over list of given type from the current point list_for_each_entry_from pos head member 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. Iterate over list of given type, continuing from current position. Kernel Hackers Manual October 2009 list_for_each_entry_safe 9 2.6.32-rc5 list_for_each_entry_safe iterate over list of given type safe against removal of list entry list_for_each_entry_safe pos n head member 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. Kernel Hackers Manual October 2009 list_for_each_entry_safe_continue 9 2.6.32-rc5 list_for_each_entry_safe_continue list_for_each_entry_safe_continue pos n head member 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. Iterate over list of given type, continuing after current point, safe against removal of list entry. Kernel Hackers Manual October 2009 list_for_each_entry_safe_from 9 2.6.32-rc5 list_for_each_entry_safe_from list_for_each_entry_safe_from pos n head member 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. Iterate over list of given type from current point, safe against removal of list entry. Kernel Hackers Manual October 2009 list_for_each_entry_safe_reverse 9 2.6.32-rc5 list_for_each_entry_safe_reverse list_for_each_entry_safe_reverse pos n head member 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. Iterate backwards over list of given type, safe against removal of list entry. Kernel Hackers Manual October 2009 hlist_for_each_entry 9 2.6.32-rc5 hlist_for_each_entry iterate over list of given type hlist_for_each_entry tpos pos head member 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. Kernel Hackers Manual October 2009 hlist_for_each_entry_continue 9 2.6.32-rc5 hlist_for_each_entry_continue iterate over a hlist continuing after current point hlist_for_each_entry_continue tpos pos member 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. Kernel Hackers Manual October 2009 hlist_for_each_entry_from 9 2.6.32-rc5 hlist_for_each_entry_from iterate over a hlist continuing from current point hlist_for_each_entry_from tpos pos member 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. Kernel Hackers Manual October 2009 hlist_for_each_entry_safe 9 2.6.32-rc5 hlist_for_each_entry_safe iterate over list of given type safe against removal of list entry hlist_for_each_entry_safe tpos pos n head member 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. 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. Kernel Hackers Manual October 2009 simple_strtoll 9 2.6.32-rc5 simple_strtoll convert a string to a signed long long long long simple_strtoll const char * cp char ** endp unsigned int base 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 Kernel Hackers Manual October 2009 simple_strtoul 9 2.6.32-rc5 simple_strtoul convert a string to an unsigned long unsigned long simple_strtoul const char * cp char ** endp unsigned int base 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 Kernel Hackers Manual October 2009 simple_strtol 9 2.6.32-rc5 simple_strtol convert a string to a signed long long simple_strtol const char * cp char ** endp unsigned int base 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 Kernel Hackers Manual October 2009 simple_strtoull 9 2.6.32-rc5 simple_strtoull convert a string to an unsigned long long unsigned long long simple_strtoull const char * cp char ** endp unsigned int base 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 Kernel Hackers Manual October 2009 strict_strtoul 9 2.6.32-rc5 strict_strtoul convert a string to an unsigned long strictly int strict_strtoul const char * cp unsigned int base unsigned long * res cp The string to be converted base The number base to use res The converted result value strict_strtoul converts a string to an unsigned long only if the string is really an unsigned long string, any string containing any invalid char at the tail will be rejected and -EINVAL is returned, only a newline char at the tail is acceptible because people generally echo 1024 > /sys/module/e1000/parameters/copybreak echo will append a newline to the tail. It returns 0 if conversion is successful and *res is set to the converted value, otherwise it returns -EINVAL and *res is set to 0. simple_strtoul just ignores the successive invalid characters and return the converted value of prefix part of the string. Kernel Hackers Manual October 2009 strict_strtol 9 2.6.32-rc5 strict_strtol convert a string to a long strictly int strict_strtol const char * cp unsigned int base long * res cp The string to be converted base The number base to use res The converted result value strict_strtol is similiar to strict_strtoul, but it allows the first character of a string is '-'. It returns 0 if conversion is successful and *res is set to the converted value, otherwise it returns -EINVAL and *res is set to 0. Kernel Hackers Manual October 2009 strict_strtoull 9 2.6.32-rc5 strict_strtoull convert a string to an unsigned long long strictly int strict_strtoull const char * cp unsigned int base unsigned long long * res cp The string to be converted base The number base to use res The converted result value strict_strtoull converts a string to an unsigned long long only if the string is really an unsigned long long string, any string containing any invalid char at the tail will be rejected and -EINVAL is returned, only a newline char at the tail is acceptible because people generally echo 1024 > /sys/module/e1000/parameters/copybreak echo will append a newline to the tail of the string. It returns 0 if conversion is successful and *res is set to the converted value, otherwise it returns -EINVAL and *res is set to 0. simple_strtoull just ignores the successive invalid characters and return the converted value of prefix part of the string. Kernel Hackers Manual October 2009 strict_strtoll 9 2.6.32-rc5 strict_strtoll convert a string to a long long strictly int strict_strtoll const char * cp unsigned int base long long * res cp The string to be converted base The number base to use res The converted result value strict_strtoll is similiar to strict_strtoull, but it allows the first character of a string is '-'. It returns 0 if conversion is successful and *res is set to the converted value, otherwise it returns -EINVAL and *res is set to 0. Kernel Hackers Manual October 2009 vsnprintf 9 2.6.32-rc5 vsnprintf Format a string and place it in a buffer int vsnprintf char * buf size_t size const char * fmt va_list args 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 This function follows C99 vsnprintf, but has some extensions: pS output the name of a text symbol with offset ps output the name of a text symbol without offset pF output the name of a function pointer with its offset pf output the name of a function pointer without its offset pR output the address range in a struct resource n is ignored 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. Kernel Hackers Manual October 2009 vscnprintf 9 2.6.32-rc5 vscnprintf Format a string and place it in a buffer int vscnprintf char * buf size_t size const char * fmt va_list args 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 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. See the vsnprintf documentation for format string extensions over C99. Kernel Hackers Manual October 2009 snprintf 9 2.6.32-rc5 snprintf Format a string and place it in a buffer int snprintf char * buf size_t size const char * fmt ... 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 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. See the vsnprintf documentation for format string extensions over C99. Kernel Hackers Manual October 2009 scnprintf 9 2.6.32-rc5 scnprintf Format a string and place it in a buffer int scnprintf char * buf size_t size const char * fmt ... 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 The return value is the number of characters written into buf not including the trailing '\0'. If size is <= 0 the function returns 0. Kernel Hackers Manual October 2009 vsprintf 9 2.6.32-rc5 vsprintf Format a string and place it in a buffer int vsprintf char * buf const char * fmt va_list args buf The buffer to place the result into fmt The format string to use args Arguments for the format string 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. See the vsnprintf documentation for format string extensions over C99. Kernel Hackers Manual October 2009 sprintf 9 2.6.32-rc5 sprintf Format a string and place it in a buffer int sprintf char * buf const char * fmt ... buf The buffer to place the result into fmt The format string to use @...: Arguments for the format string ... variable arguments The function returns the number of characters written into buf. Use snprintf or scnprintf in order to avoid buffer overflows. See the vsnprintf documentation for format string extensions over C99. Kernel Hackers Manual October 2009 vbin_printf 9 2.6.32-rc5 vbin_printf Parse a format string and place args' binary value in a buffer int vbin_printf u32 * bin_buf size_t size const char * fmt va_list args bin_buf The buffer to place args' binary value size The size of the buffer(by words(32bits), not characters) fmt The format string to use args Arguments for the format string The format follows C99 vsnprintf, except n is ignored, and its argument is skiped. The return value is the number of words(32bits) which would be generated for the given input. If the return value is greater than size, the resulting bin_buf is NOT valid for bstr_printf. Kernel Hackers Manual October 2009 bstr_printf 9 2.6.32-rc5 bstr_printf Format a string from binary arguments and place it in a buffer int bstr_printf char * buf size_t size const char * fmt const u32 * bin_buf 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 bin_buf Binary arguments for the format string This function like C99 vsnprintf, but the difference is that vsnprintf gets arguments from stack, and bstr_printf gets arguments from bin_buf which is a binary buffer that generated by vbin_printf. The format follows C99 vsnprintf, but has some extensions: see vsnprintf comment for details. 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. Kernel Hackers Manual October 2009 bprintf 9 2.6.32-rc5 bprintf Parse a format string and place args' binary value in a buffer int bprintf u32 * bin_buf size_t size const char * fmt ... bin_buf The buffer to place args' binary value size The size of the buffer(by words(32bits), not characters) fmt The format string to use @...: Arguments for the format string ... variable arguments The function returns the number of words(u32) written into bin_buf. Kernel Hackers Manual October 2009 vsscanf 9 2.6.32-rc5 vsscanf Unformat a buffer into a list of arguments int vsscanf const char * buf const char * fmt va_list args buf input buffer fmt format of buffer args arguments Kernel Hackers Manual October 2009 sscanf 9 2.6.32-rc5 sscanf Unformat a buffer into a list of arguments int sscanf const char * buf const char * fmt ... buf input buffer fmt formatting of buffer @...: resulting arguments ... variable arguments Kernel Hackers Manual October 2009 strnicmp 9 2.6.32-rc5 strnicmp Case insensitive, length-limited string comparison int strnicmp const char * s1 const char * s2 size_t len s1 One string s2 The other string len the maximum number of characters to compare Kernel Hackers Manual October 2009 strcpy 9 2.6.32-rc5 strcpy Copy a NUL terminated string char * strcpy char * dest const char * src dest Where to copy the string to src Where to copy the string from Kernel Hackers Manual October 2009 strncpy 9 2.6.32-rc5 strncpy Copy a length-limited, NUL-terminated string char * strncpy char * dest const char * src size_t count dest Where to copy the string to src Where to copy the string from count The maximum number of bytes to copy 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. Kernel Hackers Manual October 2009 strlcpy 9 2.6.32-rc5 strlcpy Copy a NUL terminated string into a sized buffer size_t strlcpy char * dest const char * src size_t size dest Where to copy the string to src Where to copy the string from size size of destination buffer 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. Kernel Hackers Manual October 2009 strcat 9 2.6.32-rc5 strcat Append one NUL-terminated string to another char * strcat char * dest const char * src dest The string to be appended to src The string to append to it Kernel Hackers Manual October 2009 strncat 9 2.6.32-rc5 strncat Append a length-limited, NUL-terminated string to another char * strncat char * dest const char * src size_t count dest The string to be appended to src The string to append to it count The maximum numbers of bytes to copy Note that in contrast to strncpy, strncat ensures the result is terminated. Kernel Hackers Manual October 2009 strlcat 9 2.6.32-rc5 strlcat Append a length-limited, NUL-terminated string to another size_t strlcat char * dest const char * src size_t count dest The string to be appended to src The string to append to it count The size of the destination buffer. Kernel Hackers Manual October 2009 strcmp 9 2.6.32-rc5 strcmp Compare two strings int strcmp const char * cs const char * ct cs One string ct Another string Kernel Hackers Manual October 2009 strncmp 9 2.6.32-rc5 strncmp Compare two length-limited strings int strncmp const char * cs const char * ct size_t count cs One string ct Another string count The maximum number of bytes to compare Kernel Hackers Manual October 2009 strchr 9 2.6.32-rc5 strchr Find the first occurrence of a character in a string char * strchr const char * s int c s The string to be searched c The character to search for Kernel Hackers Manual October 2009 strrchr 9 2.6.32-rc5 strrchr Find the last occurrence of a character in a string char * strrchr const char * s int c s The string to be searched c The character to search for Kernel Hackers Manual October 2009 strnchr 9 2.6.32-rc5 strnchr Find a character in a length limited string char * strnchr const char * s size_t count int c s The string to be searched count The number of characters to be searched c The character to search for Kernel Hackers Manual October 2009 strstrip 9 2.6.32-rc5 strstrip Removes leading and trailing whitespace from s. char * strstrip char * s s The string to be stripped. 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. Kernel Hackers Manual October 2009 strlen 9 2.6.32-rc5 strlen Find the length of a string size_t strlen const char * s s The string to be sized Kernel Hackers Manual October 2009 strnlen 9 2.6.32-rc5 strnlen Find the length of a length-limited string size_t strnlen const char * s size_t count s The string to be sized count The maximum number of bytes to search Kernel Hackers Manual October 2009 strspn 9 2.6.32-rc5 strspn Calculate the length of the initial substring of s which only contain letters in accept size_t strspn const char * s const char * accept s The string to be searched accept The string to search for Kernel Hackers Manual October 2009 strcspn 9 2.6.32-rc5 strcspn Calculate the length of the initial substring of s which does not contain letters in reject size_t strcspn const char * s const char * reject s The string to be searched reject The string to avoid Kernel Hackers Manual October 2009 strpbrk 9 2.6.32-rc5 strpbrk Find the first occurrence of a set of characters char * strpbrk const char * cs const char * ct cs The string to be searched ct The characters to search for Kernel Hackers Manual October 2009 strsep 9 2.6.32-rc5 strsep Split a string into tokens char * strsep char ** s const char * ct s The string to be searched ct The characters to search for 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. ;) Kernel Hackers Manual October 2009 sysfs_streq 9 2.6.32-rc5 sysfs_streq return true if strings are equal, modulo trailing newline bool sysfs_streq const char * s1 const char * s2 s1 one string s2 another string This routine returns true iff two strings are equal, treating both NUL and newline-then-NUL as equivalent string terminations. It's geared for use with sysfs input strings, which generally terminate with newlines but are compared against values without newlines. Kernel Hackers Manual October 2009 memset 9 2.6.32-rc5 memset Fill a region of memory with the given value void * memset void * s int c size_t count s Pointer to the start of the area. c The byte to fill the area with count The size of the area. Do not use memset to access IO space, use memset_io instead. Kernel Hackers Manual October 2009 memcpy 9 2.6.32-rc5 memcpy Copy one area of memory to another void * memcpy void * dest const void * src size_t count dest Where to copy to src Where to copy from count The size of the area. You should not use this function to access IO space, use memcpy_toio or memcpy_fromio instead. Kernel Hackers Manual October 2009 memmove 9 2.6.32-rc5 memmove Copy one area of memory to another void * memmove void * dest const void * src size_t count dest Where to copy to src Where to copy from count The size of the area. Unlike memcpy, memmove copes with overlapping areas. Kernel Hackers Manual October 2009 memcmp 9 2.6.32-rc5 memcmp Compare two areas of memory int memcmp const void * cs const void * ct size_t count cs One area of memory ct Another area of memory count The size of the area. Kernel Hackers Manual October 2009 memscan 9 2.6.32-rc5 memscan Find a character in an area of memory. void * memscan void * addr int c size_t size addr The memory area c The byte to search for size The size of the area. returns the address of the first occurrence of c, or 1 byte past the area if c is not found Kernel Hackers Manual October 2009 strstr 9 2.6.32-rc5 strstr Find the first substring in a NUL terminated string char * strstr const char * s1 const char * s2 s1 The string to be searched s2 The string to search for Kernel Hackers Manual October 2009 memchr 9 2.6.32-rc5 memchr Find a character in an area of memory. void * memchr const void * s int c size_t n s The memory area c The byte to search for n The size of the area. returns the address of the first occurrence of c, or NULL if c is not found Kernel Hackers Manual October 2009 set_bit 9 2.6.32-rc5 set_bit Atomically set a bit in memory void set_bit unsigned int nr volatile unsigned long * addr nr the bit to set addr the address to start counting from This function is atomic and may not be reordered. See __set_bit if you do not require the atomic guarantees. 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. Kernel Hackers Manual October 2009 __set_bit 9 2.6.32-rc5 __set_bit Set a bit in memory void __set_bit int nr volatile unsigned long * addr nr the bit to set addr the address to start counting from 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. Kernel Hackers Manual October 2009 clear_bit 9 2.6.32-rc5 clear_bit Clears a bit in memory void clear_bit int nr volatile unsigned long * addr nr Bit to clear addr Address to start counting from 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. Kernel Hackers Manual October 2009 __change_bit 9 2.6.32-rc5 __change_bit Toggle a bit in memory void __change_bit int nr volatile unsigned long * addr nr the bit to change addr the address to start counting from 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. Kernel Hackers Manual October 2009 change_bit 9 2.6.32-rc5 change_bit Toggle a bit in memory void change_bit int nr volatile unsigned long * addr nr Bit to change addr Address to start counting from change_bit is atomic and may not be reordered. Note that nr may be almost arbitrarily large; this function is not restricted to acting on a single-word quantity. Kernel Hackers Manual October 2009 test_and_set_bit 9 2.6.32-rc5 test_and_set_bit Set a bit and return its old value int test_and_set_bit int nr volatile unsigned long * addr nr Bit to set addr Address to count from This operation is atomic and cannot be reordered. It also implies a memory barrier. Kernel Hackers Manual October 2009 test_and_set_bit_lock 9 2.6.32-rc5 test_and_set_bit_lock Set a bit and return its old value for lock int test_and_set_bit_lock int nr volatile unsigned long * addr nr Bit to set addr Address to count from This is the same as test_and_set_bit on x86. Kernel Hackers Manual October 2009 __test_and_set_bit 9 2.6.32-rc5 __test_and_set_bit Set a bit and return its old value int __test_and_set_bit int nr volatile unsigned long * addr nr Bit to set addr Address to count from 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. Kernel Hackers Manual October 2009 test_and_clear_bit 9 2.6.32-rc5 test_and_clear_bit Clear a bit and return its old value int test_and_clear_bit int nr volatile unsigned long * addr nr Bit to clear addr Address to count from This operation is atomic and cannot be reordered. It also implies a memory barrier. Kernel Hackers Manual October 2009 __test_and_clear_bit 9 2.6.32-rc5 __test_and_clear_bit Clear a bit and return its old value int __test_and_clear_bit int nr volatile unsigned long * addr nr Bit to clear addr Address to count from 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. Kernel Hackers Manual October 2009 test_and_change_bit 9 2.6.32-rc5 test_and_change_bit Change a bit and return its old value int test_and_change_bit int nr volatile unsigned long * addr nr Bit to change addr Address to count from This operation is atomic and cannot be reordered. It also implies a memory barrier. Kernel Hackers Manual October 2009 test_bit 9 2.6.32-rc5 test_bit Determine whether a bit is set int test_bit int nr const volatile unsigned long * addr nr bit number to test addr Address to start counting from Kernel Hackers Manual October 2009 __ffs 9 2.6.32-rc5 __ffs find first set bit in word unsigned long __ffs unsigned long word word The word to search Undefined if no bit exists, so code should check against 0 first. Kernel Hackers Manual October 2009 ffz 9 2.6.32-rc5 ffz find first zero bit in word unsigned long ffz unsigned long word word The word to search Undefined if no zero exists, so code should check against ~0UL first. Kernel Hackers Manual October 2009 ffs 9 2.6.32-rc5 ffs find first set bit in word int ffs int x x the word to search This is defined the same way as the libc and compiler builtin ffs routines, therefore differs in spirit from the other bitops. ffs(value) returns 0 if value is 0 or the position of the first set bit if value is nonzero. The first (least significant) bit is at position 1. Kernel Hackers Manual October 2009 fls 9 2.6.32-rc5 fls find last set bit in word int fls int x x the word to search This is defined in a similar way as the libc and compiler builtin ffs, but returns the position of the most significant set bit. fls(value) returns 0 if value is 0 or the position of the last set bit if value is nonzero. The last (most significant) bit is at position 32. The Linux kernel provides more basic utility functions. Kernel Hackers Manual October 2009 __bitmap_shift_right 9 2.6.32-rc5 __bitmap_shift_right logical right shift of the bits in a bitmap void __bitmap_shift_right unsigned long * dst const unsigned long * src int shift int bits dst destination bitmap src source bitmap shift shift by this many bits bits bitmap size, in bits 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. Kernel Hackers Manual October 2009 __bitmap_shift_left 9 2.6.32-rc5 __bitmap_shift_left logical left shift of the bits in a bitmap void __bitmap_shift_left unsigned long * dst const unsigned long * src int shift int bits dst destination bitmap src source bitmap shift shift by this many bits bits bitmap size, in bits 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. Kernel Hackers Manual October 2009 bitmap_scnprintf 9 2.6.32-rc5 bitmap_scnprintf convert bitmap to an ASCII hex string. int bitmap_scnprintf char * buf unsigned int buflen const unsigned long * maskp int nmaskbits 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 Exactly nmaskbits bits are displayed. Hex digits are grouped into comma-separated sets of eight digits per set. Kernel Hackers Manual October 2009 __bitmap_parse 9 2.6.32-rc5 __bitmap_parse convert an ASCII hex string into a bitmap. int __bitmap_parse const char * buf unsigned int buflen int is_user unsigned long * maskp int nmaskbits 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. 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. Kernel Hackers Manual October 2009 bitmap_parse_user 9 2.6.32-rc5 bitmap_parse_user int bitmap_parse_user const char __user * ubuf unsigned int ulen unsigned long * maskp int nmaskbits 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. 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. Kernel Hackers Manual October 2009 bitmap_scnlistprintf 9 2.6.32-rc5 bitmap_scnlistprintf convert bitmap to list format ASCII string int bitmap_scnlistprintf char * buf unsigned int buflen const unsigned long * maskp int nmaskbits 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 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. Kernel Hackers Manual October 2009 bitmap_parselist 9 2.6.32-rc5 bitmap_parselist convert list format ASCII string to bitmap int bitmap_parselist const char * bp unsigned long * maskp int nmaskbits bp read nul-terminated user string from this buffer maskp write resulting mask here nmaskbits number of bits in mask to be written 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. -EINVAL: second number in range smaller than first -EINVAL: invalid character in string -ERANGE: bit number specified too large for mask Kernel Hackers Manual October 2009 bitmap_remap 9 2.6.32-rc5 bitmap_remap Apply map defined by a pair of bitmaps to another bitmap void bitmap_remap unsigned long * dst const unsigned long * src const unsigned long * old const unsigned long * new int bits 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 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. Kernel Hackers Manual October 2009 bitmap_bitremap 9 2.6.32-rc5 bitmap_bitremap Apply map defined by a pair of bitmaps to a single bit int bitmap_bitremap int oldbit const unsigned long * old const unsigned long * new int bits 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 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. Kernel Hackers Manual October 2009 bitmap_onto 9 2.6.32-rc5 bitmap_onto translate one bitmap relative to another void bitmap_onto unsigned long * dst const unsigned long * orig const unsigned long * relmap int bits dst resulting translated bitmap orig original untranslated bitmap relmap bitmap relative to which translated bits number of bits in each of these bitmaps Set the n-th bit of dst iff there exists some m such that the n-th bit of relmap is set, the m-th bit of orig is set, and the n-th bit of relmap is also the m-th _set_ bit of relmap. (If you understood the previous sentence the first time your read it, you're overqualified for your current job.) In other words, orig is mapped onto (surjectively) dst, using the the map { <n, m> | the n-th bit of relmap is the m-th set bit of relmap }. Any set bits in orig above bit number W, where W is the weight of (number of set bits in) relmap are mapped nowhere. In particular, if for all bits m set in orig, m >= W, then dst will end up empty. In situations where the possibility of such an empty result is not desired, one way to avoid it is to use the bitmap_fold operator, below, to first fold the orig bitmap over itself so that all its set bits x are in the range 0 <= x < W. The bitmap_fold operator does this by setting the bit (m % W) in dst, for each bit (m) set in orig. Example [1] for bitmap_onto: Let's say relmap has bits 30-39 set, and orig has bits 1, 3, 5, 7, 9 and 11 set. Then on return from this routine, dst will have bits 31, 33, 35, 37 and 39 set. When bit 0 is set in orig, it means turn on the bit in dst corresponding to whatever is the first bit (if any) that is turned on in relmap. Since bit 0 was off in the above example, we leave off that bit (bit 30) in dst. When bit 1 is set in orig (as in the above example), it means turn on the bit in dst corresponding to whatever is the second bit that is turned on in relmap. The second bit in relmap that was turned on in the above example was bit 31, so we turned on bit 31 in dst. Similarly, we turned on bits 33, 35, 37 and 39 in dst, because they were the 4th, 6th, 8th and 10th set bits set in relmap, and the 4th, 6th, 8th and 10th bits of orig (i.e. bits 3, 5, 7 and 9) were also set. When bit 11 is set in orig, it means turn on the bit in dst corresponding to whatever is the twelth bit that is turned on in relmap. In the above example, there were only ten bits turned on in relmap (30..39), so that bit 11 was set in orig had no affect on dst. Example [2] for bitmap_fold + bitmap_onto: Let's say relmap has these ten bits set: 40 41 42 43 45 48 53 61 74 95 (for the curious, that's 40 plus the first ten terms of the Fibonacci sequence.) Further lets say we use the following code, invoking bitmap_fold then bitmap_onto, as suggested above to avoid the possitility of an empty dst result: unsigned long *tmp; // a temporary bitmap's bits bitmap_fold(tmp, orig, bitmap_weight(relmap, bits), bits); bitmap_onto(dst, tmp, relmap, bits); Then this table shows what various values of dst would be, for various orig's. I list the zero-based positions of each set bit. The tmp column shows the intermediate result, as computed by using bitmap_fold to fold the orig bitmap modulo ten (the weight of relmap). orig tmp dst 0 0 40 1 1 41 9 9 95 10 0 40 (*) 1 3 5 7 1 3 5 7 41 43 48 61 0 1 2 3 4 0 1 2 3 4 40 41 42 43 45 0 9 18 27 0 9 8 7 40 61 74 95 0 10 20 30 0 40 0 11 22 33 0 1 2 3 40 41 42 43 0 12 24 36 0 2 4 6 40 42 45 53 78 102 211 1 2 8 41 42 74 (*) (*) For these marked lines, if we hadn't first done bitmap_fold into tmp, then the dst result would have been empty. If either of orig or relmap is empty (no set bits), then dst will be returned empty. If (as explained above) the only set bits in orig are in positions m where m >= W, (where W is the weight of relmap) then dst will once again be returned empty. All bits in dst not set by the above rule are cleared. Kernel Hackers Manual October 2009 bitmap_fold 9 2.6.32-rc5 bitmap_fold fold larger bitmap into smaller, modulo specified size void bitmap_fold unsigned long * dst const unsigned long * orig int sz int bits dst resulting smaller bitmap orig original larger bitmap sz specified size bits number of bits in each of these bitmaps For each bit oldbit in orig, set bit oldbit mod sz in dst. Clear all other bits in dst. See further the comment and Example [2] for bitmap_onto for why and how to use this. Kernel Hackers Manual October 2009 bitmap_find_free_region 9 2.6.32-rc5 bitmap_find_free_region find a contiguous aligned mem region int bitmap_find_free_region unsigned long * bitmap int bits int order 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 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. Kernel Hackers Manual October 2009 bitmap_release_region 9 2.6.32-rc5 bitmap_release_region release allocated bitmap region void bitmap_release_region unsigned long * bitmap int pos int order 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 This is the complement to __bitmap_find_free_region and releases the found region (by clearing it in the bitmap). No return value. Kernel Hackers Manual October 2009 bitmap_allocate_region 9 2.6.32-rc5 bitmap_allocate_region allocate bitmap region int bitmap_allocate_region unsigned long * bitmap int pos int order 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 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). Kernel Hackers Manual October 2009 bitmap_copy_le 9 2.6.32-rc5 bitmap_copy_le copy a bitmap, putting the bits into little-endian order. void bitmap_copy_le void * dst const unsigned long * src int nbits dst destination buffer src bitmap to copy nbits number of bits in the bitmap Require nbits % BITS_PER_LONG == 0. Kernel Hackers Manual October 2009 bitmap_pos_to_ord 9 2.6.32-rc5 bitmap_pos_to_ord int bitmap_pos_to_ord const unsigned long * buf int pos int bits buf pointer to a bitmap pos a bit position in buf (0 <= pos < bits) bits number of valid bit positions in buf 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. Kernel Hackers Manual October 2009 bitmap_ord_to_pos 9 2.6.32-rc5 bitmap_ord_to_pos int bitmap_ord_to_pos const unsigned long * buf int ord int bits buf pointer to bitmap ord ordinal bit position (n-th set bit, n >= 0) bits number of valid bit positions in buf 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. Kernel Hackers Manual October 2009 get_option 9 2.6.32-rc5 get_option Parse integer from an option string int get_option char ** str int * pint str option string pint (output) integer value parsed from str Read an int from an option string; if available accept a subsequent comma as well. 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 Kernel Hackers Manual October 2009 get_options 9 2.6.32-rc5 get_options Parse a string into a list of integers char * get_options const char * str int nints int * ints str String to be parsed nints size of integer array ints integer array 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). Kernel Hackers Manual October 2009 memparse 9 2.6.32-rc5 memparse parse a string with mem suffixes into a number unsigned long long memparse const char * ptr char ** retptr ptr Where parse begins retptr (output) Optional pointer to next char after parse completes 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. Kernel Hackers Manual October 2009 crc7 9 2.6.32-rc5 crc7 update the CRC7 for the data buffer u8 crc7 u8 crc const u8 * buffer size_t len crc previous CRC7 value buffer data pointer len number of bytes in the buffer any Returns the updated CRC7 value. Kernel Hackers Manual October 2009 crc16 9 2.6.32-rc5 crc16 compute the CRC-16 for the data buffer u16 crc16 u16 crc u8 const * buffer size_t len crc previous CRC value buffer data pointer len number of bytes in the buffer Returns the updated CRC value. Kernel Hackers Manual October 2009 crc_itu_t 9 2.6.32-rc5 crc_itu_t Compute the CRC-ITU-T for the data buffer u16 crc_itu_t u16 crc const u8 * buffer size_t len crc previous CRC value buffer data pointer len number of bytes in the buffer Returns the updated CRC value Kernel Hackers Manual October 2009 crc32_le 9 2.6.32-rc5 crc32_le Calculate bitwise little-endian Ethernet AUTODIN II CRC32 u32 __pure crc32_le u32 crc unsigned char const * p size_t len 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 Kernel Hackers Manual October 2009 crc32_be 9 2.6.32-rc5 crc32_be Calculate bitwise big-endian Ethernet AUTODIN II CRC32 u32 __pure crc32_be u32 crc unsigned char const * p size_t len 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 Kernel Hackers Manual October 2009 crc_ccitt 9 2.6.32-rc5 crc_ccitt recompute the CRC for the data buffer u16 crc_ccitt u16 crc u8 const * buffer size_t len crc previous CRC value buffer data pointer len number of bytes in the buffer Kernel Hackers Manual October 2009 kcalloc 9 2.6.32-rc5 kcalloc allocate memory for an array. The memory is set to zero. void * kcalloc size_t n size_t size gfp_t flags n number of elements. size element size. flags the type of memory to allocate. 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. Kernel Hackers Manual October 2009 kmalloc_node 9 2.6.32-rc5 kmalloc_node allocate memory from a specific node void * kmalloc_node size_t size gfp_t flags int node size how many bytes of memory are required. flags the type of memory to allocate (see kcalloc). node node to allocate from. kmalloc for non-local nodes, used to allocate from a specific node if available. Equivalent to kmalloc in the non-NUMA single-node case. Kernel Hackers Manual October 2009 kzalloc 9 2.6.32-rc5 kzalloc allocate memory. The memory is set to zero. void * kzalloc size_t size gfp_t flags size how many bytes of memory are required. flags the type of memory to allocate (see kmalloc). Kernel Hackers Manual October 2009 kzalloc_node 9 2.6.32-rc5 kzalloc_node allocate zeroed memory from a particular memory node. void * kzalloc_node size_t size gfp_t flags int node size how many bytes of memory are required. flags the type of memory to allocate (see kmalloc). node memory node from which to allocate Kernel Hackers Manual October 2009 kmem_cache_create 9 2.6.32-rc5 kmem_cache_create Create a cache. struct kmem_cache * kmem_cache_create const char * name size_t size size_t align unsigned long flags void (*ctor) void * 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. 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. Note that kmem_cache_name is not guaranteed to return the same pointer, therefore applications must manage it themselves. 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. Kernel Hackers Manual October 2009 kmem_cache_shrink 9 2.6.32-rc5 kmem_cache_shrink Shrink a cache. int kmem_cache_shrink struct kmem_cache * cachep cachep The cache to shrink. Releases as many slabs as possible for a cache. To help debugging, a zero exit status indicates all slabs were released. Kernel Hackers Manual October 2009 kmem_cache_destroy 9 2.6.32-rc5 kmem_cache_destroy delete a cache void kmem_cache_destroy struct kmem_cache * cachep cachep the cache to destroy 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. Kernel Hackers Manual October 2009 kmem_cache_alloc 9 2.6.32-rc5 kmem_cache_alloc Allocate an object void * kmem_cache_alloc struct kmem_cache * cachep gfp_t flags cachep The cache to allocate from. flags See kmalloc. Allocate an object from this cache. The flags are only relevant if the cache has no available objects. Kernel Hackers Manual October 2009 kmem_cache_free 9 2.6.32-rc5 kmem_cache_free Deallocate an object void kmem_cache_free struct kmem_cache * cachep void * objp cachep The cache the allocation was from. objp The previously allocated object. Free an object which was previously allocated from this cache. Kernel Hackers Manual October 2009 kfree 9 2.6.32-rc5 kfree free previously allocated memory void kfree const void * objp objp pointer returned by kmalloc. If objp is NULL, no operation is performed. Don't free memory not originally allocated by kmalloc or you will run into trouble. Kernel Hackers Manual October 2009 ksize 9 2.6.32-rc5 ksize get the actual amount of memory allocated for a given object size_t ksize const void * objp objp Pointer to the object 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. Kernel Hackers Manual October 2009 __copy_to_user_inatomic 9 2.6.32-rc5 __copy_to_user_inatomic Copy a block of data into user space, with less checking. unsigned long __must_check __copy_to_user_inatomic void __user * to const void * from unsigned long n to Destination address, in user space. from Source address, in kernel space. n Number of bytes to copy. User context only. 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 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. Kernel Hackers Manual October 2009 __copy_to_user 9 2.6.32-rc5 __copy_to_user Copy a block of data into user space, with less checking. unsigned long __must_check __copy_to_user void __user * to const void * from unsigned long n to Destination address, in user space. from Source address, in kernel space. n Number of bytes to copy. User context only. This function may sleep. 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. Kernel Hackers Manual October 2009 __copy_from_user 9 2.6.32-rc5 __copy_from_user Copy a block of data from user space, with less checking. unsigned long __copy_from_user void * to const void __user * from unsigned long n to Destination address, in kernel space. from Source address, in user space. n Number of bytes to copy. User context only. This function may sleep. 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. Kernel Hackers Manual October 2009 strlen_user 9 2.6.32-rc5 strlen_user Get the size of a string in user space. strlen_user str str The string to measure. User context only. This function may sleep. 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. Kernel Hackers Manual October 2009 __strncpy_from_user 9 2.6.32-rc5 __strncpy_from_user Copy a NUL terminated string from userspace, with less checking. long __strncpy_from_user char * dst const char __user * src long count 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. 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. Kernel Hackers Manual October 2009 strncpy_from_user 9 2.6.32-rc5 strncpy_from_user Copy a NUL terminated string from userspace. long strncpy_from_user char * dst const char __user * src long count 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. 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. Kernel Hackers Manual October 2009 clear_user 9 2.6.32-rc5 clear_user Zero a block of memory in user space. unsigned long clear_user void __user * to unsigned long n to Destination address, in user space. n Number of bytes to zero. Zero a block of memory in user space. Returns number of bytes that could not be cleared. On success, this will be zero. Kernel Hackers Manual October 2009 __clear_user 9 2.6.32-rc5 __clear_user Zero a block of memory in user space, with less checking. unsigned long __clear_user void __user * to unsigned long n to Destination address, in user space. n Number of bytes to zero. 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. Kernel Hackers Manual October 2009 strnlen_user 9 2.6.32-rc5 strnlen_user Get the size of a string in user space. long strnlen_user const char __user * s long n s The string to measure. n The maximum valid length 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. Kernel Hackers Manual October 2009 copy_to_user 9 2.6.32-rc5 copy_to_user Copy a block of data into user space. unsigned long copy_to_user void __user * to const void * from unsigned long n to Destination address, in user space. from Source address, in kernel space. n Number of bytes to copy. User context only. This function may sleep. Copy data from kernel space to user space. Returns number of bytes that could not be copied. On success, this will be zero. Kernel Hackers Manual October 2009 copy_from_user 9 2.6.32-rc5 copy_from_user Copy a block of data from user space. unsigned long copy_from_user void * to const void __user * from unsigned long n to Destination address, in kernel space. from Source address, in user space. n Number of bytes to copy. User context only. This function may sleep. 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. Kernel Hackers Manual October 2009 read_cache_pages 9 2.6.32-rc5 read_cache_pages populate an address space with some pages & start reads against them int read_cache_pages struct address_space * mapping struct list_head * pages int (*filler) void *, struct page * void * data 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. Hides the details of the LRU cache etc from the filesystems. Kernel Hackers Manual October 2009 page_cache_sync_readahead 9 2.6.32-rc5 page_cache_sync_readahead generic file readahead void page_cache_sync_readahead struct address_space * mapping struct file_ra_state * ra struct file * filp pgoff_t offset unsigned long req_size 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 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. Kernel Hackers Manual October 2009 page_cache_async_readahead 9 2.6.32-rc5 page_cache_async_readahead file readahead for marked pages 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 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 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 more pages. Kernel Hackers Manual October 2009 filemap_flush 9 2.6.32-rc5 filemap_flush mostly a non-blocking flush int filemap_flush struct address_space * mapping mapping target address_space This is a mostly non-blocking flush. Not suitable for data-integrity purposes - I/O may not be started against all dirty pages. Kernel Hackers Manual October 2009 filemap_fdatawait_range 9 2.6.32-rc5 filemap_fdatawait_range wait for all under-writeback pages to complete in a given range int filemap_fdatawait_range struct address_space * mapping loff_t start loff_t end mapping address space structure to wait for start offset in bytes where the range starts end offset in bytes where the range ends (inclusive) Walk the list of under-writeback pages of the given address space in the given range and wait for all of them. This is just a simple wrapper so that callers don't have to convert offsets to page indexes themselves Kernel Hackers Manual October 2009 filemap_fdatawait 9 2.6.32-rc5 filemap_fdatawait wait for all under-writeback pages to complete int filemap_fdatawait struct address_space * mapping mapping address space structure to wait for Walk the list of under-writeback pages of the given address space and wait for all of them. Kernel Hackers Manual October 2009 filemap_write_and_wait_range 9 2.6.32-rc5 filemap_write_and_wait_range write out & wait on a file range int filemap_write_and_wait_range struct address_space * mapping loff_t lstart loff_t lend mapping the address_space for the pages lstart offset in bytes where the range starts lend offset in bytes where the range ends (inclusive) Write out and wait upon file offsets lstart->lend, inclusive. Note that `lend' is inclusive (describes the last byte to be written) so that this function can be used to write to the very end-of-file (end = -1). Kernel Hackers Manual October 2009 add_to_page_cache_locked 9 2.6.32-rc5 add_to_page_cache_locked add a locked page to the pagecache int add_to_page_cache_locked struct page * page struct address_space * mapping pgoff_t offset gfp_t gfp_mask page page to add mapping the page's address_space offset page index gfp_mask page allocation mode This function is used to add a page to the pagecache. It must be locked. This function does not add the page to the LRU. The caller must do that. Kernel Hackers Manual October 2009 add_page_wait_queue 9 2.6.32-rc5 add_page_wait_queue Add an arbitrary waiter to a page's wait queue void add_page_wait_queue struct page * page wait_queue_t * waiter page Page defining the wait queue of interest waiter Waiter to add to the queue Add an arbitrary waiter to the wait queue for the nominated page. Kernel Hackers Manual October 2009 unlock_page 9 2.6.32-rc5 unlock_page unlock a locked page void unlock_page struct page * page page the page 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 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). Kernel Hackers Manual October 2009 end_page_writeback 9 2.6.32-rc5 end_page_writeback end writeback against a page void end_page_writeback struct page * page page the page Kernel Hackers Manual October 2009 __lock_page 9 2.6.32-rc5 __lock_page get a lock on the page, assuming we need to sleep to get it void __lock_page struct page * page page the page to lock 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. Kernel Hackers Manual October 2009 find_get_page 9 2.6.32-rc5 find_get_page find and get a page reference struct page * find_get_page struct address_space * mapping pgoff_t offset mapping the address_space to search offset the page index Is there a pagecache struct page at the given (mapping, offset) tuple? If yes, increment its refcount and return it; if no, return NULL. Kernel Hackers Manual October 2009 find_lock_page 9 2.6.32-rc5 find_lock_page locate, pin and lock a pagecache page struct page * find_lock_page struct address_space * mapping pgoff_t offset mapping the address_space to search offset the page index 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. Kernel Hackers Manual October 2009 find_or_create_page 9 2.6.32-rc5 find_or_create_page locate or add a pagecache page struct page * find_or_create_page struct address_space * mapping pgoff_t index gfp_t gfp_mask mapping the page's address_space index the page's index into the mapping gfp_mask page allocation mode 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. Kernel Hackers Manual October 2009 find_get_pages_contig 9 2.6.32-rc5 find_get_pages_contig gang contiguous pagecache lookup unsigned find_get_pages_contig struct address_space * mapping pgoff_t index unsigned int nr_pages struct page ** pages 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 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. Kernel Hackers Manual October 2009 find_get_pages_tag 9 2.6.32-rc5 find_get_pages_tag find and return pages that match tag unsigned find_get_pages_tag struct address_space * mapping pgoff_t * index int tag unsigned int nr_pages struct page ** pages 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 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. Kernel Hackers Manual October 2009 grab_cache_page_nowait 9 2.6.32-rc5 grab_cache_page_nowait returns locked page at given index in given cache struct page * grab_cache_page_nowait struct address_space * mapping pgoff_t index mapping target address_space index the page index 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. Kernel Hackers Manual October 2009 generic_file_aio_read 9 2.6.32-rc5 generic_file_aio_read generic filesystem read routine ssize_t generic_file_aio_read struct kiocb * iocb const struct iovec * iov unsigned long nr_segs loff_t pos iocb kernel I/O control block iov io vector request nr_segs number of segments in the iovec pos current file position This is the read routine for all filesystems that can use the page cache directly. Kernel Hackers Manual October 2009 filemap_fault 9 2.6.32-rc5 filemap_fault read in file data for page fault handling int filemap_fault struct vm_area_struct * vma struct vm_fault * vmf vma vma in which the fault was taken vmf struct vm_fault containing details of the fault 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. Kernel Hackers Manual October 2009 read_cache_page_async 9 2.6.32-rc5 read_cache_page_async read into page cache, fill it if needed struct page * read_cache_page_async struct address_space * mapping pgoff_t index int (*filler) void *,struct page* void * data mapping the page's address_space index the page index filler function to perform the read data destination for read data Same as read_cache_page, but don't wait for page to become unlocked after submitting it to the filler. Read into the page cache. If a page already exists, and PageUptodate is not set, try to fill the page but don't wait for it to become unlocked. If the page does not get brought uptodate, return -EIO. Kernel Hackers Manual October 2009 read_cache_page 9 2.6.32-rc5 read_cache_page read into page cache, fill it if needed struct page * read_cache_page struct address_space * mapping pgoff_t index int (*filler) void *,struct page* void * data mapping the page's address_space index the page index filler function to perform the read data destination for read data 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. Kernel Hackers Manual October 2009 __generic_file_aio_write 9 2.6.32-rc5 __generic_file_aio_write write data to a file ssize_t __generic_file_aio_write struct kiocb * iocb const struct iovec * iov unsigned long nr_segs loff_t * ppos iocb IO state structure (file, offset, etc.) iov vector with data to write nr_segs number of segments in the vector ppos position where to write This function does all the work needed for actually writing data to a file. It does all basic checks, removes SUID from the file, updates modification times and calls proper subroutines depending on whether we do direct IO or a standard buffered write. It expects i_mutex to be grabbed unless we work on a block device or similar object which does not need locking at all. This function does *not* take care of syncing data in case of O_SYNC write. A caller has to handle it. This is mainly due to the fact that we want to avoid syncing under i_mutex. Kernel Hackers Manual October 2009 generic_file_aio_write 9 2.6.32-rc5 generic_file_aio_write write data to a file ssize_t generic_file_aio_write struct kiocb * iocb const struct iovec * iov unsigned long nr_segs loff_t pos iocb IO state structure iov vector with data to write nr_segs number of segments in the vector pos position in file where to write This is a wrapper around __generic_file_aio_write to be used by most filesystems. It takes care of syncing the file in case of O_SYNC file and acquires i_mutex as needed. Kernel Hackers Manual October 2009 try_to_release_page 9 2.6.32-rc5 try_to_release_page release old fs-specific metadata on a page int try_to_release_page struct page * page gfp_t gfp_mask page the page which the kernel is trying to free gfp_mask memory allocation flags (and I/O mode) 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. This may also be called if PG_fscache is set on a page, indicating that the page is known to the local caching routines. 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 & __GFP_FS). Kernel Hackers Manual October 2009 zap_vma_ptes 9 2.6.32-rc5 zap_vma_ptes remove ptes mapping the vma int zap_vma_ptes struct vm_area_struct * vma unsigned long address unsigned long size vma vm_area_struct holding ptes to be zapped address starting address of pages to zap size number of bytes to zap This function only unmaps ptes assigned to VM_PFNMAP vmas. The entire address range must be fully contained within the vma. Returns 0 if successful. Kernel Hackers Manual October 2009 get_user_pages 9 2.6.32-rc5 get_user_pages pin user pages in memory int get_user_pages struct task_struct * tsk struct mm_struct * mm unsigned long start int nr_pages int write int force struct page ** pages struct vm_area_struct ** vmas tsk task_struct of target task mm mm_struct of target mm start starting user address nr_pages number of pages from start to pin write whether pages will be written to by the caller force whether to force write access even if user mapping is readonly. This will result in the page being COWed even in MAP_SHARED mappings. You do not want this. pages array that receives pointers to the pages pinned. Should be at least nr_pages long. Or NULL, if caller only intends to ensure the pages are faulted in. vmas array of pointers to vmas corresponding to each page. Or NULL if the caller does not require them. Returns number of pages pinned. This may be fewer than the number requested. If nr_pages is 0 or negative, returns 0. If no pages were pinned, returns -errno. Each page returned must be released with a put_page call when it is finished with. vmas will only remain valid while mmap_sem is held. Must be called with mmap_sem held for read or write. get_user_pages walks a process's page tables and takes a reference to each struct page that each user address corresponds to at a given instant. That is, it takes the page that would be accessed if a user thread accesses the given user virtual address at that instant. This does not guarantee that the page exists in the user mappings when get_user_pages returns, and there may even be a completely different page there in some cases (eg. if mmapped pagecache has been invalidated and subsequently re faulted). However it does guarantee that the page won't be freed completely. And mostly callers simply care that the page contains data that was valid *at some point in time*. Typically, an IO or similar operation cannot guarantee anything stronger anyway because locks can't be held over the syscall boundary. If write=0, the page must not be written to. If the page is written to, set_page_dirty (or set_page_dirty_lock, as appropriate) must be called after the page is finished with, and before put_page is called. get_user_pages is typically used for fewer-copy IO operations, to get a handle on the memory by some means other than accesses via the user virtual addresses. The pages may be submitted for DMA to devices or accessed via their kernel linear mapping (via the kmap APIs). Care should be taken to use the correct cache flushing APIs. See also get_user_pages_fast, for performance critical applications. Kernel Hackers Manual October 2009 vm_insert_page 9 2.6.32-rc5 vm_insert_page insert single page into user vma int vm_insert_page struct vm_area_struct * vma unsigned long addr struct page * page vma user vma to map to addr target user address of this page page source kernel page 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. Kernel Hackers Manual October 2009 vm_insert_pfn 9 2.6.32-rc5 vm_insert_pfn insert single pfn into user vma int vm_insert_pfn struct vm_area_struct * vma unsigned long addr unsigned long pfn vma user vma to map to addr target user address of this page pfn source kernel pfn 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. vma cannot be a COW mapping. As this is called only for pages that do not currently exist, we do not need to flush old virtual caches or the TLB. Kernel Hackers Manual October 2009 remap_pfn_range 9 2.6.32-rc5 remap_pfn_range remap kernel memory to userspace int remap_pfn_range struct vm_area_struct * vma unsigned long addr unsigned long pfn unsigned long size pgprot_t prot 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 this is only safe if the mm semaphore is held when called. Kernel Hackers Manual October 2009 unmap_mapping_range 9 2.6.32-rc5 unmap_mapping_range unmap the portion of all mmaps in the specified address_space corresponding to the specified page range in the underlying file. void unmap_mapping_range struct address_space * mapping loff_t const holebegin loff_t const holelen int even_cows 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 truncate_pagecache, 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. Kernel Hackers Manual October 2009 follow_pfn 9 2.6.32-rc5 follow_pfn look up PFN at a user virtual address int follow_pfn struct vm_area_struct * vma unsigned long address unsigned long * pfn vma memory mapping address user virtual address pfn location to store found PFN Only IO mappings and raw PFN mappings are allowed. Returns zero and the pfn at pfn on success, -ve otherwise. Kernel Hackers Manual October 2009 vm_unmap_aliases 9 2.6.32-rc5 vm_unmap_aliases unmap outstanding lazy aliases in the vmap layer void vm_unmap_aliases void void no arguments The vmap/vmalloc layer lazily flushes kernel virtual mappings primarily to amortize TLB flushing overheads. What this means is that any page you have now, may, in a former life, have been mapped into kernel virtual address by the vmap layer and so there might be some CPUs with TLB entries still referencing that page (additional to the regular 1:1 kernel mapping). vm_unmap_aliases flushes all such lazy mappings. After it returns, we can be sure that none of the pages we have control over will have any aliases from the vmap layer. Kernel Hackers Manual October 2009 vm_unmap_ram 9 2.6.32-rc5 vm_unmap_ram unmap linear kernel address space set up by vm_map_ram void vm_unmap_ram const void * mem unsigned int count mem the pointer returned by vm_map_ram count the count passed to that vm_map_ram call (cannot unmap partial) Kernel Hackers Manual October 2009 vm_map_ram 9 2.6.32-rc5 vm_map_ram map pages linearly into kernel virtual address (vmalloc space) void * vm_map_ram struct page ** pages unsigned int count int node pgprot_t prot pages an array of pointers to the pages to be mapped count number of pages node prefer to allocate data structures on this node prot memory protection to use. PAGE_KERNEL for regular RAM a pointer to the address that has been mapped, or NULL on failure Kernel Hackers Manual October 2009 vfree 9 2.6.32-rc5 vfree release memory allocated by vmalloc void vfree const void * addr addr memory base address 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. Kernel Hackers Manual October 2009 vunmap 9 2.6.32-rc5 vunmap release virtual mapping obtained by vmap void vunmap const void * addr addr memory base address 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. Kernel Hackers Manual October 2009 vmap 9 2.6.32-rc5 vmap map an array of pages into virtually contiguous space void * vmap struct page ** pages unsigned int count unsigned long flags pgprot_t prot pages array of page pointers count number of pages to map flags vm_area->flags prot page protection for the mapping Maps count pages from pages into contiguous kernel virtual space. Kernel Hackers Manual October 2009 vmalloc 9 2.6.32-rc5 vmalloc allocate virtually contiguous memory void * vmalloc unsigned long size size allocation size 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. Kernel Hackers Manual October 2009 vmalloc_user 9 2.6.32-rc5 vmalloc_user allocate zeroed virtually contiguous memory for userspace void * vmalloc_user unsigned long size size allocation size The resulting memory area is zeroed so it can be mapped to userspace without leaking data. Kernel Hackers Manual October 2009 vmalloc_node 9 2.6.32-rc5 vmalloc_node allocate memory on a specific node void * vmalloc_node unsigned long size int node size allocation size node numa node 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. Kernel Hackers Manual October 2009 vmalloc_32 9 2.6.32-rc5 vmalloc_32 allocate virtually contiguous memory (32bit addressable) void * vmalloc_32 unsigned long size size allocation size Allocate enough 32bit PA addressable pages to cover size from the page level allocator and map them into contiguous kernel virtual space. Kernel Hackers Manual October 2009 vmalloc_32_user 9 2.6.32-rc5 vmalloc_32_user allocate zeroed virtually contiguous 32bit memory void * vmalloc_32_user unsigned long size size allocation size The resulting memory area is 32bit addressable and zeroed so it can be mapped to userspace without leaking data. Kernel Hackers Manual October 2009 remap_vmalloc_range 9 2.6.32-rc5 remap_vmalloc_range map vmalloc pages to userspace int remap_vmalloc_range struct vm_area_struct * vma void * addr unsigned long pgoff vma vma to cover (map full range of vma) addr vmalloc memory pgoff number of pages into addr before first page to map 0 for success, -Exxx on failure 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) Kernel Hackers Manual October 2009 alloc_vm_area 9 2.6.32-rc5 alloc_vm_area allocate a range of kernel address space struct vm_struct * alloc_vm_area size_t size size size of the area NULL on failure, vm_struct on success 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. Kernel Hackers Manual October 2009 find_next_best_node 9 2.6.32-rc5 find_next_best_node find the next node that should appear in a given node's fallback list int find_next_best_node int node nodemask_t * used_node_mask node node whose fallback list we're appending used_node_mask nodemask_t of already used nodes 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. Kernel Hackers Manual October 2009 free_bootmem_with_active_regions 9 2.6.32-rc5 free_bootmem_with_active_regions Call free_bootmem_node for each active range void free_bootmem_with_active_regions int nid unsigned long max_low_pfn 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 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. Kernel Hackers Manual October 2009 sparse_memory_present_with_active_regions 9 2.6.32-rc5 sparse_memory_present_with_active_regions Call memory_present for each active range void sparse_memory_present_with_active_regions int nid nid The node to call memory_present for. If MAX_NUMNODES, all nodes will be used. 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. Kernel Hackers Manual October 2009 get_pfn_range_for_nid 9 2.6.32-rc5 get_pfn_range_for_nid Return the start and end page frames for a node void __meminit get_pfn_range_for_nid unsigned int nid unsigned long * start_pfn unsigned long * end_pfn 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. 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. Kernel Hackers Manual October 2009 absent_pages_in_range 9 2.6.32-rc5 absent_pages_in_range Return number of page frames in holes within a range unsigned long absent_pages_in_range unsigned long start_pfn unsigned long end_pfn start_pfn The start PFN to start searching for holes end_pfn The end PFN to stop searching for holes It returns the number of pages frames in memory holes within a range. Kernel Hackers Manual October 2009 add_active_range 9 2.6.32-rc5 add_active_range Register a range of PFNs backed by physical memory void add_active_range unsigned int nid unsigned long start_pfn unsigned long end_pfn 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 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. Kernel Hackers Manual October 2009 remove_active_range 9 2.6.32-rc5 remove_active_range Shrink an existing registered range of PFNs void remove_active_range unsigned int nid unsigned long start_pfn unsigned long end_pfn nid The node id the range is on that should be shrunk start_pfn The new PFN of the range end_pfn The new PFN of the range i386 with NUMA use alloc_remap to store a node_mem_map on a local node. The map is kept near the end physical page range that has already been registered. This function allows an arch to shrink an existing registered range. Kernel Hackers Manual October 2009 remove_all_active_ranges 9 2.6.32-rc5 remove_all_active_ranges Remove all currently registered regions void remove_all_active_ranges void void no arguments 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. Kernel Hackers Manual October 2009 find_min_pfn_with_active_regions 9 2.6.32-rc5 find_min_pfn_with_active_regions Find the minimum PFN registered unsigned long find_min_pfn_with_active_regions void void no arguments It returns the minimum PFN based on information provided via add_active_range. Kernel Hackers Manual October 2009 free_area_init_nodes 9 2.6.32-rc5 free_area_init_nodes Initialise all pg_data_t and zone data void free_area_init_nodes unsigned long * max_zone_pfn max_zone_pfn an array of max PFNs for each zone 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. Kernel Hackers Manual October 2009 set_dma_reserve 9 2.6.32-rc5 set_dma_reserve set the specified number of pages reserved in the first zone void set_dma_reserve unsigned long new_dma_reserve new_dma_reserve The number of pages to mark reserved 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. Kernel Hackers Manual October 2009 setup_per_zone_wmarks 9 2.6.32-rc5 setup_per_zone_wmarks called when min_free_kbytes changes or when memory is hot-{added|removed} void setup_per_zone_wmarks void void no arguments Ensures that the watermark[min,low,high] values for each zone are set correctly with respect to min_free_kbytes. Kernel Hackers Manual October 2009 get_pageblock_flags_group 9 2.6.32-rc5 get_pageblock_flags_group Return the requested group of flags for the pageblock_nr_pages block of pages unsigned long get_pageblock_flags_group struct page * page int start_bitidx int end_bitidx 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 Kernel Hackers Manual October 2009 set_pageblock_flags_group 9 2.6.32-rc5 set_pageblock_flags_group Set the requested group of flags for a pageblock_nr_pages block of pages void set_pageblock_flags_group struct page * page unsigned long flags int start_bitidx int end_bitidx 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 Kernel Hackers Manual October 2009 mempool_create 9 2.6.32-rc5 mempool_create create a memory pool mempool_t * mempool_create int min_nr mempool_alloc_t * alloc_fn mempool_free_t * free_fn void * pool_data 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. 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. Kernel Hackers Manual October 2009 mempool_resize 9 2.6.32-rc5 mempool_resize resize an existing memory pool int mempool_resize mempool_t * pool int new_min_nr gfp_t gfp_mask 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. 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. Kernel Hackers Manual October 2009 mempool_destroy 9 2.6.32-rc5 mempool_destroy deallocate a memory pool void mempool_destroy mempool_t * pool pool pointer to the memory pool which was allocated via mempool_create. 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. Kernel Hackers Manual October 2009 mempool_alloc 9 2.6.32-rc5 mempool_alloc allocate an element from a specific memory pool void * mempool_alloc mempool_t * pool gfp_t gfp_mask pool pointer to the memory pool which was allocated via mempool_create. gfp_mask the usual allocation bitmask. 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.) Kernel Hackers Manual October 2009 mempool_free 9 2.6.32-rc5 mempool_free return an element to the pool. void mempool_free void * element mempool_t * pool element pool element pointer. pool pointer to the memory pool which was allocated via mempool_create. this function only sleeps if the free_fn function sleeps. Kernel Hackers Manual October 2009 dma_pool_create 9 2.6.32-rc5 dma_pool_create Creates a pool of consistent memory blocks, for dma. struct dma_pool * dma_pool_create const char * name struct device * dev size_t size size_t align size_t boundary 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 boundary returned blocks won't cross this power of two boundary !in_interrupt 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 boundary 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. Kernel Hackers Manual October 2009 dma_pool_destroy 9 2.6.32-rc5 dma_pool_destroy destroys a pool of dma memory blocks. void dma_pool_destroy struct dma_pool * pool pool dma pool that will be destroyed !in_interrupt Caller guarantees that no more memory from the pool is in use, and that nothing will try to use the pool after this call. Kernel Hackers Manual October 2009 dma_pool_alloc 9 2.6.32-rc5 dma_pool_alloc get a block of consistent memory void * dma_pool_alloc struct dma_pool * pool gfp_t mem_flags dma_addr_t * handle pool dma pool that will produce the block mem_flags GFP_* bitmask handle pointer to dma address of block 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. Kernel Hackers Manual October 2009 dma_pool_free 9 2.6.32-rc5 dma_pool_free put block back into dma pool void dma_pool_free struct dma_pool * pool void * vaddr dma_addr_t dma pool the dma pool holding the block vaddr virtual address of block dma dma address of block Caller promises neither device nor driver will again touch this block unless it is first re-allocated. Kernel Hackers Manual October 2009 dmam_pool_create 9 2.6.32-rc5 dmam_pool_create Managed dma_pool_create struct dma_pool * dmam_pool_create const char * name struct device * dev size_t size size_t align size_t allocation 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) Managed dma_pool_create. DMA pool created with this function is automatically destroyed on driver detach. Kernel Hackers Manual October 2009 dmam_pool_destroy 9 2.6.32-rc5 dmam_pool_destroy Managed dma_pool_destroy void dmam_pool_destroy struct dma_pool * pool pool dma pool that will be destroyed Managed dma_pool_destroy. Kernel Hackers Manual October 2009 balance_dirty_pages_ratelimited_nr 9 2.6.32-rc5 balance_dirty_pages_ratelimited_nr balance dirty memory state void balance_dirty_pages_ratelimited_nr struct address_space * mapping unsigned long nr_pages_dirtied mapping address_space which was dirtied nr_pages_dirtied number of pages which the caller has just dirtied 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. Kernel Hackers Manual October 2009 write_cache_pages 9 2.6.32-rc5 write_cache_pages walk the list of dirty pages of the given address space and write all of them. int write_cache_pages struct address_space * mapping struct writeback_control * wbc writepage_t writepage void * data 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 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. Kernel Hackers Manual October 2009 generic_writepages 9 2.6.32-rc5 generic_writepages walk the list of dirty pages of the given address space and writepage all of them. int generic_writepages struct address_space * mapping struct writeback_control * wbc mapping address space structure to write wbc subtract the number of written pages from *wbc->nr_to_write This is a library function, which implements the writepages address_space_operation. Kernel Hackers Manual October 2009 write_one_page 9 2.6.32-rc5 write_one_page write out a single page and optionally wait on I/O int write_one_page struct page * page int wait page the page to write wait if true, wait on writeout 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. Kernel Hackers Manual October 2009 truncate_inode_pages_range 9 2.6.32-rc5 truncate_inode_pages_range truncate range of pages specified by start & end byte offsets void truncate_inode_pages_range struct address_space * mapping loff_t lstart loff_t lend mapping mapping to truncate lstart offset from which to truncate lend offset to which to truncate 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. Kernel Hackers Manual October 2009 truncate_inode_pages 9 2.6.32-rc5 truncate_inode_pages truncate *all* the pages from an offset void truncate_inode_pages struct address_space * mapping loff_t lstart mapping mapping to truncate lstart offset from which to truncate Called under (and serialised by) inode->i_mutex. Kernel Hackers Manual October 2009 invalidate_mapping_pages 9 2.6.32-rc5 invalidate_mapping_pages Invalidate all the unlocked pages of one inode unsigned long invalidate_mapping_pages struct address_space * mapping pgoff_t start pgoff_t end 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) 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. Kernel Hackers Manual October 2009 invalidate_inode_pages2_range 9 2.6.32-rc5 invalidate_inode_pages2_range remove range of pages from an address_space int invalidate_inode_pages2_range struct address_space * mapping pgoff_t start pgoff_t end mapping the address_space start the page offset 'from' which to invalidate end the page offset 'to' which to invalidate (inclusive) Any pages which are found to be mapped into pagetables are unmapped prior to invalidation. Returns -EBUSY if any pages could not be invalidated. Kernel Hackers Manual October 2009 invalidate_inode_pages2 9 2.6.32-rc5 invalidate_inode_pages2 remove all pages from an address_space int invalidate_inode_pages2 struct address_space * mapping mapping the address_space 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 Hackers Manual October 2009 truncate_pagecache 9 2.6.32-rc5 truncate_pagecache unmap and remove pagecache that has been truncated void truncate_pagecache struct inode * inode loff_t old loff_t new inode inode old old file offset new new file offset inode's new i_size must already be written before truncate_pagecache is called. This function should typically be called before the filesystem releases resources associated with the freed range (eg. deallocates blocks). This way, pagecache will always stay logically coherent with on-disk format, and the filesystem would not have to deal with situations such as writepage being called for a page that has already had its underlying blocks deallocated. Kernel Hackers Manual October 2009 vmtruncate 9 2.6.32-rc5 vmtruncate unmap mappings freed by truncate syscall int vmtruncate struct inode * inode loff_t offset inode inode of the file used offset file offset to start truncating 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. Kernel Hackers Manual October 2009 ipc_init 9 2.6.32-rc5 ipc_init initialise IPC subsystem int ipc_init void void no arguments The various system5 IPC resources (semaphores, messages and shared memory) are initialised A callback routine is registered into the memory hotplug notifier since msgmni scales to lowmem this callback routine will be called upon successful memory add / remove to recompute msmgni. Kernel Hackers Manual October 2009 ipc_init_ids 9 2.6.32-rc5 ipc_init_ids initialise IPC identifiers void ipc_init_ids struct ipc_ids * ids ids Identifier set Set up the sequence range to use for the ipc identifier range (limited below IPCMNI) then initialise the ids idr. Kernel Hackers Manual October 2009 ipc_init_proc_interface 9 2.6.32-rc5 ipc_init_proc_interface Create a proc interface for sysipc types using a seq_file interface. void ipc_init_proc_interface const char * path const char * header int ids int (*show) struct seq_file *, void * path Path in procfs header Banner to be printed at the beginning of the file. ids ipc id table to iterate. show show routine. Kernel Hackers Manual October 2009 ipc_findkey 9 2.6.32-rc5 ipc_findkey find a key in an ipc identifier set struct kern_ipc_perm * ipc_findkey struct ipc_ids * ids key_t key ids Identifier set key The key to find 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 Kernel Hackers Manual October 2009 ipc_get_maxid 9 2.6.32-rc5 ipc_get_maxid get the last assigned id int ipc_get_maxid struct ipc_ids * ids ids IPC identifier set Called with ipc_ids.rw_mutex held. Kernel Hackers Manual October 2009 ipc_addid 9 2.6.32-rc5 ipc_addid add an IPC identifier int ipc_addid struct ipc_ids * ids struct kern_ipc_perm * new int size ids IPC identifier set new new IPC permission set size limit for the number of used ids 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. Kernel Hackers Manual October 2009 ipcget_new 9 2.6.32-rc5 ipcget_new create a new ipc object int ipcget_new struct ipc_namespace * ns struct ipc_ids * ids struct ipc_ops * ops struct ipc_params * params ns namespace ids IPC identifer set ops the actual creation routine to call params its parameters This routine is called by sys_msgget, sys_semget and sys_shmget when the key is IPC_PRIVATE. Kernel Hackers Manual October 2009 ipc_check_perms 9 2.6.32-rc5 ipc_check_perms check security and permissions for an IPC int ipc_check_perms struct kern_ipc_perm * ipcp struct ipc_ops * ops struct ipc_params * params ipcp ipc permission set ops the actual security routine to call params its parameters 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. Kernel Hackers Manual October 2009 ipcget_public 9 2.6.32-rc5 ipcget_public get an ipc object or create a new one int ipcget_public struct ipc_namespace * ns struct ipc_ids * ids struct ipc_ops * ops struct ipc_params * params ns namespace ids IPC identifer set ops the actual creation routine to call params its parameters 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. Kernel Hackers Manual October 2009 ipc_rmid 9 2.6.32-rc5 ipc_rmid remove an IPC identifier void ipc_rmid struct ipc_ids * ids struct kern_ipc_perm * ipcp ids IPC identifier set ipcp ipc perm structure containing the identifier to remove 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. Kernel Hackers Manual October 2009 ipc_alloc 9 2.6.32-rc5 ipc_alloc allocate ipc space void* ipc_alloc int size size size desired Allocate memory from the appropriate pools and return a pointer to it. NULL is returned if the allocation fails Kernel Hackers Manual October 2009 ipc_free 9 2.6.32-rc5 ipc_free free ipc space void ipc_free void * ptr int size ptr pointer returned by ipc_alloc size size of block Free a block created with ipc_alloc. The caller must know the size used in the allocation call. Kernel Hackers Manual October 2009 ipc_rcu_alloc 9 2.6.32-rc5 ipc_rcu_alloc allocate ipc and rcu space void* ipc_rcu_alloc int size size size desired Allocate memory for the rcu header structure + the object. Returns the pointer to the object. NULL is returned if the allocation fails. Kernel Hackers Manual October 2009 ipc_schedule_free 9 2.6.32-rc5 ipc_schedule_free free ipc + rcu space void ipc_schedule_free struct rcu_head * head head RCU callback structure for queued work Since RCU callback function is called in bh, we need to defer the vfree to schedule_work. Kernel Hackers Manual October 2009 ipc_immediate_free 9 2.6.32-rc5 ipc_immediate_free free ipc + rcu space void ipc_immediate_free struct rcu_head * head head RCU callback structure that contains pointer to be freed Free from the RCU callback context. Kernel Hackers Manual October 2009 ipcperms 9 2.6.32-rc5 ipcperms check IPC permissions int ipcperms struct kern_ipc_perm * ipcp short flag ipcp IPC permission set flag desired permission set. Check user, group, other permissions for access to ipc resources. return 0 if allowed Kernel Hackers Manual October 2009 kernel_to_ipc64_perm 9 2.6.32-rc5 kernel_to_ipc64_perm convert kernel ipc permissions to user void kernel_to_ipc64_perm struct kern_ipc_perm * in struct ipc64_perm * out in kernel permissions out new style IPC permissions Turn the kernel object in into a set of permissions descriptions for returning to userspace (out). Kernel Hackers Manual October 2009 ipc64_perm_to_ipc_perm 9 2.6.32-rc5 ipc64_perm_to_ipc_perm convert new ipc permissions to old void ipc64_perm_to_ipc_perm struct ipc64_perm * in struct ipc_perm * out in new style IPC permissions out old style IPC permissions Turn the new style permissions object in into a compatibility object and store it into the out pointer. Kernel Hackers Manual October 2009 ipc_lock 9 2.6.32-rc5 ipc_lock Lock an ipc structure without rw_mutex held struct kern_ipc_perm * ipc_lock struct ipc_ids * ids int id ids IPC identifier set id ipc id to look for Look for an id in the ipc ids idr and lock the associated ipc object. The ipc object is locked on exit. Kernel Hackers Manual October 2009 ipcget 9 2.6.32-rc5 ipcget Common sys_*get code int ipcget struct ipc_namespace * ns struct ipc_ids * ids struct ipc_ops * ops struct ipc_params * params ns namsepace ids IPC identifier set ops operations to be called on ipc object creation, permission checks and further checks params the parameters needed by the previous operations. Common routine called by sys_msgget, sys_semget and sys_shmget. Kernel Hackers Manual October 2009 ipc_update_perm 9 2.6.32-rc5 ipc_update_perm update the permissions of an IPC. void ipc_update_perm struct ipc64_perm * in struct kern_ipc_perm * out in the permission given as input. out the permission of the ipc to set. Kernel Hackers Manual October 2009 ipcctl_pre_down 9 2.6.32-rc5 ipcctl_pre_down retrieve an ipc and check permissions for some IPC_XXX cmd struct kern_ipc_perm * ipcctl_pre_down struct ipc_ids * ids int id int cmd struct ipc64_perm * perm int extra_perm ids the table of ids where to look for the ipc id the id of the ipc to retrieve cmd the cmd to check perm the permission to set extra_perm one extra permission parameter used by msq This function does some common audit and permissions check for some IPC_XXX cmd and is called from semctl_down, shmctl_down and msgctl_down. It must be called without any lock held and - retrieves the ipc with the given id in the given table. - performs some audit and permission check, depending on the given cmd - returns the ipc with both ipc and rw_mutex locks held in case of success or an err-code without any lock held otherwise. Kernel Hackers Manual October 2009 ipc_parse_version 9 2.6.32-rc5 ipc_parse_version IPC call version int ipc_parse_version int * cmd cmd pointer to command 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. Kernel Hackers Manual October 2009 __kfifo_reset 9 2.6.32-rc5 __kfifo_reset removes the entire FIFO contents, no locking version void __kfifo_reset struct kfifo * fifo fifo the fifo to be emptied. Kernel Hackers Manual October 2009 kfifo_reset 9 2.6.32-rc5 kfifo_reset removes the entire FIFO contents void kfifo_reset struct kfifo * fifo fifo the fifo to be emptied. Kernel Hackers Manual October 2009 kfifo_put 9 2.6.32-rc5 kfifo_put puts some data into the FIFO unsigned int kfifo_put struct kfifo * fifo const unsigned char * buffer unsigned int len fifo the fifo to be used. buffer the data to be added. len the length of the data to be added. 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. Kernel Hackers Manual October 2009 kfifo_get 9 2.6.32-rc5 kfifo_get gets some data from the FIFO unsigned int kfifo_get struct kfifo * fifo unsigned char * buffer unsigned int len fifo the fifo to be used. buffer where the data must be copied. len the size of the destination buffer. This function copies at most len bytes from the FIFO into the buffer and returns the number of copied bytes. Kernel Hackers Manual October 2009 __kfifo_len 9 2.6.32-rc5 __kfifo_len returns the number of bytes available in the FIFO, no locking version unsigned int __kfifo_len struct kfifo * fifo fifo the fifo to be used. Kernel Hackers Manual October 2009 kfifo_len 9 2.6.32-rc5 kfifo_len returns the number of bytes available in the FIFO unsigned int kfifo_len struct kfifo * fifo fifo the fifo to be used. Kernel Hackers Manual October 2009 kfifo_init 9 2.6.32-rc5 kfifo_init allocates a new FIFO using a preallocated buffer struct kfifo * kfifo_init unsigned char * buffer unsigned int size gfp_t gfp_mask spinlock_t * lock 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 Do NOT pass the kfifo to kfifo_free after use! Simply free the struct kfifo with kfree. Kernel Hackers Manual October 2009 kfifo_alloc 9 2.6.32-rc5 kfifo_alloc allocates a new FIFO and its internal buffer struct kfifo * kfifo_alloc unsigned int size gfp_t gfp_mask spinlock_t * lock 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 The size will be rounded-up to a power of 2. Kernel Hackers Manual October 2009 kfifo_free 9 2.6.32-rc5 kfifo_free frees the FIFO void kfifo_free struct kfifo * fifo fifo the fifo to be freed. Kernel Hackers Manual October 2009 __kfifo_put 9 2.6.32-rc5 __kfifo_put puts some data into the FIFO, no locking version unsigned int __kfifo_put struct kfifo * fifo const unsigned char * buffer unsigned int len fifo the fifo to be used. buffer the data to be added. len the length of the data to be added. 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. Kernel Hackers Manual October 2009 __kfifo_get 9 2.6.32-rc5 __kfifo_get gets some data from the FIFO, no locking version unsigned int __kfifo_get struct kfifo * fifo unsigned char * buffer unsigned int len fifo the fifo to be used. buffer where the data must be copied. len the size of the destination buffer. 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 is designed to provide an efficient mechanism for tools and facilities to relay large amounts of data from kernel space to user space. Kernel Hackers Manual October 2009 relay_buf_full 9 2.6.32-rc5 relay_buf_full boolean, is the channel buffer full? int relay_buf_full struct rchan_buf * buf buf channel buffer Returns 1 if the buffer is full, 0 otherwise. Kernel Hackers Manual October 2009 relay_reset 9 2.6.32-rc5 relay_reset reset the channel void relay_reset struct rchan * chan chan the channel 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. Kernel Hackers Manual October 2009 relay_open 9 2.6.32-rc5 relay_open create a new relay channel 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 base_filename base name of files to create, NULL for buffering only parent dentry of parent directory, NULL for root directory or buffer subbuf_size size of sub-buffers n_subbufs number of sub-buffers cb client callback functions private_data user-defined data 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. Kernel Hackers Manual October 2009 relay_switch_subbuf 9 2.6.32-rc5 relay_switch_subbuf switch to a new sub-buffer size_t relay_switch_subbuf struct rchan_buf * buf size_t length buf channel buffer length size of current event 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. Kernel Hackers Manual October 2009 relay_subbufs_consumed 9 2.6.32-rc5 relay_subbufs_consumed update the buffer's sub-buffers-consumed count void relay_subbufs_consumed struct rchan * chan unsigned int cpu size_t subbufs_consumed 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 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'. Kernel Hackers Manual October 2009 relay_close 9 2.6.32-rc5 relay_close close the channel void relay_close struct rchan * chan chan the channel Closes all channel buffers and frees the channel. Kernel Hackers Manual October 2009 relay_flush 9 2.6.32-rc5 relay_flush close the channel void relay_flush struct rchan * chan chan the channel Flushes all channel buffers, i.e. forces buffer switch. Kernel Hackers Manual October 2009 relay_mmap_buf 9 2.6.32-rc5 relay_mmap_buf mmap channel buffer to process address space int relay_mmap_buf struct rchan_buf * buf struct vm_area_struct * vma buf relay channel buffer vma vm_area_struct describing memory to be mapped Returns 0 if ok, negative on error Caller should already have grabbed mmap_sem. Kernel Hackers Manual October 2009 relay_alloc_buf 9 2.6.32-rc5 relay_alloc_buf allocate a channel buffer void * relay_alloc_buf struct rchan_buf * buf size_t * size buf the buffer struct size total size of the buffer Returns a pointer to the resulting buffer, NULL if unsuccessful. The passed in size will get page aligned, if it isn't already. Kernel Hackers Manual October 2009 relay_create_buf 9 2.6.32-rc5 relay_create_buf allocate and initialize a channel buffer struct rchan_buf * relay_create_buf struct rchan * chan chan the relay channel Returns channel buffer if successful, NULL otherwise. Kernel Hackers Manual October 2009 relay_destroy_channel 9 2.6.32-rc5 relay_destroy_channel free the channel struct void relay_destroy_channel struct kref * kref kref target kernel reference that contains the relay channel Should only be called from kref_put. Kernel Hackers Manual October 2009 relay_destroy_buf 9 2.6.32-rc5 relay_destroy_buf destroy an rchan_buf struct and associated buffer void relay_destroy_buf struct rchan_buf * buf buf the buffer struct Kernel Hackers Manual October 2009 relay_remove_buf 9 2.6.32-rc5 relay_remove_buf remove a channel buffer void relay_remove_buf struct kref * kref kref target kernel reference that contains the relay buffer Removes the file from the fileystem, which also frees the rchan_buf_struct and the channel buffer. Should only be called from kref_put. Kernel Hackers Manual October 2009 relay_buf_empty 9 2.6.32-rc5 relay_buf_empty boolean, is the channel buffer empty? int relay_buf_empty struct rchan_buf * buf buf channel buffer Returns 1 if the buffer is empty, 0 otherwise. Kernel Hackers Manual October 2009 wakeup_readers 9 2.6.32-rc5 wakeup_readers wake up readers waiting on a channel void wakeup_readers unsigned long data data contains the channel buffer This is the timer function used to defer reader waking. Kernel Hackers Manual October 2009 __relay_reset 9 2.6.32-rc5 __relay_reset reset a channel buffer void __relay_reset struct rchan_buf * buf unsigned int init buf the channel buffer init 1 if this is a first-time initialization See relay_reset for description of effect. Kernel Hackers Manual October 2009 relay_close_buf 9 2.6.32-rc5 relay_close_buf close a channel buffer void relay_close_buf struct rchan_buf * buf buf channel buffer 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. Kernel Hackers Manual October 2009 relay_hotcpu_callback 9 2.6.32-rc5 relay_hotcpu_callback CPU hotplug callback int __cpuinit relay_hotcpu_callback struct notifier_block * nb unsigned long action void * hcpu nb notifier block action hotplug action to take hcpu CPU number Returns the success/failure of the operation. (NOTIFY_OK, NOTIFY_BAD) Kernel Hackers Manual October 2009 relay_late_setup_files 9 2.6.32-rc5 relay_late_setup_files triggers file creation int relay_late_setup_files struct rchan * chan const char * base_filename struct dentry * parent chan channel to operate on base_filename base name of files to create parent dentry of parent directory, NULL for root directory Returns 0 if successful, non-zero otherwise. Use to setup files for a previously buffer-only channel. Useful to do early tracing in kernel, before VFS is up, for example. Kernel Hackers Manual October 2009 relay_file_open 9 2.6.32-rc5 relay_file_open open file op for relay files int relay_file_open struct inode * inode struct file * filp inode the inode filp the file Increments the channel buffer refcount. Kernel Hackers Manual October 2009 relay_file_mmap 9 2.6.32-rc5 relay_file_mmap mmap file op for relay files int relay_file_mmap struct file * filp struct vm_area_struct * vma filp the file vma the vma describing what to map Calls upon relay_mmap_buf to map the file into user space. Kernel Hackers Manual October 2009 relay_file_poll 9 2.6.32-rc5 relay_file_poll poll file op for relay files unsigned int relay_file_poll struct file * filp poll_table * wait filp the file wait poll table Poll implemention. Kernel Hackers Manual October 2009 relay_file_release 9 2.6.32-rc5 relay_file_release release file op for relay files int relay_file_release struct inode * inode struct file * filp inode the inode filp the file Decrements the channel refcount, as the filesystem is no longer using it. Kernel Hackers Manual October 2009 relay_file_read_subbuf_avail 9 2.6.32-rc5 relay_file_read_subbuf_avail return bytes available in sub-buffer size_t relay_file_read_subbuf_avail size_t read_pos struct rchan_buf * buf read_pos file read position buf relay channel buffer Kernel Hackers Manual October 2009 relay_file_read_start_pos 9 2.6.32-rc5 relay_file_read_start_pos find the first available byte to read size_t relay_file_read_start_pos size_t read_pos struct rchan_buf * buf read_pos file read position buf relay channel buffer If the read_pos is in the middle of padding, return the position of the first actually available byte, otherwise return the original value. Kernel Hackers Manual October 2009 relay_file_read_end_pos 9 2.6.32-rc5 relay_file_read_end_pos return the new read position size_t relay_file_read_end_pos struct rchan_buf * buf size_t read_pos size_t count buf relay channel buffer read_pos file read position count number of bytes to be read Kernel Hackers Manual October 2009 __request_module 9 2.6.32-rc5 __request_module try to load a kernel module int __request_module bool wait const char * fmt ... wait wait (or not) for the operation to complete fmt printf style format string for the name of the module @...: arguments as specified in the format string ... variable arguments 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. Kernel Hackers Manual October 2009 call_usermodehelper_setup 9 2.6.32-rc5 call_usermodehelper_setup prepare to call a usermode helper struct subprocess_info * call_usermodehelper_setup char * path char ** argv char ** envp gfp_t gfp_mask path path to usermode executable argv arg vector for process envp environment for process gfp_mask gfp mask for memory allocation 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. Kernel Hackers Manual October 2009 call_usermodehelper_setkeys 9 2.6.32-rc5 call_usermodehelper_setkeys set the session keys for usermode helper void call_usermodehelper_setkeys struct subprocess_info * info struct key * session_keyring info a subprocess_info returned by call_usermodehelper_setup session_keyring the session keyring for the process Kernel Hackers Manual October 2009 call_usermodehelper_setcleanup 9 2.6.32-rc5 call_usermodehelper_setcleanup set a cleanup function void call_usermodehelper_setcleanup struct subprocess_info * info void (*cleanup) char **argv, char **envp info a subprocess_info returned by call_usermodehelper_setup cleanup a cleanup function 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. Kernel Hackers Manual October 2009 call_usermodehelper_stdinpipe 9 2.6.32-rc5 call_usermodehelper_stdinpipe set up a pipe to be used for stdin int call_usermodehelper_stdinpipe struct subprocess_info * sub_info struct file ** filp sub_info a subprocess_info returned by call_usermodehelper_setup filp set to the write-end of a pipe This constructs a pipe, and sets the read end to be the stdin of the subprocess, and returns the write-end in *filp. Kernel Hackers Manual October 2009 call_usermodehelper_exec 9 2.6.32-rc5 call_usermodehelper_exec start a usermode application int call_usermodehelper_exec struct subprocess_info * sub_info enum umh_wait wait 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. 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). Kernel Hackers Manual October 2009 call_usermodehelper_pipe 9 2.6.32-rc5 call_usermodehelper_pipe call a usermode helper process with a pipe stdin int call_usermodehelper_pipe char * path char ** argv char ** envp struct file ** filp path path to usermode executable argv arg vector for process envp environment for process filp set to the write-end of a pipe 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. Refer to the file kernel/module.c for more information. Kernel Hackers Manual October 2009 synchronize_irq 9 2.6.32-rc5 synchronize_irq wait for pending IRQ handlers (on other CPUs) void synchronize_irq unsigned int irq irq interrupt number to wait for 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. Kernel Hackers Manual October 2009 disable_irq_nosync 9 2.6.32-rc5 disable_irq_nosync disable an irq without waiting void disable_irq_nosync unsigned int irq irq Interrupt to disable 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. Kernel Hackers Manual October 2009 disable_irq 9 2.6.32-rc5 disable_irq disable an irq and wait for completion void disable_irq unsigned int irq irq Interrupt to disable 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. Kernel Hackers Manual October 2009 enable_irq 9 2.6.32-rc5 enable_irq enable handling of an irq void enable_irq unsigned int irq irq Interrupt to enable 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 only when desc->chip->bus_lock and desc->chip->bus_sync_unlock are NULL ! Kernel Hackers Manual October 2009 set_irq_wake 9 2.6.32-rc5 set_irq_wake control irq power management wakeup int set_irq_wake unsigned int irq unsigned int on irq interrupt to control on enable/disable power management wakeup 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. Kernel Hackers Manual October 2009 setup_irq 9 2.6.32-rc5 setup_irq setup an interrupt int setup_irq unsigned int irq struct irqaction * act irq Interrupt line to setup act irqaction for the interrupt Used to statically setup interrupts in the early boot process. Kernel Hackers Manual October 2009 remove_irq 9 2.6.32-rc5 remove_irq free an interrupt void remove_irq unsigned int irq struct irqaction * act irq Interrupt line to free act irqaction for the interrupt Used to remove interrupts statically setup by the early boot process. Kernel Hackers Manual October 2009 free_irq 9 2.6.32-rc5 free_irq free an interrupt allocated with request_irq void free_irq unsigned int irq void * dev_id irq Interrupt line to free dev_id Device identity to free 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. Kernel Hackers Manual October 2009 request_threaded_irq 9 2.6.32-rc5 request_threaded_irq allocate an interrupt line int request_threaded_irq unsigned int irq irq_handler_t handler irq_handler_t thread_fn unsigned long irqflags const char * devname void * dev_id irq Interrupt line to allocate handler Function to be called when the IRQ occurs. Primary handler for threaded interrupts If NULL and thread_fn != NULL the default primary handler is installed thread_fn Function called from the irq handler thread If NULL, no irq thread is created irqflags Interrupt type flags devname An ascii name for the claiming device dev_id A cookie passed back to the handler function 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. If you want to set up a threaded irq handler for your device then you need to supply handler and thread_fn. handler ist still called in hard interrupt context and has to check whether the interrupt originates from the device. If yes it needs to disable the interrupt on the device and return IRQ_WAKE_THREAD which will wake up the handler thread and run thread_fn. This split handler design is necessary to support shared interrupts. 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. IRQF_SHARED Interrupt is shared IRQF_DISABLED Disable local interrupts while processing IRQF_SAMPLE_RANDOM The interrupt can be used for entropy IRQF_TRIGGER_* Specify active edge(s) or level Kernel Hackers Manual October 2009 request_dma 9 2.6.32-rc5 request_dma request and reserve a system DMA channel int request_dma unsigned int dmanr const char * device_id dmanr DMA channel number device_id reserving device ID string, used in /proc/dma Kernel Hackers Manual October 2009 free_dma 9 2.6.32-rc5 free_dma free a reserved system DMA channel void free_dma unsigned int dmanr dmanr DMA channel number Kernel Hackers Manual October 2009 insert_resource 9 2.6.32-rc5 insert_resource Inserts a resource in the resource tree int insert_resource struct resource * parent struct resource * new parent parent of the new resource new new resource to insert 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. Kernel Hackers Manual October 2009 insert_resource_expand_to_fit 9 2.6.32-rc5 insert_resource_expand_to_fit Insert a resource into the resource tree void insert_resource_expand_to_fit struct resource * root struct resource * new root root resource descriptor new new resource to insert Insert a resource into the resource tree, possibly expanding it in order to make it encompass any conflicting resources. Kernel Hackers Manual October 2009 resource_alignment 9 2.6.32-rc5 resource_alignment calculate resource's alignment resource_size_t resource_alignment struct resource * res res resource pointer Returns alignment on success, 0 (invalid alignment) on failure. Kernel Hackers Manual October 2009 request_resource 9 2.6.32-rc5 request_resource request and reserve an I/O or memory resource int request_resource struct resource * root struct resource * new root root resource descriptor new resource descriptor desired by caller Returns 0 for success, negative error code on error. Kernel Hackers Manual October 2009 release_resource 9 2.6.32-rc5 release_resource release a previously reserved resource int release_resource struct resource * old old resource pointer Kernel Hackers Manual October 2009 allocate_resource 9 2.6.32-rc5 allocate_resource allocate empty slot in the resource tree given range & alignment 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 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 Kernel Hackers Manual October 2009 adjust_resource 9 2.6.32-rc5 adjust_resource modify a resource's start and size int adjust_resource struct resource * res resource_size_t start resource_size_t size res resource to modify start new start value size new size 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. Kernel Hackers Manual October 2009 __request_region 9 2.6.32-rc5 __request_region create a new busy resource region struct resource * __request_region struct resource * parent resource_size_t start resource_size_t n const char * name int flags parent parent resource descriptor start resource start address n resource region size name reserving caller's ID string flags IO resource flags Kernel Hackers Manual October 2009 __check_region 9 2.6.32-rc5 __check_region check if a resource region is busy or free int __check_region struct resource * parent resource_size_t start resource_size_t n parent parent resource descriptor start resource start address n resource region size Returns 0 if the region is free at the moment it is checked, returns -EBUSY if the region is busy. 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. Kernel Hackers Manual October 2009 __release_region 9 2.6.32-rc5 __release_region release a previously reserved resource region void __release_region struct resource * parent resource_size_t start resource_size_t n parent parent resource descriptor start resource start address n resource region size The described resource region must match a current