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 July 2017 list_add 9 4.1.27 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 July 2017 list_add_tail 9 4.1.27 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 July 2017 __list_del_entry 9 4.1.27 __list_del_entry deletes entry from list. void __list_del_entry 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 July 2017 list_replace 9 4.1.27 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 July 2017 list_del_init 9 4.1.27 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 July 2017 list_move 9 4.1.27 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 July 2017 list_move_tail 9 4.1.27 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 July 2017 list_is_last 9 4.1.27 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 July 2017 list_empty 9 4.1.27 list_empty tests whether a list is empty int list_empty const struct list_head * head head the list to test. Kernel Hackers Manual July 2017 list_empty_careful 9 4.1.27 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 July 2017 list_rotate_left 9 4.1.27 list_rotate_left rotate the list to the left void list_rotate_left struct list_head * head head the head of the list Kernel Hackers Manual July 2017 list_is_singular 9 4.1.27 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 July 2017 list_cut_position 9 4.1.27 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 July 2017 list_splice 9 4.1.27 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 July 2017 list_splice_tail 9 4.1.27 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 July 2017 list_splice_init 9 4.1.27 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 July 2017 list_splice_tail_init 9 4.1.27 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 July 2017 list_entry 9 4.1.27 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_head within the struct. Kernel Hackers Manual July 2017 list_first_entry 9 4.1.27 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_head within the struct. Note, that list is expected to be not empty. Kernel Hackers Manual July 2017 list_last_entry 9 4.1.27 list_last_entry get the last element from a list list_last_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_head within the struct. Note, that list is expected to be not empty. Kernel Hackers Manual July 2017 list_first_entry_or_null 9 4.1.27 list_first_entry_or_null get the first element from a list list_first_entry_or_null 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_head within the struct. Note that if the list is empty, it returns NULL. Kernel Hackers Manual July 2017 list_next_entry 9 4.1.27 list_next_entry get the next element in list list_next_entry pos member pos the type * to cursor member the name of the list_head within the struct. Kernel Hackers Manual July 2017 list_prev_entry 9 4.1.27 list_prev_entry get the prev element in list list_prev_entry pos member pos the type * to cursor member the name of the list_head within the struct. Kernel Hackers Manual July 2017 list_for_each 9 4.1.27 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 July 2017 list_for_each_prev 9 4.1.27 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 July 2017 list_for_each_safe 9 4.1.27 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 July 2017 list_for_each_prev_safe 9 4.1.27 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 July 2017 list_for_each_entry 9 4.1.27 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_head within the struct. Kernel Hackers Manual July 2017 list_for_each_entry_reverse 9 4.1.27 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_head within the struct. Kernel Hackers Manual July 2017 list_prepare_entry 9 4.1.27 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_head within the struct. Prepares a pos entry for use as a start point in list_for_each_entry_continue. Kernel Hackers Manual July 2017 list_for_each_entry_continue 9 4.1.27 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_head within the struct. Continue to iterate over list of given type, continuing after the current position. Kernel Hackers Manual July 2017 list_for_each_entry_continue_reverse 9 4.1.27 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_head within the struct. Start to iterate over list of given type backwards, continuing after the current position. Kernel Hackers Manual July 2017 list_for_each_entry_from 9 4.1.27 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_head within the struct. Iterate over list of given type, continuing from current position. Kernel Hackers Manual July 2017 list_for_each_entry_safe 9 4.1.27 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_head within the struct. Kernel Hackers Manual July 2017 list_for_each_entry_safe_continue 9 4.1.27 list_for_each_entry_safe_continue continue list iteration safe against removal 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_head within the struct. Iterate over list of given type, continuing after current point, safe against removal of list entry. Kernel Hackers Manual July 2017 list_for_each_entry_safe_from 9 4.1.27 list_for_each_entry_safe_from iterate over list from current point safe against removal 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_head within the struct. Iterate over list of given type from current point, safe against removal of list entry. Kernel Hackers Manual July 2017 list_for_each_entry_safe_reverse 9 4.1.27 list_for_each_entry_safe_reverse iterate backwards over list safe against removal 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_head within the struct. Iterate backwards over list of given type, safe against removal of list entry. Kernel Hackers Manual July 2017 list_safe_reset_next 9 4.1.27 list_safe_reset_next reset a stale list_for_each_entry_safe loop list_safe_reset_next pos n member pos the loop cursor used in the list_for_each_entry_safe loop n temporary storage used in list_for_each_entry_safe member the name of the list_head within the struct. list_safe_reset_next is not safe to use in general if the list may be modified concurrently (eg. the lock is dropped in the loop body). An exception to this is if the cursor element (pos) is pinned in the list, and list_safe_reset_next is called after re-taking the lock and before completing the current iteration of the loop body. Kernel Hackers Manual July 2017 hlist_for_each_entry 9 4.1.27 hlist_for_each_entry iterate over list of given type hlist_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 hlist_node within the struct. Kernel Hackers Manual July 2017 hlist_for_each_entry_continue 9 4.1.27 hlist_for_each_entry_continue iterate over a hlist continuing after current point hlist_for_each_entry_continue pos member pos the type * to use as a loop cursor. member the name of the hlist_node within the struct. Kernel Hackers Manual July 2017 hlist_for_each_entry_from 9 4.1.27 hlist_for_each_entry_from iterate over a hlist continuing from current point hlist_for_each_entry_from pos member pos the type * to use as a loop cursor. member the name of the hlist_node within the struct. Kernel Hackers Manual July 2017 hlist_for_each_entry_safe 9 4.1.27 hlist_for_each_entry_safe iterate over list of given type safe against removal of list entry hlist_for_each_entry_safe pos n head member pos the type * 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 July 2017 simple_strtoull 9 4.1.27 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 This function is obsolete. Please use kstrtoull instead. Kernel Hackers Manual July 2017 simple_strtoul 9 4.1.27 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 This function is obsolete. Please use kstrtoul instead. Kernel Hackers Manual July 2017 simple_strtol 9 4.1.27 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 This function is obsolete. Please use kstrtol instead. Kernel Hackers Manual July 2017 simple_strtoll 9 4.1.27 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 This function is obsolete. Please use kstrtoll instead. Kernel Hackers Manual July 2017 vsnprintf 9 4.1.27 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 pB output the name of a backtrace symbol with its offset pR output the address range in a struct resource with decoded flags pr output the address range in a struct resource with raw flags pb output the bitmap with field width as the number of bits pbl output the bitmap as range list with field width as the number of bits pM output a 6-byte MAC address with colons pMR output a 6-byte MAC address with colons in reversed order pMF output a 6-byte MAC address with dashes pm output a 6-byte MAC address without colons pmR output a 6-byte MAC address without colons in reversed order pI4 print an IPv4 address without leading zeros pi4 print an IPv4 address with leading zeros pI6 print an IPv6 address with colons pi6 print an IPv6 address without colons pI6c print an IPv6 address as specified by RFC 5952 pIS depending on sa_family of 'struct sockaddr *' print IPv4/IPv6 address piS depending on sa_family of 'struct sockaddr *' print IPv4/IPv6 address pU[bBlL] print a UUID/GUID in big or little endian using lower or upper case. %*pE[achnops] print an escaped buffer %*ph[CDN] a variable-length hex string with a separator (supports up to 64 bytes of the input) pC output the name (Common Clock Framework) or address (legacy clock framework) of a clock pCn output the name (Common Clock Framework) or address (legacy clock framework) of a clock pCr output the current rate of a clock n is ignored ** Please update Documentation/printk-formats.txt when making changes ** 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. If you're not already dealing with a va_list consider using snprintf. Kernel Hackers Manual July 2017 vscnprintf 9 4.1.27 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. If you're not already dealing with a va_list consider using scnprintf. See the vsnprintf documentation for format string extensions over C99. Kernel Hackers Manual July 2017 snprintf 9 4.1.27 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 July 2017 scnprintf 9 4.1.27 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 July 2017 vsprintf 9 4.1.27 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. If you're not already dealing with a va_list consider using sprintf. See the vsnprintf documentation for format string extensions over C99. Kernel Hackers Manual July 2017 sprintf 9 4.1.27 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 July 2017 vbin_printf 9 4.1.27 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 skipped. 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 July 2017 bstr_printf 9 4.1.27 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 July 2017 bprintf 9 4.1.27 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 July 2017 vsscanf 9 4.1.27 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 July 2017 sscanf 9 4.1.27 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 July 2017 kstrtol 9 4.1.27 kstrtol convert a string to a long int kstrtol const char * s unsigned int base long * res s The start of the string. The string must be null-terminated, and may also include a single newline before its terminating null. The first character may also be a plus sign or a minus sign. base The number base to use. The maximum supported base is 16. If base is given as 0, then the base of the string is automatically detected with the conventional semantics - If it begins with 0x the number will be parsed as a hexadecimal (case insensitive), if it otherwise begins with 0, it will be parsed as an octal number. Otherwise it will be parsed as a decimal. res Where to write the result of the conversion on success. Returns 0 on success, -ERANGE on overflow and -EINVAL on parsing error. Used as a replacement for the obsolete simple_strtoull. Return code must be checked. Kernel Hackers Manual July 2017 kstrtoul 9 4.1.27 kstrtoul convert a string to an unsigned long int kstrtoul const char * s unsigned int base unsigned long * res s The start of the string. The string must be null-terminated, and may also include a single newline before its terminating null. The first character may also be a plus sign, but not a minus sign. base The number base to use. The maximum supported base is 16. If base is given as 0, then the base of the string is automatically detected with the conventional semantics - If it begins with 0x the number will be parsed as a hexadecimal (case insensitive), if it otherwise begins with 0, it will be parsed as an octal number. Otherwise it will be parsed as a decimal. res Where to write the result of the conversion on success. Returns 0 on success, -ERANGE on overflow and -EINVAL on parsing error. Used as a replacement for the obsolete simple_strtoull. Return code must be checked. Kernel Hackers Manual July 2017 kstrtoull 9 4.1.27 kstrtoull convert a string to an unsigned long long int kstrtoull const char * s unsigned int base unsigned long long * res s The start of the string. The string must be null-terminated, and may also include a single newline before its terminating null. The first character may also be a plus sign, but not a minus sign. base The number base to use. The maximum supported base is 16. If base is given as 0, then the base of the string is automatically detected with the conventional semantics - If it begins with 0x the number will be parsed as a hexadecimal (case insensitive), if it otherwise begins with 0, it will be parsed as an octal number. Otherwise it will be parsed as a decimal. res Where to write the result of the conversion on success. Returns 0 on success, -ERANGE on overflow and -EINVAL on parsing error. Used as a replacement for the obsolete simple_strtoull. Return code must be checked. Kernel Hackers Manual July 2017 kstrtoll 9 4.1.27 kstrtoll convert a string to a long long int kstrtoll const char * s unsigned int base long long * res s The start of the string. The string must be null-terminated, and may also include a single newline before its terminating null. The first character may also be a plus sign or a minus sign. base The number base to use. The maximum supported base is 16. If base is given as 0, then the base of the string is automatically detected with the conventional semantics - If it begins with 0x the number will be parsed as a hexadecimal (case insensitive), if it otherwise begins with 0, it will be parsed as an octal number. Otherwise it will be parsed as a decimal. res Where to write the result of the conversion on success. Returns 0 on success, -ERANGE on overflow and -EINVAL on parsing error. Used as a replacement for the obsolete simple_strtoull. Return code must be checked. Kernel Hackers Manual July 2017 kstrtouint 9 4.1.27 kstrtouint convert a string to an unsigned int int kstrtouint const char * s unsigned int base unsigned int * res s The start of the string. The string must be null-terminated, and may also include a single newline before its terminating null. The first character may also be a plus sign, but not a minus sign. base The number base to use. The maximum supported base is 16. If base is given as 0, then the base of the string is automatically detected with the conventional semantics - If it begins with 0x the number will be parsed as a hexadecimal (case insensitive), if it otherwise begins with 0, it will be parsed as an octal number. Otherwise it will be parsed as a decimal. res Where to write the result of the conversion on success. Returns 0 on success, -ERANGE on overflow and -EINVAL on parsing error. Used as a replacement for the obsolete simple_strtoull. Return code must be checked. Kernel Hackers Manual July 2017 kstrtoint 9 4.1.27 kstrtoint convert a string to an int int kstrtoint const char * s unsigned int base int * res s The start of the string. The string must be null-terminated, and may also include a single newline before its terminating null. The first character may also be a plus sign or a minus sign. base The number base to use. The maximum supported base is 16. If base is given as 0, then the base of the string is automatically detected with the conventional semantics - If it begins with 0x the number will be parsed as a hexadecimal (case insensitive), if it otherwise begins with 0, it will be parsed as an octal number. Otherwise it will be parsed as a decimal. res Where to write the result of the conversion on success. Returns 0 on success, -ERANGE on overflow and -EINVAL on parsing error. Used as a replacement for the obsolete simple_strtoull. Return code must be checked. Kernel Hackers Manual July 2017 strncasecmp 9 4.1.27 strncasecmp Case insensitive, length-limited string comparison int strncasecmp 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 July 2017 strcpy 9 4.1.27 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 July 2017 strncpy 9 4.1.27 strncpy Copy a length-limited, C-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 July 2017 strlcpy 9 4.1.27 strlcpy Copy a C-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 July 2017 strcat 9 4.1.27 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 July 2017 strncat 9 4.1.27 strncat Append a length-limited, C-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 July 2017 strlcat 9 4.1.27 strlcat Append a length-limited, C-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 July 2017 strcmp 9 4.1.27 strcmp Compare two strings int strcmp const char * cs const char * ct cs One string ct Another string Kernel Hackers Manual July 2017 strncmp 9 4.1.27 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 July 2017 strchr 9 4.1.27 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 July 2017 strchrnul 9 4.1.27 strchrnul Find and return a character in a string, or end of string char * strchrnul const char * s int c s The string to be searched c The character to search for Returns pointer to first occurrence of 'c' in s. If c is not found, then return a pointer to the null byte at the end of s. Kernel Hackers Manual July 2017 strrchr 9 4.1.27 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 July 2017 strnchr 9 4.1.27 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 July 2017 skip_spaces 9 4.1.27 skip_spaces Removes leading whitespace from str. char * skip_spaces const char * str str The string to be stripped. Returns a pointer to the first non-whitespace character in str. Kernel Hackers Manual July 2017 strim 9 4.1.27 strim Removes leading and trailing whitespace from s. char * strim 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 July 2017 strlen 9 4.1.27 strlen Find the length of a string size_t strlen const char * s s The string to be sized Kernel Hackers Manual July 2017 strnlen 9 4.1.27 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 July 2017 strspn 9 4.1.27 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 July 2017 strcspn 9 4.1.27 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 July 2017 strpbrk 9 4.1.27 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 July 2017 strsep 9 4.1.27 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 July 2017 sysfs_streq 9 4.1.27 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 July 2017 strtobool 9 4.1.27 strtobool convert common user inputs into boolean values int strtobool const char * s bool * res s input string res result This routine returns 0 iff the first character is one of 'Yy1Nn0'. Otherwise it will return -EINVAL. Value pointed to by res is updated upon finding a match. Kernel Hackers Manual July 2017 memset 9 4.1.27 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 July 2017 memzero_explicit 9 4.1.27 memzero_explicit Fill a region of memory (e.g. sensitive keying data) with 0s. void memzero_explicit void * s size_t count s Pointer to the start of the area. count The size of the area. usually using memset is just fine (!), but in cases where clearing out _local_ data at the end of a scope is necessary, memzero_explicit should be used instead in order to prevent the compiler from optimising away zeroing. memzero_explicit doesn't need an arch-specific version as it just invokes the one of memset implicitly. Kernel Hackers Manual July 2017 memcpy 9 4.1.27 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 July 2017 memmove 9 4.1.27 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 July 2017 memcmp 9 4.1.27 memcmp Compare two areas of memory __visible 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 July 2017 memscan 9 4.1.27 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 July 2017 strstr 9 4.1.27 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 July 2017 strnstr 9 4.1.27 strnstr Find the first substring in a length-limited string char * strnstr const char * s1 const char * s2 size_t len s1 The string to be searched s2 The string to search for len the maximum number of characters to search Kernel Hackers Manual July 2017 memchr 9 4.1.27 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 July 2017 memchr_inv 9 4.1.27 memchr_inv Find an unmatching character in an area of memory. void * memchr_inv const void * start int c size_t bytes start The memory area c Find a character other than c bytes The size of the area. returns the address of the first character other than c, or NULL if the whole buffer contains just c. Kernel Hackers Manual July 2017 set_bit 9 4.1.27 set_bit Atomically set a bit in memory void set_bit long 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 July 2017 __set_bit 9 4.1.27 __set_bit Set a bit in memory void __set_bit long 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 July 2017 clear_bit 9 4.1.27 clear_bit Clears a bit in memory void clear_bit long 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_atomic and/or smp_mb__after_atomic in order to ensure changes are visible on other processors. Kernel Hackers Manual July 2017 __change_bit 9 4.1.27 __change_bit Toggle a bit in memory void __change_bit long 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 July 2017 change_bit 9 4.1.27 change_bit Toggle a bit in memory void change_bit long 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 July 2017 test_and_set_bit 9 4.1.27 test_and_set_bit Set a bit and return its old value int test_and_set_bit long 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 July 2017 test_and_set_bit_lock 9 4.1.27 test_and_set_bit_lock Set a bit and return its old value for lock int test_and_set_bit_lock long 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 July 2017 __test_and_set_bit 9 4.1.27 __test_and_set_bit Set a bit and return its old value int __test_and_set_bit long 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 July 2017 test_and_clear_bit 9 4.1.27 test_and_clear_bit Clear a bit and return its old value int test_and_clear_bit long 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 July 2017 __test_and_clear_bit 9 4.1.27 __test_and_clear_bit Clear a bit and return its old value int __test_and_clear_bit long 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. the operation is performed atomically with respect to the local CPU, but not other CPUs. Portable code should not rely on this behaviour. KVM relies on this behaviour on x86 for modifying memory that is also don't change this without also updating arch/x86/kernel/kvm.c Kernel Hackers Manual July 2017 test_and_change_bit 9 4.1.27 test_and_change_bit Change a bit and return its old value int test_and_change_bit long 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 July 2017 test_bit 9 4.1.27 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 July 2017 __ffs 9 4.1.27 __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 July 2017 ffz 9 4.1.27 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 July 2017 ffs 9 4.1.27 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 July 2017 fls 9 4.1.27 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. Kernel Hackers Manual July 2017 fls64 9 4.1.27 fls64 find last set bit in a 64-bit word int fls64 __u64 x x the word to search This is defined in a similar way as the libc and compiler builtin ffsll, but returns the position of the most significant set bit. fls64(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 64. The Linux kernel provides more basic utility functions. Kernel Hackers Manual July 2017 __bitmap_shift_right 9 4.1.27 __bitmap_shift_right logical right shift of the bits in a bitmap void __bitmap_shift_right unsigned long * dst const unsigned long * src unsigned shift unsigned nbits dst destination bitmap src source bitmap shift shift by this many bits nbits 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 July 2017 __bitmap_shift_left 9 4.1.27 __bitmap_shift_left logical left shift of the bits in a bitmap void __bitmap_shift_left unsigned long * dst const unsigned long * src unsigned int shift unsigned int nbits dst destination bitmap src source bitmap shift shift by this many bits nbits 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 July 2017 bitmap_find_next_zero_area_off 9 4.1.27 bitmap_find_next_zero_area_off find a contiguous aligned zero area unsigned long bitmap_find_next_zero_area_off unsigned long * map unsigned long size unsigned long start unsigned int nr unsigned long align_mask unsigned long align_offset map The address to base the search on size The bitmap size in bits start The bitnumber to start searching at nr The number of zeroed bits we're looking for align_mask Alignment mask for zero area align_offset Alignment offset for zero area. The align_mask should be one less than a power of 2; the effect is that the bit offset of all zero areas this function finds plus align_offset is multiple of that power of 2. Kernel Hackers Manual July 2017 __bitmap_parse 9 4.1.27 __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 July 2017 bitmap_parse_user 9 4.1.27 bitmap_parse_user convert an ASCII hex string in a user buffer into a bitmap 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 July 2017 bitmap_print_to_pagebuf 9 4.1.27 bitmap_print_to_pagebuf convert bitmap to list or hex format ASCII string int bitmap_print_to_pagebuf bool list char * buf const unsigned long * maskp int nmaskbits list indicates whether the bitmap must be list buf page aligned buffer into which string is placed maskp pointer to bitmap to convert nmaskbits size of bitmap, in bits Output format is a comma-separated list of decimal numbers and ranges if list is specified or hex digits grouped into comma-separated sets of 8 digits/set. Returns the number of characters written to buf. Kernel Hackers Manual July 2017 bitmap_parselist_user 9 4.1.27 bitmap_parselist_user int bitmap_parselist_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_parselist, 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 July 2017 bitmap_remap 9 4.1.27 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 unsigned int nbits dst remapped result src subset to be remapped old defines domain of map new defines range of map nbits 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 July 2017 bitmap_bitremap 9 4.1.27 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 July 2017 bitmap_onto 9 4.1.27 bitmap_onto translate one bitmap relative to another void bitmap_onto unsigned long * dst const unsigned long * orig const unsigned long * relmap unsigned 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 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 twelfth 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 possibility 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 July 2017 bitmap_fold 9 4.1.27 bitmap_fold fold larger bitmap into smaller, modulo specified size void bitmap_fold unsigned long * dst const unsigned long * orig unsigned int sz unsigned int nbits dst resulting smaller bitmap orig original larger bitmap sz specified size nbits 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 July 2017 bitmap_find_free_region 9 4.1.27 bitmap_find_free_region find a contiguous aligned mem region int bitmap_find_free_region unsigned long * bitmap unsigned 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 July 2017 bitmap_release_region 9 4.1.27 bitmap_release_region release allocated bitmap region void bitmap_release_region unsigned long * bitmap unsigned 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 July 2017 bitmap_allocate_region 9 4.1.27 bitmap_allocate_region allocate bitmap region int bitmap_allocate_region unsigned long * bitmap unsigned 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 July 2017 bitmap_copy_le 9 4.1.27 bitmap_copy_le copy a bitmap, putting the bits into little-endian order. void bitmap_copy_le unsigned long * dst const unsigned long * src unsigned 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 July 2017 __bitmap_parselist 9 4.1.27 __bitmap_parselist convert list format ASCII string to bitmap int __bitmap_parselist const char * buf unsigned int buflen int is_user unsigned long * maskp int nmaskbits buf read nul-terminated user string from this buffer 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 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 July 2017 bitmap_pos_to_ord 9 4.1.27 bitmap_pos_to_ord find ordinal of set bit at given position in bitmap int bitmap_pos_to_ord const unsigned long * buf unsigned int pos unsigned int nbits buf pointer to a bitmap pos a bit position in buf (0 <= pos < nbits) nbits number of valid bit positions in buf Map the bit at position pos in buf (of length nbits) 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 -1. 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 July 2017 bitmap_ord_to_pos 9 4.1.27 bitmap_ord_to_pos find position of n-th set bit in bitmap unsigned int bitmap_ord_to_pos const unsigned long * buf unsigned int ord unsigned int nbits buf pointer to bitmap ord ordinal bit position (n-th set bit, n >= 0) nbits 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). If ord >= weight(buf), returns nbits. 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 returns nbits. 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 nbits-1 are valid positions in buf. Kernel Hackers Manual July 2017 get_option 9 4.1.27 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 July 2017 get_options 9 4.1.27 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 July 2017 memparse 9 4.1.27 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, M, G, T, P, E. Kernel Hackers Manual July 2017 crc7_be 9 4.1.27 crc7_be update the CRC7 for the data buffer u8 crc7_be 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. The CRC7 is left-aligned in the byte (the lsbit is always 0), as that makes the computation easier, and all callers want it in that form. Kernel Hackers Manual July 2017 crc16 9 4.1.27 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 July 2017 crc_itu_t 9 4.1.27 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 .//lib/crc32.c Document generation inconsistency The template for this document tried to insert the structured comment from the file .//lib/crc32.c at this point, but none was found. This dummy section is inserted to allow generation to continue. Kernel Hackers Manual July 2017 crc_ccitt 9 4.1.27 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 idr synchronization (stolen from radix-tree.h) idr_find is able to be called locklessly, using RCU. The caller must ensure calls to this function are made within rcu_read_lock regions. Other readers (lock-free or otherwise) and modifications may be running concurrently. It is still required that the caller manage the synchronization and lifetimes of the items. So if RCU lock-free lookups are used, typically this would mean that the items have their own locks, or are amenable to lock-free access; and that the items are freed by RCU (or only freed after having been deleted from the idr tree *and* a synchronize_rcu grace period). IDA - IDR based ID allocator This is id allocator without id -> pointer translation. Memory usage is much lower than full blown idr because each id only occupies a bit. ida uses a custom leaf node which contains IDA_BITMAP_BITS slots. 2007-04-25 written by Tejun Heo <htejungmail.com> Kernel Hackers Manual July 2017 idr_preload 9 4.1.27 idr_preload preload for idr_alloc void idr_preload gfp_t gfp_mask gfp_mask allocation mask to use for preloading Preload per-cpu layer buffer for idr_alloc. Can only be used from process context and each idr_preload invocation should be matched with idr_preload_end. Note that preemption is disabled while preloaded. The first idr_alloc in the preloaded section can be treated as if it were invoked with gfp_mask used for preloading. This allows using more permissive allocation masks for idrs protected by spinlocks. For example, if idr_alloc below fails, the failure can be treated as if idr_alloc were called with GFP_KERNEL rather than GFP_NOWAIT. idr_preload(GFP_KERNEL); spin_lock(lock); id = idr_alloc(idr, ptr, start, end, GFP_NOWAIT); spin_unlock(lock); idr_preload_end; if (id < 0) error; Kernel Hackers Manual July 2017 idr_alloc 9 4.1.27 idr_alloc allocate new idr entry int idr_alloc struct idr * idr void * ptr int start int end gfp_t gfp_mask idr the (initialized) idr ptr pointer to be associated with the new id start the minimum id (inclusive) end the maximum id (exclusive, <= 0 for max) gfp_mask memory allocation flags Allocate an id in [start, end) and associate it with ptr. If no ID is available in the specified range, returns -ENOSPC. On memory allocation failure, returns -ENOMEM. Note that end is treated as max when <= 0. This is to always allow using start + N as end as long as N is inside integer range. The user is responsible for exclusively synchronizing all operations which may modify idr. However, read-only accesses such as idr_find or iteration can be performed under RCU read lock provided the user destroys ptr in RCU-safe way after removal from idr. Kernel Hackers Manual July 2017 idr_alloc_cyclic 9 4.1.27 idr_alloc_cyclic allocate new idr entry in a cyclical fashion int idr_alloc_cyclic struct idr * idr void * ptr int start int end gfp_t gfp_mask idr the (initialized) idr ptr pointer to be associated with the new id start the minimum id (inclusive) end the maximum id (exclusive, <= 0 for max) gfp_mask memory allocation flags Essentially the same as idr_alloc, but prefers to allocate progressively higher ids if it can. If the cur counter wraps, then it will start again at the start end of the range and allocate one that has already been used. Kernel Hackers Manual July 2017 idr_remove 9 4.1.27 idr_remove remove the given id and free its slot void idr_remove struct idr * idp int id idp idr handle id unique key Kernel Hackers Manual July 2017 idr_destroy 9 4.1.27 idr_destroy release all cached layers within an idr tree void idr_destroy struct idr * idp idp idr handle Free all id mappings and all idp_layers. After this function, idp is completely unused and can be freed / recycled. The caller is responsible for ensuring that no one else accesses idp during or after idr_destroy. A typical clean-up sequence for objects stored in an idr tree will use idr_for_each to free all objects, if necessary, then idr_destroy to free up the id mappings and cached idr_layers. Kernel Hackers Manual July 2017 idr_for_each 9 4.1.27 idr_for_each iterate through all stored pointers int idr_for_each struct idr * idp int (*fn) int id, void *p, void *data void * data idp idr handle fn function to be called for each pointer data data passed back to callback function Iterate over the pointers registered with the given idr. The callback function will be called for each pointer currently registered, passing the id, the pointer and the data pointer passed to this function. It is not safe to modify the idr tree while in the callback, so functions such as idr_get_new and idr_remove are not allowed. We check the return of fn each time. If it returns anything other than 0, we break out and return that value. The caller must serialize idr_for_each vs idr_get_new and idr_remove. Kernel Hackers Manual July 2017 idr_get_next 9 4.1.27 idr_get_next lookup next object of id to given id. void * idr_get_next struct idr * idp int * nextidp idp idr handle nextidp pointer to lookup key Returns pointer to registered object with id, which is next number to given id. After being looked up, *nextidp will be updated for the next iteration. This function can be called under rcu_read_lock, given that the leaf pointers lifetimes are correctly managed. Kernel Hackers Manual July 2017 idr_replace 9 4.1.27 idr_replace replace pointer for given id void * idr_replace struct idr * idp void * ptr int id idp idr handle ptr pointer you want associated with the id id lookup key Replace the pointer registered with an id and return the old value. A -ENOENT return indicates that id was not found. A -EINVAL return indicates that id was not within valid constraints. The caller must serialize with writers. Kernel Hackers Manual July 2017 idr_init 9 4.1.27 idr_init initialize idr handle void idr_init struct idr * idp idp idr handle This function is use to set up the handle (idp) that you will pass to the rest of the functions. Kernel Hackers Manual July 2017 ida_pre_get 9 4.1.27 ida_pre_get reserve resources for ida allocation int ida_pre_get struct ida * ida gfp_t gfp_mask ida ida handle gfp_mask memory allocation flag This function should be called prior to locking and calling the following function. It preallocates enough memory to satisfy the worst possible allocation. If the system is REALLY out of memory this function returns 0, otherwise 1. Kernel Hackers Manual July 2017 ida_get_new_above 9 4.1.27 ida_get_new_above allocate new ID above or equal to a start id int ida_get_new_above struct ida * ida int starting_id int * p_id ida ida handle starting_id id to start search at p_id pointer to the allocated handle Allocate new ID above or equal to starting_id. It should be called with any required locks. If memory is required, it will return -EAGAIN, you should unlock and go back to the ida_pre_get call. If the ida is full, it will return -ENOSPC. p_id returns a value in the range starting_id ... 0x7fffffff. Kernel Hackers Manual July 2017 ida_remove 9 4.1.27 ida_remove remove the given ID void ida_remove struct ida * ida int id ida ida handle id ID to free Kernel Hackers Manual July 2017 ida_destroy 9 4.1.27 ida_destroy release all cached layers within an ida tree void ida_destroy struct ida * ida ida ida handle Kernel Hackers Manual July 2017 ida_simple_get 9 4.1.27 ida_simple_get get a new id. int ida_simple_get struct ida * ida unsigned int start unsigned int end gfp_t gfp_mask ida the (initialized) ida. start the minimum id (inclusive, < 0x8000000) end the maximum id (exclusive, < 0x8000000 or 0) gfp_mask memory allocation flags Allocates an id in the range start <= id < end, or returns -ENOSPC. On memory allocation failure, returns -ENOMEM. Use ida_simple_remove to get rid of an id. Kernel Hackers Manual July 2017 ida_simple_remove 9 4.1.27 ida_simple_remove remove an allocated id. void ida_simple_remove struct ida * ida unsigned int id ida the (initialized) ida. id the id returned by ida_simple_get. Kernel Hackers Manual July 2017 ida_init 9 4.1.27 ida_init initialize ida handle void ida_init struct ida * ida ida ida handle This function is use to set up the handle (ida) that you will pass to the rest of the functions. Kernel Hackers Manual July 2017 kmalloc 9 4.1.27 kmalloc allocate memory void * kmalloc size_t size gfp_t flags size how many bytes of memory are required. flags the type of memory to allocate. kmalloc is the normal method of allocating memory for objects smaller than page size in the kernel. 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 July 2017 kmalloc_array 9 4.1.27 kmalloc_array allocate memory for an array. void * kmalloc_array size_t n size_t size gfp_t flags n number of elements. size element size. flags the type of memory to allocate (see kmalloc). Kernel Hackers Manual July 2017 kcalloc 9 4.1.27 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 (see kmalloc). Kernel Hackers Manual July 2017 kzalloc 9 4.1.27 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 July 2017 kzalloc_node 9 4.1.27 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 July 2017 kmem_cache_alloc 9 4.1.27 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 July 2017 kmem_cache_alloc_node 9 4.1.27 kmem_cache_alloc_node Allocate an object on the specified node void * kmem_cache_alloc_node struct kmem_cache * cachep gfp_t flags int nodeid cachep The cache to allocate from. flags See kmalloc. nodeid node number of the target node. Identical to kmem_cache_alloc but it will allocate memory on the given node, which can improve the performance for cpu bound structures. Fallback to other node is possible if __GFP_THISNODE is not set. Kernel Hackers Manual July 2017 kmem_cache_free 9 4.1.27 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 July 2017 kfree 9 4.1.27 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 July 2017 ksize 9 4.1.27 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 July 2017 kfree_const 9 4.1.27 kfree_const conditionally free memory void kfree_const const void * x x pointer to the memory Function calls kfree only if x is not in .rodata section. Kernel Hackers Manual July 2017 kstrdup 9 4.1.27 kstrdup allocate space for and copy an existing string char * kstrdup const char * s gfp_t gfp s the string to duplicate gfp the GFP mask used in the kmalloc call when allocating memory Kernel Hackers Manual July 2017 kstrdup_const 9 4.1.27 kstrdup_const conditionally duplicate an existing const string const char * kstrdup_const const char * s gfp_t gfp s the string to duplicate gfp the GFP mask used in the kmalloc call when allocating memory Function returns source string if it is in .rodata section otherwise it fallbacks to kstrdup. Strings allocated by kstrdup_const should be freed by kfree_const. Kernel Hackers Manual July 2017 kstrndup 9 4.1.27 kstrndup allocate space for and copy an existing string char * kstrndup const char * s size_t max gfp_t gfp s the string to duplicate max read at most max chars from s gfp the GFP mask used in the kmalloc call when allocating memory Kernel Hackers Manual July 2017 kmemdup 9 4.1.27 kmemdup duplicate region of memory void * kmemdup const void * src size_t len gfp_t gfp src memory region to duplicate len memory region length gfp GFP mask to use Kernel Hackers Manual July 2017 memdup_user 9 4.1.27 memdup_user duplicate memory region from user space void * memdup_user const void __user * src size_t len src source address in user space len number of bytes to copy Returns an ERR_PTR on failure. Kernel Hackers Manual July 2017 get_user_pages_fast 9 4.1.27 get_user_pages_fast pin user pages in memory int get_user_pages_fast unsigned long start int nr_pages int write struct page ** pages start starting user address nr_pages number of pages from start to pin write whether pages will be written to pages array that receives pointers to the pages pinned. Should be at least nr_pages long. 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. get_user_pages_fast provides equivalent functionality to get_user_pages, operating on current and current->mm, with force=0 and vma=NULL. However unlike get_user_pages, it must be called without mmap_sem held. get_user_pages_fast may take mmap_sem and page table locks, so no assumptions can be made about lack of locking. get_user_pages_fast is to be implemented in a way that is advantageous (vs get_user_pages) when the user memory area is already faulted in and present in ptes. However if the pages have to be faulted in, it may turn out to be slightly slower so callers need to carefully consider what to use. On many architectures, get_user_pages_fast simply falls back to get_user_pages. Kernel Hackers Manual July 2017 __copy_to_user_inatomic 9 4.1.27 __copy_to_user_inatomic Copy a block of data into user space, with less checking. unsigned long __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 July 2017 __copy_to_user 9 4.1.27 __copy_to_user Copy a block of data into user space, with less checking. 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. 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 July 2017 __copy_from_user 9 4.1.27 __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 July 2017 clear_user 9 4.1.27 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 July 2017 __clear_user 9 4.1.27 __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 July 2017 _copy_to_user 9 4.1.27 _copy_to_user Copy a block of data into user space. unsigned long _copy_to_user void __user * to const void * from unsigned 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 July 2017 _copy_from_user 9 4.1.27 _copy_from_user Copy a block of data from user space. unsigned long _copy_from_user void * to const void __user * from unsigned 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 July 2017 read_cache_pages 9 4.1.27 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 July 2017 page_cache_sync_readahead 9 4.1.27 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 July 2017 page_cache_async_readahead 9 4.1.27 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_readahead 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 July 2017 delete_from_page_cache 9 4.1.27 delete_from_page_cache delete page from page cache void delete_from_page_cache struct page * page page the page which the kernel is trying to remove from page cache This must be called only on pages that have been verified to be in the page cache and locked. It will never put the page into the free list, the caller has a reference on the page. Kernel Hackers Manual July 2017 filemap_flush 9 4.1.27 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 July 2017 filemap_fdatawait_range 9 4.1.27 filemap_fdatawait_range wait for writeback to complete int filemap_fdatawait_range struct address_space * mapping loff_t start_byte loff_t end_byte mapping address space structure to wait for start_byte offset in bytes where the range starts end_byte 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. Kernel Hackers Manual July 2017 filemap_fdatawait 9 4.1.27 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 July 2017 filemap_write_and_wait_range 9 4.1.27 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 July 2017 replace_page_cache_page 9 4.1.27 replace_page_cache_page replace a pagecache page with a new one int replace_page_cache_page struct page * old struct page * new gfp_t gfp_mask old page to be replaced new page to replace with gfp_mask allocation mode This function replaces a page in the pagecache with a new one. On success it acquires the pagecache reference for the new page and drops it for the old page. Both the old and new pages must be locked. This function does not add the new page to the LRU, the caller must do that. The remove + add is atomic. The only way this function can fail is memory allocation failure. Kernel Hackers Manual July 2017 add_to_page_cache_locked 9 4.1.27 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 July 2017 add_page_wait_queue 9 4.1.27 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 July 2017 unlock_page 9 4.1.27 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 mechanism 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 July 2017 end_page_writeback 9 4.1.27 end_page_writeback end writeback against a page void end_page_writeback struct page * page page the page Kernel Hackers Manual July 2017 __lock_page 9 4.1.27 __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 Kernel Hackers Manual July 2017 page_cache_next_hole 9 4.1.27 page_cache_next_hole find the next hole (not-present entry) pgoff_t page_cache_next_hole struct address_space * mapping pgoff_t index unsigned long max_scan mapping mapping index index max_scan maximum range to search Search the set [index, min(index+max_scan-1, MAX_INDEX)] for the lowest indexed hole. the index of the hole if found, otherwise returns an index outside of the set specified (in which case 'return - index >= max_scan' will be true). In rare cases of index wrap-around, 0 will be returned. page_cache_next_hole may be called under rcu_read_lock. However, like radix_tree_gang_lookup, this will not atomically search a snapshot of the tree at a single point in time. For example, if a hole is created at index 5, then subsequently a hole is created at index 10, page_cache_next_hole covering both indexes may return 10 if called under rcu_read_lock. Kernel Hackers Manual July 2017 page_cache_prev_hole 9 4.1.27 page_cache_prev_hole find the prev hole (not-present entry) pgoff_t page_cache_prev_hole struct address_space * mapping pgoff_t index unsigned long max_scan mapping mapping index index max_scan maximum range to search Search backwards in the range [max(index-max_scan+1, 0), index] for the first hole. the index of the hole if found, otherwise returns an index outside of the set specified (in which case 'index - return >= max_scan' will be true). In rare cases of wrap-around, ULONG_MAX will be returned. page_cache_prev_hole may be called under rcu_read_lock. However, like radix_tree_gang_lookup, this will not atomically search a snapshot of the tree at a single point in time. For example, if a hole is created at index 10, then subsequently a hole is created at index 5, page_cache_prev_hole covering both indexes may return 5 if called under rcu_read_lock. Kernel Hackers Manual July 2017 find_get_entry 9 4.1.27 find_get_entry find and get a page cache entry struct page * find_get_entry struct address_space * mapping pgoff_t offset mapping the address_space to search offset the page cache index Looks up the page cache slot at mapping & offset. If there is a page cache page, it is returned with an increased refcount. If the slot holds a shadow entry of a previously evicted page, or a swap entry from shmem/tmpfs, it is returned. Otherwise, NULL is returned. Kernel Hackers Manual July 2017 find_lock_entry 9 4.1.27 find_lock_entry locate, pin and lock a page cache entry struct page * find_lock_entry struct address_space * mapping pgoff_t offset mapping the address_space to search offset the page cache index Looks up the page cache slot at mapping & offset. If there is a page cache page, it is returned locked and with an increased refcount. If the slot holds a shadow entry of a previously evicted page, or a swap entry from shmem/tmpfs, it is returned. Otherwise, NULL is returned. find_lock_entry may sleep. Kernel Hackers Manual July 2017 pagecache_get_page 9 4.1.27 pagecache_get_page find and get a page reference struct page * pagecache_get_page struct address_space * mapping pgoff_t offset int fgp_flags gfp_t gfp_mask mapping the address_space to search offset the page index fgp_flags PCG flags gfp_mask gfp mask to use for the page cache data page allocation Looks up the page cache slot at mapping & offset. PCG flags modify how the page is returned. the page will be marked accessed Page is return locked If page is not present then a new page is allocated using gfp_mask and added to the page cache and the VM's LRU list. The page is returned locked and with an increased refcount. Otherwise, NULL is returned. If FGP_LOCK or FGP_CREAT are specified then the function may sleep even if the GFP flags specified for FGP_CREAT are atomic. If there is a page cache page, it is returned with an increased refcount. Kernel Hackers Manual July 2017 find_get_pages_contig 9 4.1.27 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 July 2017 find_get_pages_tag 9 4.1.27 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 July 2017 generic_file_read_iter 9 4.1.27 generic_file_read_iter generic filesystem read routine ssize_t generic_file_read_iter struct kiocb * iocb struct iov_iter * iter iocb kernel I/O control block iter destination for the data read This is the read_iter routine for all filesystems that can use the page cache directly. Kernel Hackers Manual July 2017 filemap_fault 9 4.1.27 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. vma->vm_mm->mmap_sem must be held on entry. If our return value has VM_FAULT_RETRY set, it's because lock_page_or_retry returned 0. The mmap_sem has usually been released in this case. See __lock_page_or_retry for the exception. If our return value does not have VM_FAULT_RETRY set, the mmap_sem has not been released. We never return with VM_FAULT_RETRY and a bit from VM_FAULT_ERROR set. Kernel Hackers Manual July 2017 read_cache_page 9 4.1.27 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 first arg to filler(data, page) function, often left as NULL Read into the page cache. If a page already exists, and PageUptodate is not set, try to fill the page and wait for it to become unlocked. If the page does not get brought uptodate, return -EIO. Kernel Hackers Manual July 2017 read_cache_page_gfp 9 4.1.27 read_cache_page_gfp read into page cache, using specified page allocation flags. struct page * read_cache_page_gfp struct address_space * mapping pgoff_t index gfp_t gfp mapping the page's address_space index the page index gfp the page allocator flags to use if allocating This is the same as read_mapping_page(mapping, index, NULL), but with any new page allocations done using the specified allocation flags. If the page does not get brought uptodate, return -EIO. Kernel Hackers Manual July 2017 __generic_file_write_iter 9 4.1.27 __generic_file_write_iter write data to a file ssize_t __generic_file_write_iter struct kiocb * iocb struct iov_iter * from iocb IO state structure (file, offset, etc.) from iov_iter with data 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 July 2017 generic_file_write_iter 9 4.1.27 generic_file_write_iter write data to a file ssize_t generic_file_write_iter struct kiocb * iocb struct iov_iter * from iocb IO state structure from iov_iter with data to write This is a wrapper around __generic_file_write_iter 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 July 2017 try_to_release_page 9 4.1.27 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 July 2017 zap_vma_ptes 9 4.1.27 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 July 2017 vm_insert_page 9 4.1.27 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. Usually this function is called from f_op->mmap handler under mm->mmap_sem write-lock, so it can change vma->vm_flags. Caller must set VM_MIXEDMAP on vma if it wants to call this function from other places, for example from page-fault handler. Kernel Hackers Manual July 2017 vm_insert_pfn 9 4.1.27 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_insert_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 July 2017 remap_pfn_range 9 4.1.27 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 July 2017 vm_iomap_memory 9 4.1.27 vm_iomap_memory remap memory to userspace int vm_iomap_memory struct vm_area_struct * vma phys_addr_t start unsigned long len vma user vma to map to start start of area len size of area This is a simplified io_remap_pfn_range for common driver use. The driver just needs to give us the physical memory range to be mapped, we'll figure out the rest from the vma information. NOTE! Some drivers might want to tweak vma->vm_page_prot first to get whatever write-combining details or similar. Kernel Hackers Manual July 2017 unmap_mapping_range 9 4.1.27 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 July 2017 follow_pfn 9 4.1.27 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 July 2017 vm_unmap_aliases 9 4.1.27 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 July 2017 vm_unmap_ram 9 4.1.27 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 July 2017 vm_map_ram 9 4.1.27 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 If you use this function for less than VMAP_MAX_ALLOC pages, it could be faster than vmap so it's good. But if you mix long-life and short-life objects with vm_map_ram, it could consume lots of address space through fragmentation (especially on a 32bit machine). You could see failures in the end. Please use this function for short-lived objects. a pointer to the address that has been mapped, or NULL on failure Kernel Hackers Manual July 2017 unmap_kernel_range_noflush 9 4.1.27 unmap_kernel_range_noflush unmap kernel VM area void unmap_kernel_range_noflush unsigned long addr unsigned long size addr start of the VM area to unmap size size of the VM area to unmap Unmap PFN_UP(size) pages at addr. The VM area addr and size specify should have been allocated using get_vm_area and its friends. This function does NOT do any cache flushing. The caller is responsible for calling flush_cache_vunmap on to-be-mapped areas before calling this function and flush_tlb_kernel_range after. Kernel Hackers Manual July 2017 unmap_kernel_range 9 4.1.27 unmap_kernel_range unmap kernel VM area and flush cache and TLB void unmap_kernel_range unsigned long addr unsigned long size addr start of the VM area to unmap size size of the VM area to unmap Similar to unmap_kernel_range_noflush but flushes vcache before the unmapping and tlb after. Kernel Hackers Manual July 2017 vfree 9 4.1.27 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 NMI context (strictly speaking, only if we don't have CONFIG_ARCH_HAVE_NMI_SAFE_CMPXCHG, but making the calling conventions for vfree arch-depenedent would be a really bad idea) assumes that the object at *addr has a size >= sizeof(llist_node) Kernel Hackers Manual July 2017 vunmap 9 4.1.27 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 July 2017 vmap 9 4.1.27 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 July 2017 vmalloc 9 4.1.27 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 July 2017 vzalloc 9 4.1.27 vzalloc allocate virtually contiguous memory with zero fill void * vzalloc 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. The memory allocated is set to zero. For tight control over page level allocator and protection flags use __vmalloc instead. Kernel Hackers Manual July 2017 vmalloc_user 9 4.1.27 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 July 2017 vmalloc_node 9 4.1.27 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 July 2017 vzalloc_node 9 4.1.27 vzalloc_node allocate memory on a specific node with zero fill void * vzalloc_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. The memory allocated is set to zero. For tight control over page level allocator and protection flags use __vmalloc_node instead. Kernel Hackers Manual July 2017 vmalloc_32 9 4.1.27 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 July 2017 vmalloc_32_user 9 4.1.27 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 July 2017 remap_vmalloc_range_partial 9 4.1.27 remap_vmalloc_range_partial map vmalloc pages to userspace int remap_vmalloc_range_partial struct vm_area_struct * vma unsigned long uaddr void * kaddr unsigned long size vma vma to cover uaddr target user address to start at kaddr virtual address of vmalloc kernel memory size size of map area 0 for success, -Exxx on failure This function checks that kaddr is a valid vmalloc'ed area, and that it is big enough to cover the range starting at uaddr in vma. Will return failure if that criteria isn't met. Similar to remap_pfn_range (see mm/memory.c) Kernel Hackers Manual July 2017 remap_vmalloc_range 9 4.1.27 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 July 2017 alloc_vm_area 9 4.1.27 alloc_vm_area allocate a range of kernel address space struct vm_struct * alloc_vm_area size_t size pte_t ** ptes size size of the area ptes returns the PTEs for the address space 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 ptes is non-NULL, pointers to the PTEs (in init_mm) allocated for the VM area are returned. Kernel Hackers Manual July 2017 alloc_pages_exact_nid 9 4.1.27 alloc_pages_exact_nid allocate an exact number of physically-contiguous pages on a node. void * alloc_pages_exact_nid int nid size_t size gfp_t gfp_mask nid the preferred node ID where memory should be allocated size the number of bytes to allocate gfp_mask GFP flags for the allocation Like alloc_pages_exact, but try to allocate on node nid first before falling back. Note this is not alloc_pages_exact_node which allocates on a specific node, but is not exact. Kernel Hackers Manual July 2017 nr_free_zone_pages 9 4.1.27 nr_free_zone_pages count number of pages beyond high watermark unsigned long nr_free_zone_pages int offset offset The zone index of the highest zone nr_free_zone_pages counts the number of counts pages which are beyond the high watermark within all zones at or below a given zone index. For each zone, the number of pages is calculated as: managed_pages - high_pages Kernel Hackers Manual July 2017 nr_free_pagecache_pages 9 4.1.27 nr_free_pagecache_pages count number of pages beyond high watermark unsigned long nr_free_pagecache_pages void void no arguments nr_free_pagecache_pages counts the number of pages which are beyond the high watermark within all zones. Kernel Hackers Manual July 2017 find_next_best_node 9 4.1.27 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 July 2017 free_bootmem_with_active_regions 9 4.1.27 free_bootmem_with_active_regions Call memblock_free_early_nid 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 memblock_free_early_nid If an architecture guarantees that all ranges registered contain no holes and may be freed, this this function may be used instead of calling memblock_free_early_nid manually. Kernel Hackers Manual July 2017 sparse_memory_present_with_active_regions 9 4.1.27 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 contain no holes and may be freed, this function may be used instead of calling memory_present manually. Kernel Hackers Manual July 2017 get_pfn_range_for_nid 9 4.1.27 get_pfn_range_for_nid Return the start and end page frames for a node void 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 memblock_set_node. 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 July 2017 absent_pages_in_range 9 4.1.27 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 July 2017 node_map_pfn_alignment 9 4.1.27 node_map_pfn_alignment determine the maximum internode alignment unsigned long node_map_pfn_alignment void void no arguments This function should be called after node map is populated and sorted. It calculates the maximum power of two alignment which can distinguish all the nodes. For example, if all nodes are 1GiB and aligned to 1GiB, the return value would indicate 1GiB alignment with (1 << (30 - PAGE_SHIFT)). If the nodes are shifted by 256MiB, 256MiB. Note that if only the last node is shifted, 1GiB is enough and this function will indicate so. This is used to test whether pfn -> nid mapping of the chosen memory model has fine enough granularity to avoid incorrect mapping for the populated node map. Returns the determined alignment in pfn's. 0 if there is no alignment requirement (single node). Kernel Hackers Manual July 2017 find_min_pfn_with_active_regions 9 4.1.27 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 memblock_set_node. Kernel Hackers Manual July 2017 free_area_init_nodes 9 4.1.27 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 memblock_set_node, 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 July 2017 set_dma_reserve 9 4.1.27 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 July 2017 setup_per_zone_wmarks 9 4.1.27 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 July 2017 get_pfnblock_flags_mask 9 4.1.27 get_pfnblock_flags_mask Return the requested group of flags for the pageblock_nr_pages block of pages unsigned long get_pfnblock_flags_mask struct page * page unsigned long pfn unsigned long end_bitidx unsigned long mask page The page within the block of interest pfn The target page frame number end_bitidx The last bit of interest to retrieve mask mask of bits that the caller is interested in pageblock_bits flags Kernel Hackers Manual July 2017 set_pfnblock_flags_mask 9 4.1.27 set_pfnblock_flags_mask Set the requested group of flags for a pageblock_nr_pages block of pages void set_pfnblock_flags_mask struct page * page unsigned long flags unsigned long pfn unsigned long end_bitidx unsigned long mask page The page within the block of interest flags The flags to set pfn The target page frame number end_bitidx The last bit of interest mask mask of bits that the caller is interested in Kernel Hackers Manual July 2017 alloc_contig_range 9 4.1.27 alloc_contig_range - tries to allocate given range of pages int alloc_contig_range unsigned long start unsigned long end unsigned migratetype start start PFN to allocate end one-past-the-last PFN to allocate migratetype migratetype of the underlaying pageblocks (either #MIGRATE_MOVABLE or #MIGRATE_CMA). All pageblocks in range must have the same migratetype and it must be either of the two. The PFN range does not have to be pageblock or MAX_ORDER_NR_PAGES aligned, however it's the caller's responsibility to guarantee that we are the only thread that changes migrate type of pageblocks the pages fall in. The PFN range must belong to a single zone. Returns zero on success or negative error code. On success all pages which PFN is in [start, end) are allocated for the caller and need to be freed with free_contig_range. Kernel Hackers Manual July 2017 mempool_destroy 9 4.1.27 mempool_destroy deallocate a memory pool void mempool_destroy mempool_t * pool pool pointer to the memory pool which was allocated via mempool_create. Free all reserved elements in pool and pool itself. This function only sleeps if the free_fn function sleeps. Kernel Hackers Manual July 2017 mempool_create 9 4.1.27 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 July 2017 mempool_resize 9 4.1.27 mempool_resize resize an existing memory pool int mempool_resize mempool_t * pool int new_min_nr 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. 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. This function may sleep. 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 July 2017 mempool_alloc 9 4.1.27 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.) using __GFP_ZERO is not supported. Kernel Hackers Manual July 2017 mempool_free 9 4.1.27 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 July 2017 dma_pool_create 9 4.1.27 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 July 2017 dma_pool_destroy 9 4.1.27 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 July 2017 dma_pool_alloc 9 4.1.27 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 July 2017 dma_pool_free 9 4.1.27 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 July 2017 dmam_pool_create 9 4.1.27 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 July 2017 dmam_pool_destroy 9 4.1.27 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 July 2017 balance_dirty_pages_ratelimited 9 4.1.27 balance_dirty_pages_ratelimited balance dirty memory state void balance_dirty_pages_ratelimited struct address_space * mapping mapping address_space which was 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 July 2017 tag_pages_for_writeback 9 4.1.27 tag_pages_for_writeback tag pages to be written by write_cache_pages void tag_pages_for_writeback struct address_space * mapping pgoff_t start pgoff_t end mapping address space structure to write start starting page index end ending page index (inclusive) This function scans the page range from start to end (inclusive) and tags all pages that have DIRTY tag set with a special TOWRITE tag. The idea is that write_cache_pages (or whoever calls this function) will then use TOWRITE tag to identify pages eligible for writeback. This mechanism is used to avoid livelocking of writeback by a process steadily creating new dirty pages in the file (thus it is important for this function to be quick so that it can tag pages faster than a dirtying process can create them). Kernel Hackers Manual July 2017 write_cache_pages 9 4.1.27 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. To avoid livelocks (when other process dirties new pages), we first tag pages which should be written back with TOWRITE tag and only then start writing them. For data-integrity sync we have to be careful so that we do not miss some pages (e.g., because some other process has cleared TOWRITE tag we set). The rule we follow is that TOWRITE tag can be cleared only by the process clearing the DIRTY tag (and submitting the page for IO). Kernel Hackers Manual July 2017 generic_writepages 9 4.1.27 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 July 2017 write_one_page 9 4.1.27 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 July 2017 wait_for_stable_page 9 4.1.27 wait_for_stable_page wait for writeback to finish, if necessary. void wait_for_stable_page struct page * page page The page to wait on. This function determines if the given page is related to a backing device that requires page contents to be held stable during writeback. If so, then it will wait for any pending writeback to complete. Kernel Hackers Manual July 2017 truncate_inode_pages_range 9 4.1.27 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 (inclusive) Truncate the page cache, removing the pages that are between specified offsets (and zeroing out partial pages if lstart or lend + 1 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. 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. Note that since ->invalidatepage accepts range to invalidate truncate_inode_pages_range is able to handle cases where lend + 1 is not page aligned properly. Kernel Hackers Manual July 2017 truncate_inode_pages 9 4.1.27 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. When this function returns, there can be a page in the process of deletion (inside __delete_from_page_cache) in the specified range. Thus mapping->nrpages can be non-zero when this function returns even after truncation of the whole mapping. Kernel Hackers Manual July 2017 truncate_inode_pages_final 9 4.1.27 truncate_inode_pages_final truncate *all* pages before inode dies void truncate_inode_pages_final struct address_space * mapping mapping mapping to truncate Called under (and serialized by) inode->i_mutex. Filesystems have to use this in the .evict_inode path to inform the VM that this is the final truncate and the inode is going away. Kernel Hackers Manual July 2017 invalidate_mapping_pages 9 4.1.27 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 July 2017 invalidate_inode_pages2_range 9 4.1.27 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 July 2017 invalidate_inode_pages2 9 4.1.27 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 -EBUSY if any pages could not be invalidated. Kernel Hackers Manual July 2017 truncate_pagecache 9 4.1.27 truncate_pagecache unmap and remove pagecache that has been truncated void truncate_pagecache struct inode * inode loff_t newsize inode inode newsize new file size 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 July 2017 truncate_setsize 9 4.1.27 truncate_setsize update inode and pagecache for a new file size void truncate_setsize struct inode * inode loff_t newsize inode inode newsize new file size truncate_setsize updates i_size and performs pagecache truncation (if necessary) to newsize. It will be typically be called from the filesystem's setattr function when ATTR_SIZE is passed in. Must be called with a lock serializing truncates and writes (generally i_mutex but e.g. xfs uses a different lock) and before all filesystem specific block truncation has been performed. Kernel Hackers Manual July 2017 pagecache_isize_extended 9 4.1.27 pagecache_isize_extended update pagecache after extension of i_size void pagecache_isize_extended struct inode * inode loff_t from loff_t to inode inode for which i_size was extended from original inode size to new inode size Handle extension of inode size either caused by extending truncate or by write starting after current i_size. We mark the page straddling current i_size RO so that page_mkwrite is called on the nearest write access to the page. This way filesystem can be sure that page_mkwrite is called on the page before user writes to the page via mmap after the i_size has been changed. The function must be called after i_size is updated so that page fault coming after we unlock the page will already see the new i_size. The function must be called while we still hold i_mutex - this not only makes sure i_size is stable but also that userspace cannot observe new i_size value before we are prepared to store mmap writes at new inode size. Kernel Hackers Manual July 2017 truncate_pagecache_range 9 4.1.27 truncate_pagecache_range unmap and remove pagecache that is hole-punched void truncate_pagecache_range struct inode * inode loff_t lstart loff_t lend inode inode lstart offset of beginning of hole lend offset of last byte of hole 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 July 2017 ipc_init 9 4.1.27 ipc_init initialise ipc subsystem int ipc_init void void no arguments The various sysv 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 July 2017 ipc_init_ids 9 4.1.27 ipc_init_ids initialise ipc identifiers void ipc_init_ids struct ipc_ids * ids ids ipc 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 July 2017 ipc_init_proc_interface 9 4.1.27 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 July 2017 ipc_findkey 9 4.1.27 ipc_findkey find a key in an ipc identifier set struct kern_ipc_perm * ipc_findkey struct ipc_ids * ids key_t key ids ipc identifier set key key to find Returns the locked pointer to the ipc structure if found or NULL otherwise. If key is found ipc points to the owning ipc structure Called with ipc_ids.rwsem held. Kernel Hackers Manual July 2017 ipc_get_maxid 9 4.1.27 ipc_get_maxid get the last assigned id int ipc_get_maxid struct ipc_ids * ids ids ipc identifier set Called with ipc_ids.rwsem held. Kernel Hackers Manual July 2017 ipc_addid 9 4.1.27 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 writer ipc_ids.rwsem held. Kernel Hackers Manual July 2017 ipcget_new 9 4.1.27 ipcget_new create a new ipc object int ipcget_new struct ipc_namespace * ns struct ipc_ids * ids const struct ipc_ops * ops struct ipc_params * params ns ipc namespace ids ipc identifier 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 July 2017 ipc_check_perms 9 4.1.27 ipc_check_perms check security and permissions for an ipc object int ipc_check_perms struct ipc_namespace * ns struct kern_ipc_perm * ipcp const struct ipc_ops * ops struct ipc_params * params ns ipc namespace 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 ds IDR. On success, the ipc id is returned. It is called with ipc_ids.rwsem and ipcp->lock held. Kernel Hackers Manual July 2017 ipcget_public 9 4.1.27 ipcget_public get an ipc object or create a new one int ipcget_public struct ipc_namespace * ns struct ipc_ids * ids const struct ipc_ops * ops struct ipc_params * params ns ipc namespace ids ipc identifier 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 July 2017 ipc_rmid 9 4.1.27 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.rwsem (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 July 2017 ipc_alloc 9 4.1.27 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 July 2017 ipc_free 9 4.1.27 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 July 2017 ipc_rcu_alloc 9 4.1.27 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 or NULL upon failure. Kernel Hackers Manual July 2017 ipcperms 9 4.1.27 ipcperms check ipc permissions int ipcperms struct ipc_namespace * ns struct kern_ipc_perm * ipcp short flag ns ipc namespace ipcp ipc permission set flag desired permission set Check user, group, other permissions for access to ipc resources. return 0 if allowed flag will most probably be 0 or S_...UGO from <linux/stat.h> Kernel Hackers Manual July 2017 kernel_to_ipc64_perm 9 4.1.27 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 July 2017 ipc64_perm_to_ipc_perm 9 4.1.27 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 July 2017 ipc_obtain_object 9 4.1.27 ipc_obtain_object struct kern_ipc_perm * ipc_obtain_object 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 return associated ipc object. Call inside the RCU critical section. The ipc object is *not* locked on exit. Kernel Hackers Manual July 2017 ipc_lock 9 4.1.27 ipc_lock lock an ipc structure without rwsem 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 successful exit. Kernel Hackers Manual July 2017 ipc_obtain_object_check 9 4.1.27 ipc_obtain_object_check struct kern_ipc_perm * ipc_obtain_object_check struct ipc_ids * ids int id ids ipc identifier set id ipc id to look for Similar to ipc_obtain_object but also checks the ipc object reference counter. Call inside the RCU critical section. The ipc object is *not* locked on exit. Kernel Hackers Manual July 2017 ipcget 9 4.1.27 ipcget Common sys_*get code int ipcget struct ipc_namespace * ns struct ipc_ids * ids const struct ipc_ops * ops struct ipc_params * params ns namespace 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 July 2017 ipc_update_perm 9 4.1.27 ipc_update_perm update the permissions of an ipc object int 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 July 2017 ipcctl_pre_down_nolock 9 4.1.27 ipcctl_pre_down_nolock retrieve an ipc and check permissions for some IPC_XXX cmd struct kern_ipc_perm * ipcctl_pre_down_nolock struct ipc_namespace * ns struct ipc_ids * ids int id int cmd struct ipc64_perm * perm int extra_perm ns ipc namespace 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 a pointer to the ipc object or otherwise, the corresponding error. Call holding the both the rwsem and the rcu read lock. Kernel Hackers Manual July 2017 ipc_parse_version 9 4.1.27 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 July 2017 DECLARE_KFIFO_PTR 9 4.1.27 DECLARE_KFIFO_PTR macro to declare a fifo pointer object DECLARE_KFIFO_PTR fifo type fifo name of the declared fifo type type of the fifo elements Kernel Hackers Manual July 2017 DECLARE_KFIFO 9 4.1.27 DECLARE_KFIFO macro to declare a fifo object DECLARE_KFIFO fifo type size fifo name of the declared fifo type type of the fifo elements size the number of elements in the fifo, this must be a power of 2 Kernel Hackers Manual July 2017 INIT_KFIFO 9 4.1.27 INIT_KFIFO Initialize a fifo declared by DECLARE_KFIFO INIT_KFIFO fifo fifo name of the declared fifo datatype Kernel Hackers Manual July 2017 DEFINE_KFIFO 9 4.1.27 DEFINE_KFIFO macro to define and initialize a fifo DEFINE_KFIFO fifo type size fifo name of the declared fifo datatype type type of the fifo elements size the number of elements in the fifo, this must be a power of 2 the macro can be used for global and local fifo data type variables. Kernel Hackers Manual July 2017 kfifo_initialized 9 4.1.27 kfifo_initialized Check if the fifo is initialized kfifo_initialized fifo fifo address of the fifo to check Return true if fifo is initialized, otherwise false. Assumes the fifo was 0 before. Kernel Hackers Manual July 2017 kfifo_esize 9 4.1.27 kfifo_esize returns the size of the element managed by the fifo kfifo_esize fifo fifo address of the fifo to be used Kernel Hackers Manual July 2017 kfifo_recsize 9 4.1.27 kfifo_recsize returns the size of the record length field kfifo_recsize fifo fifo address of the fifo to be used Kernel Hackers Manual July 2017 kfifo_size 9 4.1.27 kfifo_size returns the size of the fifo in elements kfifo_size fifo fifo address of the fifo to be used Kernel Hackers Manual July 2017 kfifo_reset 9 4.1.27 kfifo_reset removes the entire fifo content kfifo_reset fifo fifo address of the fifo to be used usage of kfifo_reset is dangerous. It should be only called when the fifo is exclusived locked or when it is secured that no other thread is accessing the fifo. Kernel Hackers Manual July 2017 kfifo_reset_out 9 4.1.27 kfifo_reset_out skip fifo content kfifo_reset_out fifo fifo address of the fifo to be used The usage of kfifo_reset_out is safe until it will be only called from the reader thread and there is only one concurrent reader. Otherwise it is dangerous and must be handled in the same way as kfifo_reset. Kernel Hackers Manual July 2017 kfifo_len 9 4.1.27 kfifo_len returns the number of used elements in the fifo kfifo_len fifo fifo address of the fifo to be used Kernel Hackers Manual July 2017 kfifo_is_empty 9 4.1.27 kfifo_is_empty returns true if the fifo is empty kfifo_is_empty fifo fifo address of the fifo to be used Kernel Hackers Manual July 2017 kfifo_is_full 9 4.1.27 kfifo_is_full returns true if the fifo is full kfifo_is_full fifo fifo address of the fifo to be used Kernel Hackers Manual July 2017 kfifo_avail 9 4.1.27 kfifo_avail returns the number of unused elements in the fifo kfifo_avail fifo fifo address of the fifo to be used Kernel Hackers Manual July 2017 kfifo_skip 9 4.1.27 kfifo_skip skip output data kfifo_skip fifo fifo address of the fifo to be used Kernel Hackers Manual July 2017 kfifo_peek_len 9 4.1.27 kfifo_peek_len gets the size of the next fifo record kfifo_peek_len fifo fifo address of the fifo to be used This function returns the size of the next fifo record in number of bytes. Kernel Hackers Manual July 2017 kfifo_alloc 9 4.1.27 kfifo_alloc dynamically allocates a new fifo buffer kfifo_alloc fifo size gfp_mask fifo pointer to the fifo size the number of elements in the fifo, this must be a power of 2 gfp_mask get_free_pages mask, passed to kmalloc This macro dynamically allocates a new fifo buffer. The numer of elements will be rounded-up to a power of 2. The fifo will be release with kfifo_free. Return 0 if no error, otherwise an error code. Kernel Hackers Manual July 2017 kfifo_free 9 4.1.27 kfifo_free frees the fifo kfifo_free fifo fifo the fifo to be freed Kernel Hackers Manual July 2017 kfifo_init 9 4.1.27 kfifo_init initialize a fifo using a preallocated buffer kfifo_init fifo buffer size fifo the fifo to assign the buffer buffer the preallocated buffer to be used size the size of the internal buffer, this have to be a power of 2 This macro initialize a fifo using a preallocated buffer. The numer of elements will be rounded-up to a power of 2. Return 0 if no error, otherwise an error code. Kernel Hackers Manual July 2017 kfifo_put 9 4.1.27 kfifo_put put data into the fifo kfifo_put fifo val fifo address of the fifo to be used val the data to be added This macro copies the given value into the fifo. It returns 0 if the fifo was full. Otherwise it returns the number processed elements. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macro. Kernel Hackers Manual July 2017 kfifo_get 9 4.1.27 kfifo_get get data from the fifo kfifo_get fifo val fifo address of the fifo to be used val address where to store the data This macro reads the data from the fifo. It returns 0 if the fifo was empty. Otherwise it returns the number processed elements. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macro. Kernel Hackers Manual July 2017 kfifo_peek 9 4.1.27 kfifo_peek get data from the fifo without removing kfifo_peek fifo val fifo address of the fifo to be used val address where to store the data This reads the data from the fifo without removing it from the fifo. It returns 0 if the fifo was empty. Otherwise it returns the number processed elements. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macro. Kernel Hackers Manual July 2017 kfifo_in 9 4.1.27 kfifo_in put data into the fifo kfifo_in fifo buf n fifo address of the fifo to be used buf the data to be added n number of elements to be added This macro copies the given buffer into the fifo and returns the number of copied elements. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macro. Kernel Hackers Manual July 2017 kfifo_in_spinlocked 9 4.1.27 kfifo_in_spinlocked put data into the fifo using a spinlock for locking kfifo_in_spinlocked fifo buf n lock fifo address of the fifo to be used buf the data to be added n number of elements to be added lock pointer to the spinlock to use for locking This macro copies the given values buffer into the fifo and returns the number of copied elements. Kernel Hackers Manual July 2017 kfifo_out 9 4.1.27 kfifo_out get data from the fifo kfifo_out fifo buf n fifo address of the fifo to be used buf pointer to the storage buffer n max. number of elements to get This macro get some data from the fifo and return the numbers of elements copied. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macro. Kernel Hackers Manual July 2017 kfifo_out_spinlocked 9 4.1.27 kfifo_out_spinlocked get data from the fifo using a spinlock for locking kfifo_out_spinlocked fifo buf n lock fifo address of the fifo to be used buf pointer to the storage buffer n max. number of elements to get lock pointer to the spinlock to use for locking This macro get the data from the fifo and return the numbers of elements copied. Kernel Hackers Manual July 2017 kfifo_from_user 9 4.1.27 kfifo_from_user puts some data from user space into the fifo kfifo_from_user fifo from len copied fifo address of the fifo to be used from pointer to the data to be added len the length of the data to be added copied pointer to output variable to store the number of copied bytes This macro copies at most len bytes from the from into the fifo, depending of the available space and returns -EFAULT/0. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macro. Kernel Hackers Manual July 2017 kfifo_to_user 9 4.1.27 kfifo_to_user copies data from the fifo into user space kfifo_to_user fifo to len copied fifo address of the fifo to be used to where the data must be copied len the size of the destination buffer copied pointer to output variable to store the number of copied bytes This macro copies at most len bytes from the fifo into the to buffer and returns -EFAULT/0. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macro. Kernel Hackers Manual July 2017 kfifo_dma_in_prepare 9 4.1.27 kfifo_dma_in_prepare setup a scatterlist for DMA input kfifo_dma_in_prepare fifo sgl nents len fifo address of the fifo to be used sgl pointer to the scatterlist array nents number of entries in the scatterlist array len number of elements to transfer This macro fills a scatterlist for DMA input. It returns the number entries in the scatterlist array. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macros. Kernel Hackers Manual July 2017 kfifo_dma_in_finish 9 4.1.27 kfifo_dma_in_finish finish a DMA IN operation kfifo_dma_in_finish fifo len fifo address of the fifo to be used len number of bytes to received This macro finish a DMA IN operation. The in counter will be updated by the len parameter. No error checking will be done. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macros. Kernel Hackers Manual July 2017 kfifo_dma_out_prepare 9 4.1.27 kfifo_dma_out_prepare setup a scatterlist for DMA output kfifo_dma_out_prepare fifo sgl nents len fifo address of the fifo to be used sgl pointer to the scatterlist array nents number of entries in the scatterlist array len number of elements to transfer This macro fills a scatterlist for DMA output which at most len bytes to transfer. It returns the number entries in the scatterlist array. A zero means there is no space available and the scatterlist is not filled. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macros. Kernel Hackers Manual July 2017 kfifo_dma_out_finish 9 4.1.27 kfifo_dma_out_finish finish a DMA OUT operation kfifo_dma_out_finish fifo len fifo address of the fifo to be used len number of bytes transferred This macro finish a DMA OUT operation. The out counter will be updated by the len parameter. No error checking will be done. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macros. Kernel Hackers Manual July 2017 kfifo_out_peek 9 4.1.27 kfifo_out_peek gets some data from the fifo kfifo_out_peek fifo buf n fifo address of the fifo to be used buf pointer to the storage buffer n max. number of elements to get This macro get the data from the fifo and return the numbers of elements copied. The data is not removed from the fifo. Note that with only one concurrent reader and one concurrent writer, you don't need extra locking to use these macro. 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 July 2017 relay_buf_full 9 4.1.27 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 July 2017 relay_reset 9 4.1.27 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 July 2017 relay_open 9 4.1.27 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 July 2017 relay_switch_subbuf 9 4.1.27 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 July 2017 relay_subbufs_consumed 9 4.1.27 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 July 2017 relay_close 9 4.1.27 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 July 2017 relay_flush 9 4.1.27 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 July 2017 relay_mmap_buf 9 4.1.27 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 July 2017 relay_alloc_buf 9 4.1.27 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 July 2017 relay_create_buf 9 4.1.27 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 July 2017 relay_destroy_channel 9 4.1.27 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 July 2017 relay_destroy_buf 9 4.1.27 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 July 2017 relay_remove_buf 9 4.1.27 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 filesystem, which also frees the rchan_buf_struct and the channel buffer. Should only be called from kref_put. Kernel Hackers Manual July 2017 relay_buf_empty 9 4.1.27 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 July 2017 wakeup_readers 9 4.1.27 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 July 2017 __relay_reset 9 4.1.27 __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 July 2017 relay_close_buf 9 4.1.27 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 July 2017 relay_hotcpu_callback 9 4.1.27 relay_hotcpu_callback CPU hotplug callback int 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 July 2017 relay_late_setup_files 9 4.1.27 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 July 2017 relay_file_open 9 4.1.27 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 July 2017 relay_file_mmap 9 4.1.27 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 July 2017 relay_file_poll 9 4.1.27 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 July 2017 relay_file_release 9 4.1.27 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 July 2017 relay_file_read_subbuf_avail 9 4.1.27 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 July 2017 relay_file_read_start_pos 9 4.1.27 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 July 2017 relay_file_read_end_pos 9 4.1.27 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 July 2017 __request_module 9 4.1.27 __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 July 2017 call_usermodehelper_setup 9 4.1.27 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 int (*init) struct subprocess_info *info, struct cred *new void (*cleanup) struct subprocess_info *info void * data path path to usermode executable argv arg vector for process envp environment for process gfp_mask gfp mask for memory allocation init an init function cleanup a cleanup function data arbitrary context sensitive data 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. The init function is used to customize the helper process prior to exec. A non-zero return code causes the process to error out, exit, and return the failure to the calling process The cleanup function is just before 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 July 2017 call_usermodehelper_exec 9 4.1.27 call_usermodehelper_exec start a usermode application int call_usermodehelper_exec struct subprocess_info * sub_info int wait sub_info information about the subprocessa wait wait for the application to finish and return status. when UMH_NO_WAIT 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 July 2017 call_usermodehelper 9 4.1.27 call_usermodehelper prepare and start a usermode application int call_usermodehelper char * path char ** argv char ** envp int wait path path to usermode executable argv arg vector for process envp environment for process wait wait for the application to finish and return status. when UMH_NO_WAIT 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. This function is the equivalent to use call_usermodehelper_setup and call_usermodehelper_exec. Refer to the file kernel/module.c for more information. Kernel Hackers Manual July 2017 synchronize_hardirq 9 4.1.27 synchronize_hardirq wait for pending hard IRQ handlers (on other CPUs) bool synchronize_hardirq unsigned int irq irq interrupt number to wait for This function waits for any pending hard 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. It does not take associated threaded handlers into account. Do not use this for shutdown scenarios where you must be sure that all parts (hardirq and threaded handler) have completed. false if a threaded handler is active. This function may be called - with care - from IRQ context. Kernel Hackers Manual July 2017 synchronize_irq 9 4.1.27 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 July 2017 irq_set_affinity_notifier 9 4.1.27 irq_set_affinity_notifier control notification of IRQ affinity changes int irq_set_affinity_notifier unsigned int irq struct irq_affinity_notify * notify irq Interrupt for which to enable/disable notification notify Context for notification, or NULL to disable notification. Function pointers must be initialised; the other fields will be initialised by this function. Must be called in process context. Notification may only be enabled after the IRQ is allocated and must be disabled before the IRQ is freed using free_irq. Kernel Hackers Manual July 2017 disable_irq_nosync 9 4.1.27 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 July 2017 disable_irq 9 4.1.27 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 July 2017 disable_hardirq 9 4.1.27 disable_hardirq disables an irq and waits for hardirq completion bool disable_hardirq unsigned int irq irq Interrupt to disable Disable the selected interrupt line. Enables and Disables are nested. This function waits for any pending hard IRQ handlers for this interrupt to complete before returning. If you use this function while holding a resource the hard IRQ handler may need you will deadlock. When used to optimistically disable an interrupt from atomic context the return value must be checked. false if a threaded handler is active. This function may be called - with care - from IRQ context. Kernel Hackers Manual July 2017 enable_irq 9 4.1.27 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->irq_data.chip->bus_lock and desc->chip->bus_sync_unlock are NULL ! Kernel Hackers Manual July 2017 irq_set_irq_wake 9 4.1.27 irq_set_irq_wake control irq power management wakeup int irq_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 July 2017 irq_wake_thread 9 4.1.27 irq_wake_thread wake the irq thread for the action identified by dev_id void irq_wake_thread unsigned int irq void * dev_id irq Interrupt line dev_id Device identity for which the thread should be woken Kernel Hackers Manual July 2017 setup_irq 9 4.1.27 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 July 2017 remove_irq 9 4.1.27 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 July 2017 free_irq 9 4.1.27 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 July 2017 request_threaded_irq 9 4.1.27 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 is 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_TRIGGER_* Specify active edge(s) or level Kernel Hackers Manual July 2017 request_any_context_irq 9 4.1.27 request_any_context_irq allocate an interrupt line int request_any_context_irq unsigned int irq irq_handler_t handler unsigned long flags const char * name void * dev_id irq Interrupt line to allocate handler Function to be called when the IRQ occurs. Threaded handler for threaded interrupts. flags Interrupt type flags name 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. It selects either a hardirq or threaded handling method depending on the context. On failure, it returns a negative value. On success, it returns either IRQC_IS_HARDIRQ or IRQC_IS_NESTED. Kernel Hackers Manual July 2017 request_dma 9 4.1.27 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 July 2017 free_dma 9 4.1.27 free_dma free a reserved system DMA channel void free_dma unsigned int dmanr dmanr DMA channel number Kernel Hackers Manual July 2017 request_resource_conflict 9 4.1.27 request_resource_conflict request and reserve an I/O or memory resource struct resource * request_resource_conflict struct resource * root struct resource * new root root resource descriptor new resource descriptor desired by caller Returns 0 for success, conflict resource on error. Kernel Hackers Manual July 2017 reallocate_resource 9 4.1.27 reallocate_resource allocate a slot in the resource tree given range & alignment. The resource will be relocated if the new size cannot be reallocated in the current location. int reallocate_resource struct resource * root struct resource * old resource_size_t newsize struct resource_constraint * constraint root root resource descriptor old resource descriptor desired by caller newsize new size of the resource descriptor constraint the size and alignment constraints to be met. Kernel Hackers Manual July 2017 lookup_resource 9 4.1.27 lookup_resource find an existing resource by a resource start address struct resource * lookup_resource struct resource * root resource_size_t start root root resource descriptor start resource start address Returns a pointer to the resource if found, NULL otherwise Kernel Hackers Manual July 2017 insert_resource_conflict 9 4.1.27 insert_resource_conflict Inserts resource in the resource tree struct resource * insert_resource_conflict struct resource * parent struct resource * new parent parent of the new resource new new resource to insert Returns 0 on success, conflict resource if the resource can't be inserted. This function is equivalent to request_resource_conflict 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 July 2017 insert_resource 9 4.1.27 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. Kernel Hackers Manual July 2017 insert_resource_expand_to_fit 9 4.1.27 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 July 2017 resource_alignment 9 4.1.27 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 July 2017 release_mem_region_adjustable 9 4.1.27 release_mem_region_adjustable release a previously reserved memory region int release_mem_region_adjustable struct resource * parent resource_size_t start resource_size_t size parent parent resource descriptor start resource start address size resource region size This interface is intended for memory hot-delete. The requested region is released from a currently busy memory resource. The requested region must either match exactly or fit into a single busy resource entry. In the latter case, the remaining resource is adjusted accordingly. Existing children of the busy memory resource must be immutable in the request. - Additional release conditions, such as overlapping region, can be supported after they are confirmed as valid cases. - When a busy memory resource gets split into two entries, the code assumes that all children remain in the lower address entry for simplicity. Enhance this logic when necessary. Kernel Hackers Manual July 2017 request_resource 9 4.1.27 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 July 2017 release_resource 9 4.1.27 release_resource release a previously reserved resource int release_resource struct resource * old old resource pointer Kernel Hackers Manual July 2017 allocate_resource 9 4.1.27 allocate_resource allocate empty slot in the resource tree given range & alignment. The resource will be reallocated with a new size if it was already allocated 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 resource_size_t (*alignf) void *, const 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 boundary to allocate max maximum boundary 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 July 2017 adjust_resource 9 4.1.27 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 July 2017 __request_region 9 4.1.27 __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 July 2017 __release_region 9 4.1.27 __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 currently busy region. Kernel Hackers Manual July 2017 devm_request_resource 9 4.1.27 devm_request_resource request and reserve an I/O or memory resource int devm_request_resource struct device * dev struct resource * root struct resource * new dev device for which to request the resource root root of the resource tree from which to request the resource new descriptor of the resource to request This is a device-managed version of request_resource. There is usually no need to release resources requested by this function explicitly since that will be taken care of when the device is unbound from its driver. If for some reason the resource needs to be released explicitly, because of ordering issues for example, drivers must call devm_release_resource rather than the regular release_resource. When a conflict is detected between any existing resources and the newly requested resource, an error message will be printed. Returns 0 on success or a negative error code on failure. Kernel Hackers Manual July 2017 devm_release_resource 9 4.1.27 devm_release_resource release a previously requested resource void devm_release_resource struct device * dev struct resource * new dev device for which to release the resource new descriptor of the resource to release Releases a resource previously requested using devm_request_resource. Kernel Hackers Manual July 2017 mtrr_add 9 4.1.27 mtrr_add Add a memory type region int mtrr_add unsigned long base unsigned long size unsigned int type bool increment base Physical base address of region size Physical size of region type Type of MTRR desired increment If this is true do usage counting on the region Memory type region registers control the caching on newer Intel and non Intel processors. This function allows drivers to request an MTRR is added. The details and hardware specifics of each processor's implementation are hidden from the caller, but nevertheless the caller should expect to need to provide a power of two size on an equivalent power of two boundary. If the region cannot be added either because all regions are in use or the CPU cannot support it a negative value is returned. On success the register number for this entry is returned, but should be treated as a cookie only. On a multiprocessor machine the changes are made to all processors. This is required on x86 by the Intel processors. The available types are MTRR_TYPE_UNCACHABLE - No caching MTRR_TYPE_WRBACK - Write data back in bursts whenever MTRR_TYPE_WRCOMB - Write data back soon but allow bursts MTRR_TYPE_WRTHROUGH - Cache reads but not writes Needs a quiet flag for the cases where drivers do not mind failures and do not wish system log messages to be sent. Kernel Hackers Manual July 2017 mtrr_del 9 4.1.27 mtrr_del delete a memory type region int mtrr_del int reg unsigned long base unsigned long size reg Register returned by mtrr_add base Physical base address size Size of region If register is supplied then base and size are ignored. This is how drivers should call it. Releases an MTRR region. If the usage count drops to zero the register is freed and the region returns to default state. On success the register is returned, on failure a negative error code. Kernel Hackers Manual July 2017 arch_phys_wc_add 9 4.1.27 arch_phys_wc_add add a WC MTRR and handle errors if PAT is unavailable int arch_phys_wc_add unsigned long base unsigned long size base Physical base address size Size of region If PAT is available, this does nothing. If PAT is unavailable, it attempts to add a WC MTRR covering size bytes starting at base and logs an error if this fails. Drivers must store the return value to pass to mtrr_del_wc_if_needed, but drivers should not try to interpret that return value. Kernel Hackers Manual July 2017 pci_bus_max_busnr 9 4.1.27 pci_bus_max_busnr returns maximum PCI bus number of given bus' children unsigned char pci_bus_max_busnr struct pci_bus * bus bus pointer to PCI bus structure to search Given a PCI bus, returns the highest PCI bus number present in the set including the given PCI bus and its list of child PCI buses. Kernel Hackers Manual July 2017 pci_find_capability 9 4.1.27 pci_find_capability query for devices' capabilities int pci_find_capability struct pci_dev * dev int cap dev PCI device to query cap capability code Tell if a device supports a given PCI capability. Returns the address of the requested capability structure within the device's PCI configuration space or 0 in case the device does not support it. Possible values for cap: PCI_CAP_ID_PM Power Management PCI_CAP_ID_AGP Accelerated Graphics Port PCI_CAP_ID_VPD Vital Product Data PCI_CAP_ID_SLOTID Slot Identification PCI_CAP_ID_MSI Message Signalled Interrupts PCI_CAP_ID_CHSWP CompactPCI HotSwap PCI_CAP_ID_PCIX PCI-X PCI_CAP_ID_EXP PCI Express Kernel Hackers Manual July 2017 pci_bus_find_capability 9 4.1.27 pci_bus_find_capability query for devices' capabilities int pci_bus_find_capability struct pci_bus * bus unsigned int devfn int cap bus the PCI bus to query devfn PCI device to query cap capability code Like pci_find_capability but works for pci devices that do not have a pci_dev structure set up yet. Returns the address of the requested capability structure within the device's PCI configuration space or 0 in case the device does not support it. Kernel Hackers Manual July 2017 pci_find_next_ext_capability 9 4.1.27 pci_find_next_ext_capability Find an extended capability int pci_find_next_ext_capability struct pci_dev * dev int start int cap dev PCI device to query start address at which to start looking (0 to start at beginning of list) cap capability code Returns the address of the next matching extended capability structure within the device's PCI configuration space or 0 if the device does not support it. Some capabilities can occur several times, e.g., the vendor-specific capability, and this provides a way to find them all. Kernel Hackers Manual July 2017 pci_find_ext_capability 9 4.1.27 pci_find_ext_capability Find an extended capability int pci_find_ext_capability struct pci_dev * dev int cap dev PCI device to query cap capability code Returns the address of the requested extended capability structure within the device's PCI configuration space or 0 if the device does not support it. Possible values for cap: PCI_EXT_CAP_ID_ERR Advanced Error Reporting PCI_EXT_CAP_ID_VC Virtual Channel PCI_EXT_CAP_ID_DSN Device Serial Number PCI_EXT_CAP_ID_PWR Power Budgeting Kernel Hackers Manual July 2017 pci_find_next_ht_capability 9 4.1.27 pci_find_next_ht_capability query a device's Hypertransport capabilities int pci_find_next_ht_capability struct pci_dev * dev int pos int ht_cap dev PCI device to query pos Position from which to continue searching ht_cap Hypertransport capability code To be used in conjunction with pci_find_ht_capability to search for all capabilities matching ht_cap. pos should always be a value returned from pci_find_ht_capability. NB. To be 100% safe against broken PCI devices, the caller should take steps to avoid an infinite loop. Kernel Hackers Manual July 2017 pci_find_ht_capability 9 4.1.27 pci_find_ht_capability query a device's Hypertransport capabilities int pci_find_ht_capability struct pci_dev * dev int ht_cap dev PCI device to query ht_cap Hypertransport capability code Tell if a device supports a given Hypertransport capability. Returns an address within the device's PCI configuration space or 0 in case the device does not support the request capability. The address points to the PCI capability, of type PCI_CAP_ID_HT, which has a Hypertransport capability matching ht_cap. Kernel Hackers Manual July 2017 pci_find_parent_resource 9 4.1.27 pci_find_parent_resource return resource region of parent bus of given region struct resource * pci_find_parent_resource const struct pci_dev * dev struct resource * res dev PCI device structure contains resources to be searched res child resource record for which parent is sought For given resource region of given device, return the resource region of parent bus the given region is contained in. Kernel Hackers Manual July 2017 __pci_complete_power_transition 9 4.1.27 __pci_complete_power_transition Complete power transition of a PCI device int __pci_complete_power_transition struct pci_dev * dev pci_power_t state dev PCI device to handle. state State to put the device into. This function should not be called directly by device drivers. Kernel Hackers Manual July 2017 pci_set_power_state 9 4.1.27 pci_set_power_state Set the power state of a PCI device int pci_set_power_state struct pci_dev * dev pci_power_t state dev PCI device to handle. state PCI power state (D0, D1, D2, D3hot) to put the device into. Transition a device to a new power state, using the platform firmware and/or the device's PCI PM registers. -EINVAL if the requested state is invalid. -EIO if device does not support PCI PM or its PM capabilities register has a wrong version, or device doesn't support the requested state. 0 if device already is in the requested state. 0 if device's power state has been successfully changed. Kernel Hackers Manual July 2017 pci_choose_state 9 4.1.27 pci_choose_state Choose the power state of a PCI device pci_power_t pci_choose_state struct pci_dev * dev pm_message_t state dev PCI device to be suspended state target sleep state for the whole system. This is the value that is passed to suspend function. Returns PCI power state suitable for given device and given system message. Kernel Hackers Manual July 2017 pci_save_state 9 4.1.27 pci_save_state save the PCI configuration space of a device before suspending int pci_save_state struct pci_dev * dev dev - PCI device that we're dealing with Kernel Hackers Manual July 2017 pci_restore_state 9 4.1.27 pci_restore_state Restore the saved state of a PCI device void pci_restore_state struct pci_dev * dev dev - PCI device that we're dealing with Kernel Hackers Manual July 2017 pci_store_saved_state 9 4.1.27 pci_store_saved_state Allocate and return an opaque struct containing the device saved state. struct pci_saved_state * pci_store_saved_state struct pci_dev * dev dev PCI device that we're dealing with Return NULL if no state or error. Kernel Hackers Manual July 2017 pci_load_saved_state 9 4.1.27 pci_load_saved_state Reload the provided save state into struct pci_dev. int pci_load_saved_state struct pci_dev * dev struct pci_saved_state * state dev PCI device that we're dealing with state Saved state returned from pci_store_saved_state Kernel Hackers Manual July 2017 pci_load_and_free_saved_state 9 4.1.27 pci_load_and_free_saved_state Reload the save state pointed to by state, and free the memory allocated for it. int pci_load_and_free_saved_state struct pci_dev * dev struct pci_saved_state ** state dev PCI device that we're dealing with state Pointer to saved state returned from pci_store_saved_state Kernel Hackers Manual July 2017 pci_reenable_device 9 4.1.27 pci_reenable_device Resume abandoned device int pci_reenable_device struct pci_dev * dev dev PCI device to be resumed Note this function is a backend of pci_default_resume and is not supposed to be called by normal code, write proper resume handler and use it instead. Kernel Hackers Manual July 2017 pci_enable_device_io 9 4.1.27 pci_enable_device_io Initialize a device for use with IO space int pci_enable_device_io struct pci_dev * dev dev PCI device to be initialized Initialize device before it's used by a driver. Ask low-level code to enable I/O resources. Wake up the device if it was suspended. Beware, this function can fail. Kernel Hackers Manual July 2017 pci_enable_device_mem 9 4.1.27 pci_enable_device_mem Initialize a device for use with Memory space int pci_enable_device_mem struct pci_dev * dev dev PCI device to be initialized Initialize device before it's used by a driver. Ask low-level code to enable Memory resources. Wake up the device if it was suspended. Beware, this function can fail. Kernel Hackers Manual July 2017 pci_enable_device 9 4.1.27 pci_enable_device Initialize device before it's used by a driver. int pci_enable_device struct pci_dev * dev dev PCI device to be initialized Initialize device before it's used by a driver. Ask low-level code to enable I/O and memory. Wake up the device if it was suspended. Beware, this function can fail. Note we don't actually enable the device many times if we call this function repeatedly (we just increment the count). Kernel Hackers Manual July 2017 pcim_enable_device 9 4.1.27 pcim_enable_device Managed pci_enable_device int pcim_enable_device struct pci_dev * pdev pdev PCI device to be initialized Managed pci_enable_device. Kernel Hackers Manual July 2017 pcim_pin_device 9 4.1.27 pcim_pin_device Pin managed PCI device void pcim_pin_device struct pci_dev * pdev pdev PCI device to pin Pin managed PCI device pdev. Pinned device won't be disabled on driver detach. pdev must have been enabled with pcim_enable_device. Kernel Hackers Manual July 2017 pci_disable_device 9 4.1.27 pci_disable_device Disable PCI device after use void pci_disable_device struct pci_dev * dev dev PCI device to be disabled Signal to the system that the PCI device is not in use by the system anymore. This only involves disabling PCI bus-mastering, if active. Note we don't actually disable the device until all callers of pci_enable_device have called pci_disable_device. Kernel Hackers Manual July 2017 pci_set_pcie_reset_state 9 4.1.27 pci_set_pcie_reset_state set reset state for device dev int pci_set_pcie_reset_state struct pci_dev * dev enum pcie_reset_state state dev the PCIe device reset state Reset state to enter into Sets the PCI reset state for the device. Kernel Hackers Manual July 2017 pci_pme_capable 9 4.1.27 pci_pme_capable check the capability of PCI device to generate PME# bool pci_pme_capable struct pci_dev * dev pci_power_t state dev PCI device to handle. state PCI state from which device will issue PME#. Kernel Hackers Manual July 2017 pci_pme_active 9 4.1.27 pci_pme_active enable or disable PCI device's PME# function void pci_pme_active struct pci_dev * dev bool enable dev PCI device to handle. enable 'true' to enable PME# generation; 'false' to disable it. The caller must verify that the device is capable of generating PME# before calling this function with enable equal to 'true'. Kernel Hackers Manual July 2017 __pci_enable_wake 9 4.1.27 __pci_enable_wake enable PCI device as wakeup event source int __pci_enable_wake struct pci_dev * dev pci_power_t state bool runtime bool enable dev PCI device affected state PCI state from which device will issue wakeup events runtime True if the events are to be generated at run time enable True to enable event generation; false to disable This enables the device as a wakeup event source, or disables it. When such events involves platform-specific hooks, those hooks are called automatically by this routine. Devices with legacy power management (no standard PCI PM capabilities) always require such platform hooks. 0 is returned on success -EINVAL is returned if device is not supposed to wake up the system Error code depending on the platform is returned if both the platform and the native mechanism fail to enable the generation of wake-up events Kernel Hackers Manual July 2017 pci_wake_from_d3 9 4.1.27 pci_wake_from_d3 enable/disable device to wake up from D3_hot or D3_cold int pci_wake_from_d3 struct pci_dev * dev bool enable dev PCI device to prepare enable True to enable wake-up event generation; false to disable Many drivers want the device to wake up the system from D3_hot or D3_cold and this function allows them to set that up cleanly - pci_enable_wake should not be called twice in a row to enable wake-up due to PCI PM vs ACPI ordering constraints. This function only returns error code if the device is not capable of generating PME# from both D3_hot and D3_cold, and the platform is unable to enable wake-up power for it. Kernel Hackers Manual July 2017 pci_prepare_to_sleep 9 4.1.27 pci_prepare_to_sleep prepare PCI device for system-wide transition into a sleep state int pci_prepare_to_sleep struct pci_dev * dev dev Device to handle. Choose the power state appropriate for the device depending on whether it can wake up the system and/or is power manageable by the platform (PCI_D3hot is the default) and put the device into that state. Kernel Hackers Manual July 2017 pci_back_from_sleep 9 4.1.27 pci_back_from_sleep turn PCI device on during system-wide transition into working state int pci_back_from_sleep struct pci_dev * dev dev Device to handle. Disable device's system wake-up capability and put it into D0. Kernel Hackers Manual July 2017 pci_dev_run_wake 9 4.1.27 pci_dev_run_wake Check if device can generate run-time wake-up events. bool pci_dev_run_wake struct pci_dev * dev dev Device to check. Return true if the device itself is capable of generating wake-up events (through the platform or using the native PCIe PME) or if the device supports PME and one of its upstream bridges can generate wake-up events. Kernel Hackers Manual July 2017 pci_common_swizzle 9 4.1.27 pci_common_swizzle swizzle INTx all the way to root bridge u8 pci_common_swizzle struct pci_dev * dev u8 * pinp dev the PCI device pinp pointer to the INTx pin value (1=INTA, 2=INTB, 3=INTD, 4=INTD) Perform INTx swizzling for a device. This traverses through all PCI-to-PCI bridges all the way up to a PCI root bus. Kernel Hackers Manual July 2017 pci_release_region 9 4.1.27 pci_release_region Release a PCI bar void pci_release_region struct pci_dev * pdev int bar pdev PCI device whose resources were previously reserved by pci_request_region bar BAR to release Releases the PCI I/O and memory resources previously reserved by a successful call to pci_request_region. Call this function only after all use of the PCI regions has ceased. Kernel Hackers Manual July 2017 pci_request_region 9 4.1.27 pci_request_region Reserve PCI I/O and memory resource int pci_request_region struct pci_dev * pdev int bar const char * res_name pdev PCI device whose resources are to be reserved bar BAR to be reserved res_name Name to be associated with resource Mark the PCI region associated with PCI device pdev BAR bar as being reserved by owner res_name. Do not access any address inside the PCI regions unless this call returns successfully. Returns 0 on success, or EBUSY on error. A warning message is also printed on failure. Kernel Hackers Manual July 2017 pci_request_region_exclusive 9 4.1.27 pci_request_region_exclusive Reserved PCI I/O and memory resource int pci_request_region_exclusive struct pci_dev * pdev int bar const char * res_name pdev PCI device whose resources are to be reserved bar BAR to be reserved res_name Name to be associated with resource. Mark the PCI region associated with PCI device pdev BR bar as being reserved by owner res_name. Do not access any address inside the PCI regions unless this call returns successfully. Returns 0 on success, or EBUSY on error. A warning message is also printed on failure. The key difference that _exclusive makes it that userspace is explicitly not allowed to map the resource via /dev/mem or sysfs. Kernel Hackers Manual July 2017 pci_release_selected_regions 9 4.1.27 pci_release_selected_regions Release selected PCI I/O and memory resources void pci_release_selected_regions struct pci_dev * pdev int bars pdev PCI device whose resources were previously reserved bars Bitmask of BARs to be released Release selected PCI I/O and memory resources previously reserved. Call this function only after all use of the PCI regions has ceased. Kernel Hackers Manual July 2017 pci_request_selected_regions 9 4.1.27 pci_request_selected_regions Reserve selected PCI I/O and memory resources int pci_request_selected_regions struct pci_dev * pdev int bars const char * res_name pdev PCI device whose resources are to be reserved bars Bitmask of BARs to be requested res_name Name to be associated with resource Kernel Hackers Manual July 2017 pci_release_regions 9 4.1.27 pci_release_regions Release reserved PCI I/O and memory resources void pci_release_regions struct pci_dev * pdev pdev PCI device whose resources were previously reserved by pci_request_regions Releases all PCI I/O and memory resources previously reserved by a successful call to pci_request_regions. Call this function only after all use of the PCI regions has ceased. Kernel Hackers Manual July 2017 pci_request_regions 9 4.1.27 pci_request_regions Reserved PCI I/O and memory resources int pci_request_regions struct pci_dev * pdev const char * res_name pdev PCI device whose resources are to be reserved res_name Name to be associated with resource. Mark all PCI regions associated with PCI device pdev as being reserved by owner res_name. Do not access any address inside the PCI regions unless this call returns successfully. Returns 0 on success, or EBUSY on error. A warning message is also printed on failure. Kernel Hackers Manual July 2017 pci_request_regions_exclusive 9 4.1.27 pci_request_regions_exclusive Reserved PCI I/O and memory resources int pci_request_regions_exclusive struct pci_dev * pdev const char * res_name pdev PCI device whose resources are to be reserved res_name Name to be associated with resource. Mark all PCI regions associated with PCI device pdev as being reserved by owner res_name. Do not access any address inside the PCI regions unless this call returns successfully. pci_request_regions_exclusive will mark the region so that /dev/mem and the sysfs MMIO access will not be allowed. Returns 0 on success, or EBUSY on error. A warning message is also printed on failure. Kernel Hackers Manual July 2017 pci_set_master 9 4.1.27 pci_set_master enables bus-mastering for device dev void pci_set_master struct pci_dev * dev dev the PCI device to enable Enables bus-mastering on the device and calls pcibios_set_master to do the needed arch specific settings. Kernel Hackers Manual July 2017 pci_clear_master 9 4.1.27 pci_clear_master disables bus-mastering for device dev void pci_clear_master struct pci_dev * dev dev the PCI device to disable Kernel Hackers Manual July 2017 pci_set_cacheline_size 9 4.1.27 pci_set_cacheline_size ensure the CACHE_LINE_SIZE register is programmed int pci_set_cacheline_size struct pci_dev * dev dev the PCI device for which MWI is to be enabled Helper function for pci_set_mwi. Originally copied from drivers/net/acenic.c. Copyright 1998-2001 by Jes Sorensen, <jestrained-monkey.org>. An appropriate -ERRNO error value on error, or zero for success. Kernel Hackers Manual July 2017 pci_set_mwi 9 4.1.27 pci_set_mwi enables memory-write-invalidate PCI transaction int pci_set_mwi struct pci_dev * dev dev the PCI device for which MWI is enabled Enables the Memory-Write-Invalidate transaction in PCI_COMMAND. An appropriate -ERRNO error value on error, or zero for success. Kernel Hackers Manual July 2017 pci_try_set_mwi 9 4.1.27 pci_try_set_mwi enables memory-write-invalidate PCI transaction int pci_try_set_mwi struct pci_dev * dev dev the PCI device for which MWI is enabled Enables the Memory-Write-Invalidate transaction in PCI_COMMAND. Callers are not required to check the return value. An appropriate -ERRNO error value on error, or zero for success. Kernel Hackers Manual July 2017 pci_clear_mwi 9 4.1.27 pci_clear_mwi disables Memory-Write-Invalidate for device dev void pci_clear_mwi struct pci_dev * dev dev the PCI device to disable Disables PCI Memory-Write-Invalidate transaction on the device Kernel Hackers Manual July 2017 pci_intx 9 4.1.27 pci_intx enables/disables PCI INTx for device dev void pci_intx struct pci_dev * pdev int enable pdev the PCI device to operate on enable boolean: whether to enable or disable PCI INTx Enables/disables PCI INTx for device dev Kernel Hackers Manual July 2017 pci_intx_mask_supported 9 4.1.27 pci_intx_mask_supported probe for INTx masking support bool pci_intx_mask_supported struct pci_dev * dev dev the PCI device to operate on Check if the device dev support INTx masking via the config space command word. Kernel Hackers Manual July 2017 pci_check_and_mask_intx 9 4.1.27 pci_check_and_mask_intx mask INTx on pending interrupt bool pci_check_and_mask_intx struct pci_dev * dev dev the PCI device to operate on Check if the device dev has its INTx line asserted, mask it and return true in that case. False is returned if not interrupt was pending. Kernel Hackers Manual July 2017 pci_check_and_unmask_intx 9 4.1.27 pci_check_and_unmask_intx unmask INTx if no interrupt is pending bool pci_check_and_unmask_intx struct pci_dev * dev dev the PCI device to operate on Check if the device dev has its INTx line asserted, unmask it if not and return true. False is returned and the mask remains active if there was still an interrupt pending. Kernel Hackers Manual July 2017 pci_msi_off 9 4.1.27 pci_msi_off disables any MSI or MSI-X capabilities void pci_msi_off struct pci_dev * dev dev the PCI device to operate on If you want to use MSI, see pci_enable_msi and friends. This is a lower-level primitive that allows us to disable MSI operation at the device level. Kernel Hackers Manual July 2017 pci_wait_for_pending_transaction 9 4.1.27 pci_wait_for_pending_transaction waits for pending transaction int pci_wait_for_pending_transaction struct pci_dev * dev dev the PCI device to operate on Return 0 if transaction is pending 1 otherwise. Kernel Hackers Manual July 2017 pci_reset_bridge_secondary_bus 9 4.1.27 pci_reset_bridge_secondary_bus Reset the secondary bus on a PCI bridge. void pci_reset_bridge_secondary_bus struct pci_dev * dev dev Bridge device Use the bridge control register to assert reset on the secondary bus. Devices on the secondary bus are left in power-on state. Kernel Hackers Manual July 2017 __pci_reset_function 9 4.1.27 __pci_reset_function reset a PCI device function int __pci_reset_function struct pci_dev * dev dev PCI device to reset Some devices allow an individual function to be reset without affecting other functions in the same device. The PCI device must be responsive to PCI config space in order to use this function. The device function is presumed to be unused when this function is called. Resetting the device will make the contents of PCI configuration space random, so any caller of this must be prepared to reinitialise the device including MSI, bus mastering, BARs, decoding IO and memory spaces, etc. Returns 0 if the device function was successfully reset or negative if the device doesn't support resetting a single function. Kernel Hackers Manual July 2017 __pci_reset_function_locked 9 4.1.27 __pci_reset_function_locked reset a PCI device function while holding the dev mutex lock. int __pci_reset_function_locked struct pci_dev * dev dev PCI device to reset Some devices allow an individual function to be reset without affecting other functions in the same device. The PCI device must be responsive to PCI config space in order to use this function. The device function is presumed to be unused and the caller is holding the device mutex lock when this function is called. Resetting the device will make the contents of PCI configuration space random, so any caller of this must be prepared to reinitialise the device including MSI, bus mastering, BARs, decoding IO and memory spaces, etc. Returns 0 if the device function was successfully reset or negative if the device doesn't support resetting a single function. Kernel Hackers Manual July 2017 pci_reset_function 9 4.1.27 pci_reset_function quiesce and reset a PCI device function int pci_reset_function struct pci_dev * dev dev PCI device to reset Some devices allow an individual function to be reset without affecting other functions in the same device. The PCI device must be responsive to PCI config space in order to use this function. This function does not just reset the PCI portion of a device, but clears all the state associated with the device. This function differs from __pci_reset_function in that it saves and restores device state over the reset. Returns 0 if the device function was successfully reset or negative if the device doesn't support resetting a single function. Kernel Hackers Manual July 2017 pci_try_reset_function 9 4.1.27 pci_try_reset_function quiesce and reset a PCI device function int pci_try_reset_function struct pci_dev * dev dev PCI device to reset Same as above, except return -EAGAIN if unable to lock device. Kernel Hackers Manual July 2017 pci_probe_reset_slot 9 4.1.27 pci_probe_reset_slot probe whether a PCI slot can be reset int pci_probe_reset_slot struct pci_slot * slot slot PCI slot to probe Return 0 if slot can be reset, negative if a slot reset is not supported. Kernel Hackers Manual July 2017 pci_reset_slot 9 4.1.27 pci_reset_slot reset a PCI slot int pci_reset_slot struct pci_slot * slot slot PCI slot to reset A PCI bus may host multiple slots, each slot may support a reset mechanism independent of other slots. For instance, some slots may support slot power control. In the case of a 1:1 bus to slot architecture, this function may wrap the bus reset to avoid spurious slot related events such as hotplug. Generally a slot reset should be attempted before a bus reset. All of the function of the slot and any subordinate buses behind the slot are reset through this function. PCI config space of all devices in the slot and behind the slot is saved before and restored after reset. Return 0 on success, non-zero on error. Kernel Hackers Manual July 2017 pci_try_reset_slot 9 4.1.27 pci_try_reset_slot Try to reset a PCI slot int pci_try_reset_slot struct pci_slot * slot slot PCI slot to reset Same as above except return -EAGAIN if the slot cannot be locked Kernel Hackers Manual July 2017 pci_probe_reset_bus 9 4.1.27 pci_probe_reset_bus probe whether a PCI bus can be reset int pci_probe_reset_bus struct pci_bus * bus bus PCI bus to probe Return 0 if bus can be reset, negative if a bus reset is not supported. Kernel Hackers Manual July 2017 pci_reset_bus 9 4.1.27 pci_reset_bus reset a PCI bus int pci_reset_bus struct pci_bus * bus bus top level PCI bus to reset Do a bus reset on the given bus and any subordinate buses, saving and restoring state of all devices. Return 0 on success, non-zero on error. Kernel Hackers Manual July 2017 pci_try_reset_bus 9 4.1.27 pci_try_reset_bus Try to reset a PCI bus int pci_try_reset_bus struct pci_bus * bus bus top level PCI bus to reset Same as above except return -EAGAIN if the bus cannot be locked Kernel Hackers Manual July 2017 pcix_get_max_mmrbc 9 4.1.27 pcix_get_max_mmrbc get PCI-X maximum designed memory read byte count int pcix_get_max_mmrbc struct pci_dev * dev dev PCI device to query maximum designed memory read count in bytes or appropriate error value. Kernel Hackers Manual July 2017 pcix_get_mmrbc 9 4.1.27 pcix_get_mmrbc get PCI-X maximum memory read byte count int pcix_get_mmrbc struct pci_dev * dev dev PCI device to query maximum memory read count in bytes or appropriate error value. Kernel Hackers Manual July 2017 pcix_set_mmrbc 9 4.1.27 pcix_set_mmrbc set PCI-X maximum memory read byte count int pcix_set_mmrbc struct pci_dev * dev int mmrbc dev PCI device to query mmrbc maximum memory read count in bytes valid values are 512, 1024, 2048, 4096 If possible sets maximum memory read byte count, some bridges have erratas that prevent this. Kernel Hackers Manual July 2017 pcie_get_readrq 9 4.1.27 pcie_get_readrq get PCI Express read request size int pcie_get_readrq struct pci_dev * dev dev PCI device to query Returns maximum memory read request in bytes or appropriate error value. Kernel Hackers Manual July 2017 pcie_set_readrq 9 4.1.27 pcie_set_readrq set PCI Express maximum memory read request int pcie_set_readrq struct pci_dev * dev int rq dev PCI device to query rq maximum memory read count in bytes valid values are 128, 256, 512, 1024, 2048, 4096 If possible sets maximum memory read request in bytes Kernel Hackers Manual July 2017 pcie_get_mps 9 4.1.27 pcie_get_mps get PCI Express maximum payload size int pcie_get_mps struct pci_dev * dev dev PCI device to query Returns maximum payload size in bytes Kernel Hackers Manual July 2017 pcie_set_mps 9 4.1.27 pcie_set_mps set PCI Express maximum payload size int pcie_set_mps struct pci_dev * dev int mps dev PCI device to query mps maximum payload size in bytes valid values are 128, 256, 512, 1024, 2048, 4096 If possible sets maximum payload size Kernel Hackers Manual July 2017 pcie_get_minimum_link 9 4.1.27 pcie_get_minimum_link determine minimum link settings of a PCI device int pcie_get_minimum_link struct pci_dev * dev enum pci_bus_speed * speed enum pcie_link_width * width dev PCI device to query speed storage for minimum speed width storage for minimum width This function will walk up the PCI device chain and determine the minimum link width and speed of the device. Kernel Hackers Manual July 2017 pci_select_bars 9 4.1.27 pci_select_bars Make BAR mask from the type of resource int pci_select_bars struct pci_dev * dev unsigned long flags dev the PCI device for which BAR mask is made flags resource type mask to be selected This helper routine makes bar mask from the type of resource. Kernel Hackers Manual July 2017 pci_add_dynid 9 4.1.27 pci_add_dynid add a new PCI device ID to this driver and re-probe devices int pci_add_dynid struct pci_driver * drv unsigned int vendor unsigned int device unsigned int subvendor unsigned int subdevice unsigned int class unsigned int class_mask unsigned long driver_data drv target pci driver vendor PCI vendor ID device PCI device ID subvendor PCI subvendor ID subdevice PCI subdevice ID class PCI class class_mask PCI class mask driver_data private driver data Adds a new dynamic pci device ID to this driver and causes the driver to probe for all devices again. drv must have been registered prior to calling this function. Does GFP_KERNEL allocation. 0 on success, -errno on failure. Kernel Hackers Manual July 2017 pci_match_id 9 4.1.27 pci_match_id See if a pci device matches a given pci_id table const struct pci_device_id * pci_match_id const struct pci_device_id * ids struct pci_dev * dev ids array of PCI device id structures to search in dev the PCI device structure to match against. Used by a driver to check whether a PCI device present in the system is in its list of supported devices. Returns the matching pci_device_id structure or NULL if there is no match. Deprecated, don't use this as it will not catch any dynamic ids that a driver might want to check for. Kernel Hackers Manual July 2017 __pci_register_driver 9 4.1.27 __pci_register_driver register a new pci driver int __pci_register_driver struct pci_driver * drv struct module * owner const char * mod_name drv the driver structure to register owner owner module of drv mod_name module name string Adds the driver structure to the list of registered drivers. Returns a negative value on error, otherwise 0. If no error occurred, the driver remains registered even if no device was claimed during registration. Kernel Hackers Manual July 2017 pci_unregister_driver 9 4.1.27 pci_unregister_driver unregister a pci driver void pci_unregister_driver struct pci_driver * drv drv the driver structure to unregister Deletes the driver structure from the list of registered PCI drivers, gives it a chance to clean up by calling its remove function for each device it was responsible for, and marks those devices as driverless. Kernel Hackers Manual July 2017 pci_dev_driver 9 4.1.27 pci_dev_driver get the pci_driver of a device struct pci_driver * pci_dev_driver const struct pci_dev * dev dev the device to query Returns the appropriate pci_driver structure or NULL if there is no registered driver for the device. Kernel Hackers Manual July 2017 pci_dev_get 9 4.1.27 pci_dev_get increments the reference count of the pci device structure struct pci_dev * pci_dev_get struct pci_dev * dev dev the device being referenced Each live reference to a device should be refcounted. Drivers for PCI devices should normally record such references in their probe methods, when they bind to a device, and release them by calling pci_dev_put, in their disconnect methods. A pointer to the device with the incremented reference counter is returned. Kernel Hackers Manual July 2017 pci_dev_put 9 4.1.27 pci_dev_put release a use of the pci device structure void pci_dev_put struct pci_dev * dev dev device that's been disconnected Must be called when a user of a device is finished with it. When the last user of the device calls this function, the memory of the device is freed. Kernel Hackers Manual July 2017 pci_stop_and_remove_bus_device 9 4.1.27 pci_stop_and_remove_bus_device remove a PCI device and any children void pci_stop_and_remove_bus_device struct pci_dev * dev dev the device to remove Remove a PCI device from the device lists, informing the drivers that the device has been removed. We also remove any subordinate buses and children in a depth-first manner. For each device we remove, delete the device structure from the device lists, remove the /proc entry, and notify userspace (/sbin/hotplug). Kernel Hackers Manual July 2017 pci_find_bus 9 4.1.27 pci_find_bus locate PCI bus from a given domain and bus number struct pci_bus * pci_find_bus int domain int busnr domain number of PCI domain to search busnr number of desired PCI bus Given a PCI bus number and domain number, the desired PCI bus is located in the global list of PCI buses. If the bus is found, a pointer to its data structure is returned. If no bus is found, NULL is returned. Kernel Hackers Manual July 2017 pci_find_next_bus 9 4.1.27 pci_find_next_bus begin or continue searching for a PCI bus struct pci_bus * pci_find_next_bus const struct pci_bus * from from Previous PCI bus found, or NULL for new search. Iterates through the list of known PCI buses. A new search is initiated by passing NULL as the from argument. Otherwise if from is not NULL, searches continue from next device on the global list. Kernel Hackers Manual July 2017 pci_get_slot 9 4.1.27 pci_get_slot locate PCI device for a given PCI slot struct pci_dev * pci_get_slot struct pci_bus * bus unsigned int devfn bus PCI bus on which desired PCI device resides devfn encodes number of PCI slot in which the desired PCI device resides and the logical device number within that slot in case of multi-function devices. Given a PCI bus and slot/function number, the desired PCI device is located in the list of PCI devices. If the device is found, its reference count is increased and this function returns a pointer to its data structure. The caller must decrement the reference count by calling pci_dev_put. If no device is found, NULL is returned. Kernel Hackers Manual July 2017 pci_get_domain_bus_and_slot 9 4.1.27 pci_get_domain_bus_and_slot locate PCI device for a given PCI domain (segment), bus, and slot struct pci_dev * pci_get_domain_bus_and_slot int domain unsigned int bus unsigned int devfn domain PCI domain/segment on which the PCI device resides. bus PCI bus on which desired PCI device resides devfn encodes number of PCI slot in which the desired PCI device resides and the logical device number within that slot in case of multi-function devices. Given a PCI domain, bus, and slot/function number, the desired PCI device is located in the list of PCI devices. If the device is found, its reference count is increased and this function returns a pointer to its data structure. The caller must decrement the reference count by calling pci_dev_put. If no device is found, NULL is returned. Kernel Hackers Manual July 2017 pci_get_subsys 9 4.1.27 pci_get_subsys begin or continue searching for a PCI device by vendor/subvendor/device/subdevice id struct pci_dev * pci_get_subsys unsigned int vendor unsigned int device unsigned int ss_vendor unsigned int ss_device struct pci_dev * from vendor PCI vendor id to match, or PCI_ANY_ID to match all vendor ids device PCI device id to match, or PCI_ANY_ID to match all device ids ss_vendor PCI subsystem vendor id to match, or PCI_ANY_ID to match all vendor ids ss_device PCI subsystem device id to match, or PCI_ANY_ID to match all device ids from Previous PCI device found in search, or NULL for new search. Iterates through the list of known PCI devices. If a PCI device is found with a matching vendor, device, ss_vendor and ss_device, a pointer to its device structure is returned, and the reference count to the device is incremented. Otherwise, NULL is returned. A new search is initiated by passing NULL as the from argument. Otherwise if from is not NULL, searches continue from next device on the global list. The reference count for from is always decremented if it is not NULL. Kernel Hackers Manual July 2017 pci_get_device 9 4.1.27 pci_get_device begin or continue searching for a PCI device by vendor/device id struct pci_dev * pci_get_device unsigned int vendor unsigned int device struct pci_dev * from vendor PCI vendor id to match, or PCI_ANY_ID to match all vendor ids device PCI device id to match, or PCI_ANY_ID to match all device ids from Previous PCI device found in search, or NULL for new search. Iterates through the list of known PCI devices. If a PCI device is found with a matching vendor and device, the reference count to the device is incremented and a pointer to its device structure is returned. Otherwise, NULL is returned. A new search is initiated by passing NULL as the from argument. Otherwise if from is not NULL, searches continue from next device on the global list. The reference count for from is always decremented if it is not NULL. Kernel Hackers Manual July 2017 pci_get_class 9 4.1.27 pci_get_class begin or continue searching for a PCI device by class struct pci_dev * pci_get_class unsigned int class struct pci_dev * from class search for a PCI device with this class designation from Previous PCI device found in search, or NULL for new search. Iterates through the list of known PCI devices. If a PCI device is found with a matching class, the reference count to the device is incremented and a pointer to its device structure is returned. Otherwise, NULL is returned. A new search is initiated by passing NULL as the from argument. Otherwise if from is not NULL, searches continue from next device on the global list. The reference count for from is always decremented if it is not NULL. Kernel Hackers Manual July 2017 pci_dev_present 9 4.1.27 pci_dev_present Returns 1 if device matching the device list is present, 0 if not. int pci_dev_present const struct pci_device_id * ids ids A pointer to a null terminated list of struct pci_device_id structures that describe the type of PCI device the caller is trying to find. You do not have a reference to any device that might be found by this function, so if that device is removed from the system right after this function is finished, the value will be stale. Use this function to find devices that are usually built into a system, or for a general hint as to if another device happens to be present at this specific moment in time. Kernel Hackers Manual July 2017 pci_msi_vec_count 9 4.1.27 pci_msi_vec_count Return the number of MSI vectors a device can send int pci_msi_vec_count struct pci_dev * dev dev device to report about This function returns the number of MSI vectors a device requested via Multiple Message Capable register. It returns a negative errno if the device is not capable sending MSI interrupts. Otherwise, the call succeeds and returns a power of two, up to a maximum of 2^5 (32), according to the MSI specification. Kernel Hackers Manual July 2017 pci_msix_vec_count 9 4.1.27 pci_msix_vec_count return the number of device's MSI-X table entries int pci_msix_vec_count struct pci_dev * dev dev pointer to the pci_dev data structure of MSI-X device function This function returns the number of device's MSI-X table entries and therefore the number of MSI-X vectors device is capable of sending. It returns a negative errno if the device is not capable of sending MSI-X interrupts. Kernel Hackers Manual July 2017 pci_enable_msix 9 4.1.27 pci_enable_msix configure device's MSI-X capability structure int pci_enable_msix struct pci_dev * dev struct msix_entry * entries int nvec dev pointer to the pci_dev data structure of MSI-X device function entries pointer to an array of MSI-X entries nvec number of MSI-X irqs requested for allocation by device driver Setup the MSI-X capability structure of device function with the number of requested irqs upon its software driver call to request for MSI-X mode enabled on its hardware device function. A return of zero indicates the successful configuration of MSI-X capability structure with new allocated MSI-X irqs. A return of < 0 indicates a failure. Or a return of > 0 indicates that driver request is exceeding the number of irqs or MSI-X vectors available. Driver should use the returned value to re-send its request. Kernel Hackers Manual July 2017 pci_msi_enabled 9 4.1.27 pci_msi_enabled is MSI enabled? int pci_msi_enabled void void no arguments Returns true if MSI has not been disabled by the command-line option pci=nomsi. Kernel Hackers Manual July 2017 pci_enable_msi_range 9 4.1.27 pci_enable_msi_range configure device's MSI capability structure int pci_enable_msi_range struct pci_dev * dev int minvec int maxvec dev device to configure minvec minimal number of interrupts to configure maxvec maximum number of interrupts to configure This function tries to allocate a maximum possible number of interrupts in a range between minvec and maxvec. It returns a negative errno if an error occurs. If it succeeds, it returns the actual number of interrupts allocated and updates the dev's irq member to the lowest new interrupt number; the other interrupt numbers allocated to this device are consecutive. Kernel Hackers Manual July 2017 pci_enable_msix_range 9 4.1.27 pci_enable_msix_range configure device's MSI-X capability structure int pci_enable_msix_range struct pci_dev * dev struct msix_entry * entries int minvec int maxvec dev pointer to the pci_dev data structure of MSI-X device function entries pointer to an array of MSI-X entries minvec minimum number of MSI-X irqs requested maxvec maximum number of MSI-X irqs requested Setup the MSI-X capability structure of device function with a maximum possible number of interrupts in the range between minvec and maxvec upon its software driver call to request for MSI-X mode enabled on its hardware device function. It returns a negative errno if an error occurs. If it succeeds, it returns the actual number of interrupts allocated and indicates the successful configuration of MSI-X capability structure with new allocated MSI-X interrupts. Kernel Hackers Manual July 2017 pci_bus_alloc_resource 9 4.1.27 pci_bus_alloc_resource allocate a resource from a parent bus int pci_bus_alloc_resource struct pci_bus * bus struct resource * res resource_size_t size resource_size_t align resource_size_t min unsigned long type_mask resource_size_t (*alignf) void *, const struct resource *, resource_size_t, resource_size_t void * alignf_data bus PCI bus res resource to allocate size size of resource to allocate align alignment of resource to allocate min minimum /proc/iomem address to allocate type_mask IORESOURCE_* type flags alignf resource alignment function alignf_data data argument for resource alignment function Given the PCI bus a device resides on, the size, minimum address, alignment and type, try to find an acceptable resource allocation for a specific device resource. Kernel Hackers Manual July 2017 pci_bus_add_device 9 4.1.27 pci_bus_add_device start driver for a single device void pci_bus_add_device struct pci_dev * dev dev device to add This adds add sysfs entries and start device drivers Kernel Hackers Manual July 2017 pci_bus_add_devices 9 4.1.27 pci_bus_add_devices start driver for PCI devices void pci_bus_add_devices const struct pci_bus * bus bus bus to check for new devices Start driver for PCI devices and add some sysfs entries. Kernel Hackers Manual July 2017 pci_bus_set_ops 9 4.1.27 pci_bus_set_ops Set raw operations of pci bus struct pci_ops * pci_bus_set_ops struct pci_bus * bus struct pci_ops * ops bus pci bus struct ops new raw operations Return previous raw operations Kernel Hackers Manual July 2017 pci_read_vpd 9 4.1.27 pci_read_vpd Read one entry from Vital Product Data ssize_t pci_read_vpd struct pci_dev * dev loff_t pos size_t count void * buf dev pci device struct pos offset in vpd space count number of bytes to read buf pointer to where to store result Kernel Hackers Manual July 2017 pci_write_vpd 9 4.1.27 pci_write_vpd Write entry to Vital Product Data ssize_t pci_write_vpd struct pci_dev * dev loff_t pos size_t count const void * buf dev pci device struct pos offset in vpd space count number of bytes to write buf buffer containing write data Kernel Hackers Manual July 2017 pci_cfg_access_lock 9 4.1.27 pci_cfg_access_lock Lock PCI config reads/writes void pci_cfg_access_lock struct pci_dev * dev dev pci device struct When access is locked, any userspace reads or writes to config space and concurrent lock requests will sleep until access is allowed via pci_cfg_access_unlocked again. Kernel Hackers Manual July 2017 pci_cfg_access_trylock 9 4.1.27 pci_cfg_access_trylock try to lock PCI config reads/writes bool pci_cfg_access_trylock struct pci_dev * dev dev pci device struct Same as pci_cfg_access_lock, but will return 0 if access is already locked, 1 otherwise. This function can be used from atomic contexts. Kernel Hackers Manual July 2017 pci_cfg_access_unlock 9 4.1.27 pci_cfg_access_unlock Unlock PCI config reads/writes void pci_cfg_access_unlock struct pci_dev * dev dev pci device struct This function allows PCI config accesses to resume. Kernel Hackers Manual July 2017 pci_lost_interrupt 9 4.1.27 pci_lost_interrupt reports a lost PCI interrupt enum pci_lost_interrupt_reason pci_lost_interrupt struct pci_dev * pdev pdev device whose interrupt is lost The primary function of this routine is to report a lost interrupt in a standard way which users can recognise (instead of blaming the driver). a suggestion for fixing it (although the driver is not required to act on this). Kernel Hackers Manual July 2017 __ht_create_irq 9 4.1.27 __ht_create_irq create an irq and attach it to a device. int __ht_create_irq struct pci_dev * dev int idx ht_irq_update_t * update dev The hypertransport device to find the irq capability on. idx Which of the possible irqs to attach to. update Function to be called when changing the htirq message The irq number of the new irq or a negative error value is returned. Kernel Hackers Manual July 2017 ht_create_irq 9 4.1.27 ht_create_irq create an irq and attach it to a device. int ht_create_irq struct pci_dev * dev int idx dev The hypertransport device to find the irq capability on. idx Which of the possible irqs to attach to. ht_create_irq needs to be called for all hypertransport devices that generate irqs. The irq number of the new irq or a negative error value is returned. Kernel Hackers Manual July 2017 ht_destroy_irq 9 4.1.27 ht_destroy_irq destroy an irq created with ht_create_irq void ht_destroy_irq unsigned int irq irq irq to be destroyed This reverses ht_create_irq removing the specified irq from existence. The irq should be free before this happens. Kernel Hackers Manual July 2017 pci_scan_slot 9 4.1.27 pci_scan_slot scan a PCI slot on a bus for devices. int pci_scan_slot struct pci_bus * bus int devfn bus PCI bus to scan devfn slot number to scan (must have zero function.) Scan a PCI slot on the specified PCI bus for devices, adding discovered devices to the bus->devices list. New devices will not have is_added set. Returns the number of new devices found. Kernel Hackers Manual July 2017 pci_rescan_bus 9 4.1.27 pci_rescan_bus scan a PCI bus for devices. unsigned int pci_rescan_bus struct pci_bus * bus bus PCI bus to scan Scan a PCI bus and child buses for new devices, adds them, and enables them. Returns the max number of subordinate bus discovered. Kernel Hackers Manual July 2017 pci_create_slot 9 4.1.27 pci_create_slot create or increment refcount for physical PCI slot struct pci_slot * pci_create_slot struct pci_bus * parent int slot_nr const char * name struct hotplug_slot * hotplug parent struct pci_bus of parent bridge slot_nr PCI_SLOT(pci_dev->devfn) or -1 for placeholder name user visible string presented in /sys/bus/pci/slots/<name> hotplug set if caller is hotplug driver, NULL otherwise PCI slots have first class attributes such as address, speed, width, and a struct pci_slot is used to manage them. This interface will either return a new struct pci_slot to the caller, or if the pci_slot already exists, its refcount will be incremented. Slots are uniquely identified by a pci_bus, slot_nr tuple. There are known platforms with broken firmware that assign the same name to multiple slots. Workaround these broken platforms by renaming the slots on behalf of the caller. If firmware assigns name N to The first slot is assigned N The second slot is assigned N-1 The third slot is assigned N-2 etc. In most cases, pci_bus, slot_nr will be sufficient to uniquely identify a slot. There is one notable exception - pSeries (rpaphp), where the slot_nr cannot be determined until a device is actually inserted into the slot. In this scenario, the caller may pass -1 for slot_nr. The following semantics are imposed when the caller passes slot_nr == -1. First, we no longer check for an existing struct pci_slot, as there may be many slots with slot_nr of -1. The other change in semantics is user-visible, which is the 'address' parameter presented in sysfs will bb tuple, where dddd is the PCI domain of the struct pci_bus and bb is the bus number. In other words, the devfn of the 'placeholder' slot will not be displayed. Kernel Hackers Manual July 2017 pci_destroy_slot 9 4.1.27 pci_destroy_slot decrement refcount for physical PCI slot void pci_destroy_slot struct pci_slot * slot slot struct pci_slot to decrement struct pci_slot is refcounted, so destroying them is really easy; we just call kobject_put on its kobj and let our release methods do the rest. Kernel Hackers Manual July 2017 pci_hp_create_module_link 9 4.1.27 pci_hp_create_module_link create symbolic link to the hotplug driver module. void pci_hp_create_module_link struct pci_slot * pci_slot pci_slot struct pci_slot Helper function for pci_hotplug_core.c to create symbolic link to the hotplug driver module. Kernel Hackers Manual July 2017 pci_hp_remove_module_link 9 4.1.27 pci_hp_remove_module_link remove symbolic link to the hotplug driver module. void pci_hp_remove_module_link struct pci_slot * pci_slot pci_slot struct pci_slot Helper function for pci_hotplug_core.c to remove symbolic link to the hotplug driver module. Kernel Hackers Manual July 2017 pci_enable_rom 9 4.1.27 pci_enable_rom enable ROM decoding for a PCI device int pci_enable_rom struct pci_dev * pdev pdev PCI device to enable Enable ROM decoding on dev. This involves simply turning on the last bit of the PCI ROM BAR. Note that some cards may share address decoders between the ROM and other resources, so enabling it may disable access to MMIO registers or other card memory. Kernel Hackers Manual July 2017 pci_disable_rom 9 4.1.27 pci_disable_rom disable ROM decoding for a PCI device void pci_disable_rom struct pci_dev * pdev pdev PCI device to disable Disable ROM decoding on a PCI device by turning off the last bit in the ROM BAR. Kernel Hackers Manual July 2017 pci_map_rom 9 4.1.27 pci_map_rom map a PCI ROM to kernel space void __iomem * pci_map_rom struct pci_dev * pdev size_t * size pdev pointer to pci device struct size pointer to receive size of pci window over ROM kernel virtual pointer to image of ROM Map a PCI ROM into kernel space. If ROM is boot video ROM, the shadow BIOS copy will be returned instead of the actual ROM. Kernel Hackers Manual July 2017 pci_unmap_rom 9 4.1.27 pci_unmap_rom unmap the ROM from kernel space void pci_unmap_rom struct pci_dev * pdev void __iomem * rom pdev pointer to pci device struct rom virtual address of the previous mapping Remove a mapping of a previously mapped ROM Kernel Hackers Manual July 2017 pci_platform_rom 9 4.1.27 pci_platform_rom provides a pointer to any ROM image provided by the platform void __iomem * pci_platform_rom struct pci_dev * pdev size_t * size pdev pointer to pci device struct size pointer to receive size of pci window over ROM Kernel Hackers Manual July 2017 pci_enable_sriov 9 4.1.27 pci_enable_sriov enable the SR-IOV capability int pci_enable_sriov struct pci_dev * dev int nr_virtfn dev the PCI device nr_virtfn number of virtual functions to enable Returns 0 on success, or negative on failure. Kernel Hackers Manual July 2017 pci_disable_sriov 9 4.1.27 pci_disable_sriov disable the SR-IOV capability void pci_disable_sriov struct pci_dev * dev dev the PCI device Kernel Hackers Manual July 2017 pci_num_vf 9 4.1.27 pci_num_vf return number of VFs associated with a PF device_release_driver int pci_num_vf struct pci_dev * dev dev the PCI device Returns number of VFs, or 0 if SR-IOV is not enabled. Kernel Hackers Manual July 2017 pci_vfs_assigned 9 4.1.27 pci_vfs_assigned returns number of VFs are assigned to a guest int pci_vfs_assigned struct pci_dev * dev dev the PCI device Returns number of VFs belonging to this device that are assigned to a guest. If device is not a physical function returns 0. Kernel Hackers Manual July 2017 pci_sriov_set_totalvfs 9 4.1.27 pci_sriov_set_totalvfs - reduce the TotalVFs available int pci_sriov_set_totalvfs struct pci_dev * dev u16 numvfs dev the PCI PF device numvfs number that should be used for TotalVFs supported Should be called from PF driver's probe routine with device's mutex held. Returns 0 if PF is an SRIOV-capable device and value of numvfs valid. If not a PF return -ENOSYS; if numvfs is invalid return -EINVAL; if VFs already enabled, return -EBUSY. Kernel Hackers Manual July 2017 pci_sriov_get_totalvfs 9 4.1.27 pci_sriov_get_totalvfs - get total VFs supported on this device int pci_sriov_get_totalvfs struct pci_dev * dev dev the PCI PF device For a PCIe device with SRIOV support, return the PCIe SRIOV capability value of TotalVFs or the value of driver_max_VFs if the driver reduced it. Otherwise 0. Kernel Hackers Manual July 2017 pci_read_legacy_io 9 4.1.27 pci_read_legacy_io read byte(s) from legacy I/O port space ssize_t pci_read_legacy_io struct file * filp struct kobject * kobj struct bin_attribute * bin_attr char * buf loff_t off size_t count filp open sysfs file kobj kobject corresponding to file to read from bin_attr struct bin_attribute for this file buf buffer to store results off offset into legacy I/O port space count number of bytes to read Reads 1, 2, or 4 bytes from legacy I/O port space using an arch specific callback routine (pci_legacy_read). Kernel Hackers Manual July 2017 pci_write_legacy_io 9 4.1.27 pci_write_legacy_io write byte(s) to legacy I/O port space ssize_t pci_write_legacy_io struct file * filp struct kobject * kobj struct bin_attribute * bin_attr char * buf loff_t off size_t count filp open sysfs file kobj kobject corresponding to file to read from bin_attr struct bin_attribute for this file buf buffer containing value to be written off offset into legacy I/O port space count number of bytes to write Writes 1, 2, or 4 bytes from legacy I/O port space using an arch specific callback routine (pci_legacy_write). Kernel Hackers Manual July 2017 pci_mmap_legacy_mem 9 4.1.27 pci_mmap_legacy_mem map legacy PCI memory into user memory space int pci_mmap_legacy_mem struct file * filp struct kobject * kobj struct bin_attribute * attr struct vm_area_struct * vma filp open sysfs file kobj kobject corresponding to device to be mapped attr struct bin_attribute for this file vma struct vm_area_struct passed to mmap Uses an arch specific callback, pci_mmap_legacy_mem_page_range, to mmap legacy memory space (first meg of bus space) into application virtual memory space. Kernel Hackers Manual July 2017 pci_mmap_legacy_io 9 4.1.27 pci_mmap_legacy_io map legacy PCI IO into user memory space int pci_mmap_legacy_io struct file * filp struct kobject * kobj struct bin_attribute * attr struct vm_area_struct * vma filp open sysfs file kobj kobject corresponding to device to be mapped attr struct bin_attribute for this file vma struct vm_area_struct passed to mmap Uses an arch specific callback, pci_mmap_legacy_io_page_range, to mmap legacy IO space (first meg of bus space) into application virtual memory space. Returns -ENOSYS if the operation isn't supported Kernel Hackers Manual July 2017 pci_adjust_legacy_attr 9 4.1.27 pci_adjust_legacy_attr adjustment of legacy file attributes void pci_adjust_legacy_attr struct pci_bus * b enum pci_mmap_state mmap_type b bus to create files under mmap_type I/O port or memory Stub implementation. Can be overridden by arch if necessary. Kernel Hackers Manual July 2017 pci_create_legacy_files 9 4.1.27 pci_create_legacy_files create legacy I/O port and memory files void pci_create_legacy_files struct pci_bus * b b bus to create files under Some platforms allow access to legacy I/O port and ISA memory space on a per-bus basis. This routine creates the files and ties them into their associated read, write and mmap files from pci-sysfs.c On error unwind, but don't propagate the error to the caller as it is ok to set up the PCI bus without these files. Kernel Hackers Manual July 2017 pci_mmap_resource 9 4.1.27 pci_mmap_resource map a PCI resource into user memory space int pci_mmap_resource struct kobject * kobj struct bin_attribute * attr struct vm_area_struct * vma int write_combine kobj kobject for mapping attr struct bin_attribute for the file being mapped vma struct vm_area_struct passed into the mmap write_combine 1 for write_combine mapping Use the regular PCI mapping routines to map a PCI resource into userspace. Kernel Hackers Manual July 2017 pci_remove_resource_files 9 4.1.27 pci_remove_resource_files cleanup resource files void pci_remove_resource_files struct pci_dev * pdev pdev dev to cleanup If we created resource files for pdev, remove them from sysfs and free their resources. Kernel Hackers Manual July 2017 pci_create_resource_files 9 4.1.27 pci_create_resource_files create resource files in sysfs for dev int pci_create_resource_files struct pci_dev * pdev pdev dev in question Walk the resources in pdev creating files for each resource available. Kernel Hackers Manual July 2017 pci_write_rom 9 4.1.27 pci_write_rom used to enable access to the PCI ROM display ssize_t pci_write_rom struct file * filp struct kobject * kobj struct bin_attribute * bin_attr char * buf loff_t off size_t count filp sysfs file kobj kernel object handle bin_attr struct bin_attribute for this file buf user input off file offset count number of byte in input writing anything except 0 enables it Kernel Hackers Manual July 2017 pci_read_rom 9 4.1.27 pci_read_rom read a PCI ROM ssize_t pci_read_rom struct file * filp struct kobject * kobj struct bin_attribute * bin_attr char * buf loff_t off size_t count filp sysfs file kobj kernel object handle bin_attr struct bin_attribute for this file buf where to put the data we read from the ROM off file offset count number of bytes to read Put count bytes starting at off into buf from the ROM in the PCI device corresponding to kobj. Kernel Hackers Manual July 2017 pci_remove_sysfs_dev_files 9 4.1.27 pci_remove_sysfs_dev_files cleanup PCI specific sysfs files void pci_remove_sysfs_dev_files struct pci_dev * pdev pdev device whose entries we should free Cleanup when pdev is removed from sysfs. Kernel Hackers Manual July 2017 __pci_hp_register 9 4.1.27 __pci_hp_register register a hotplug_slot with the PCI hotplug subsystem int __pci_hp_register struct hotplug_slot * slot struct pci_bus * bus int devnr const char * name struct module * owner const char * mod_name slot pointer to the struct hotplug_slot to register bus bus this slot is on devnr device number name name registered with kobject core owner caller module owner mod_name caller module name Registers a hotplug slot with the pci hotplug subsystem, which will allow userspace interaction to the slot. Returns 0 if successful, anything else for an error. Kernel Hackers Manual July 2017 pci_hp_deregister 9 4.1.27 pci_hp_deregister deregister a hotplug_slot with the PCI hotplug subsystem int pci_hp_deregister struct hotplug_slot * hotplug hotplug pointer to the struct hotplug_slot to deregister The slot must have been registered with the pci hotplug subsystem previously with a call to pci_hp_register. Returns 0 if successful, anything else for an error. Kernel Hackers Manual July 2017 pci_hp_change_slot_info 9 4.1.27 pci_hp_change_slot_info changes the slot's information structure in the core int pci_hp_change_slot_info struct hotplug_slot * hotplug struct hotplug_slot_info * info hotplug pointer to the slot whose info has changed info pointer to the info copy into the slot's info structure slot must have been registered with the pci hotplug subsystem previously with a call to pci_hp_register. Returns 0 if successful, anything else for an error. Kernel Hackers Manual July 2017 dmi_check_system 9 4.1.27 dmi_check_system check system DMI data int dmi_check_system const struct dmi_system_id * list list array of dmi_system_id structures to match against All non-null elements of the list must match their slot's (field index's) data (i.e., each list string must be a substring of the specified DMI slot's string data) to be considered a successful match. Walk the blacklist table running matching functions until someone returns non zero or we hit the end. Callback function is called for each successful match. Returns the number of matches. Kernel Hackers Manual July 2017 dmi_first_match 9 4.1.27 dmi_first_match find dmi_system_id structure matching system DMI data const struct dmi_system_id * dmi_first_match const struct dmi_system_id * list list array of dmi_system_id structures to match against All non-null elements of the list must match their slot's (field index's) data (i.e., each list string must be a substring of the specified DMI slot's string data) to be considered a successful match. Walk the blacklist table until the first match is found. Return the pointer to the matching entry or NULL if there's no match. Kernel Hackers Manual July 2017 dmi_get_system_info 9 4.1.27 dmi_get_system_info return DMI data value const char * dmi_get_system_info int field field data index (see enum dmi_field) Returns one DMI data value, can be used to perform complex DMI data checks. Kernel Hackers Manual July 2017 dmi_name_in_vendors 9 4.1.27 dmi_name_in_vendors Check if string is in the DMI system or board vendor name int dmi_name_in_vendors const char * str str Case sensitive Name Kernel Hackers Manual July 2017 dmi_find_device 9 4.1.27 dmi_find_device find onboard device by type/name const struct dmi_device * dmi_find_device int type const char * name const struct dmi_device * from type device type or DMI_DEV_TYPE_ANY to match all device types name device name string or NULL to match all from previous device found in search, or NULL for new search. Iterates through the list of known onboard devices. If a device is found with a matching vendor and device, a pointer to its device structure is returned. Otherwise, NULL is returned. A new search is initiated by passing NULL as the from argument. If from is not NULL, searches continue from next device. Kernel Hackers Manual July 2017 dmi_get_date 9 4.1.27 dmi_get_date parse a DMI date bool dmi_get_date int field int * yearp int * monthp int * dayp field data index (see enum dmi_field) yearp optional out parameter for the year monthp optional out parameter for the month dayp optional out parameter for the day The date field is assumed to be in the form resembling [mm[/dd]]/yy[yy] and the result is stored in the out parameters any or all of which can be omitted. If the field doesn't exist, all out parameters are set to zero and false is returned. Otherwise, true is returned with any invalid part of date set to zero. On return, year, month and day are guaranteed to be in the range of [0,9999], [0,12] and [0,31] respectively. Kernel Hackers Manual July 2017 dmi_walk 9 4.1.27 dmi_walk Walk the DMI table and get called back for every record int dmi_walk void (*decode) const struct dmi_header *, void * void * private_data decode Callback function private_data Private data to be passed to the callback function Returns -1 when the DMI table can't be reached, 0 on success. Kernel Hackers Manual July 2017 dmi_match 9 4.1.27 dmi_match compare a string to the dmi field (if exists) bool dmi_match enum dmi_field f const char * str f DMI field identifier str string to compare the DMI field to Returns true if the requested field equals to the str (including NULL). Kernel Hackers Manual July 2017 edd_show_raw_data 9 4.1.27 edd_show_raw_data copies raw data to buffer for userspace to parse ssize_t edd_show_raw_data struct edd_device * edev char * buf edev target edd_device buf output buffer number of bytes written, or -EINVAL on failure Kernel Hackers Manual July 2017 edd_release 9 4.1.27 edd_release free edd structure void edd_release struct kobject * kobj kobj kobject of edd structure This is called when the refcount of the edd structure reaches 0. This should happen right after we unregister, but just in case, we use the release callback anyway. Kernel Hackers Manual July 2017 edd_dev_is_type 9 4.1.27 edd_dev_is_type is this EDD device a 'type' device? int edd_dev_is_type struct edd_device * edev const char * type edev target edd_device type a host bus or interface identifier string per the EDD spec Returns 1 (TRUE) if it is a 'type' device, 0 otherwise. Kernel Hackers Manual July 2017 edd_get_pci_dev 9 4.1.27 edd_get_pci_dev finds pci_dev that matches edev struct pci_dev * edd_get_pci_dev struct edd_device * edev edev edd_device Returns pci_dev if found, or NULL Kernel Hackers Manual July 2017 edd_init 9 4.1.27 edd_init creates sysfs tree of EDD data int edd_init void void no arguments Kernel Hackers Manual July 2017 security_init 9 4.1.27 security_init initializes the security framework int security_init void void no arguments This should be called early in the kernel initialization sequence. Kernel Hackers Manual July 2017 security_module_enable 9 4.1.27 security_module_enable Load given security module on boot ? int security_module_enable struct security_operations * ops ops a pointer to the struct security_operations that is to be checked. Each LSM must pass this method before registering its own operations to avoid security registration races. This method may also be used to check if your LSM is currently loaded during kernel initialization. -The passed LSM is the one chosen by user at boot time, -or the passed LSM is configured as the default and the user did not choose an alternate LSM at boot time. Otherwise, return false. Kernel Hackers Manual July 2017 register_security 9 4.1.27 register_security registers a security framework with the kernel int register_security struct security_operations * ops ops a pointer to the struct security_options that is to be registered This function allows a security module to register itself with the kernel security subsystem. Some rudimentary checking is done on the ops value passed to this function. You'll need to check first if your LSM is allowed to register its ops by calling security_module_enable(ops). If there is already a security module registered with the kernel, an error will be returned. Otherwise 0 is returned on success. Kernel Hackers Manual July 2017 securityfs_create_file 9 4.1.27 securityfs_create_file create a file in the securityfs filesystem struct dentry * securityfs_create_file const char * name umode_t mode struct dentry * parent void * data const struct file_operations * fops name a pointer to a string containing the name of the file to create. mode the permission that the file should have parent a pointer to the parent dentry for this file. This should be a directory dentry if set. If this parameter is NULL, then the file will be created in the root of the securityfs filesystem. data a pointer to something that the caller will want to get to later on. The inode.i_private pointer will point to this value on the open call. fops a pointer to a struct file_operations that should be used for this file. This is the basic create a file function for securityfs. It allows for a wide range of flexibility in creating a file, or a directory (if you want to create a directory, the securityfs_create_dir function is recommended to be used instead). This function returns a pointer to a dentry if it succeeds. This pointer must be passed to the securityfs_remove function when the file is to be removed (no automatic cleanup happens if your module is unloaded, you are responsible here). If an error occurs, the function will return the error value (via ERR_PTR). If securityfs is not enabled in the kernel, the value -ENODEV is returned. Kernel Hackers Manual July 2017 securityfs_create_dir 9 4.1.27 securityfs_create_dir create a directory in the securityfs filesystem struct dentry * securityfs_create_dir const char * name struct dentry * parent name a pointer to a string containing the name of the directory to create. parent a pointer to the parent dentry for this file. This should be a directory dentry if set. If this parameter is NULL, then the directory will be created in the root of the securityfs filesystem. This function creates a directory in securityfs with the given name. This function returns a pointer to a dentry if it succeeds. This pointer must be passed to the securityfs_remove function when the file is to be removed (no automatic cleanup happens if your module is unloaded, you are responsible here). If an error occurs, NULL will be returned. If securityfs is not enabled in the kernel, the value -ENODEV is returned. It is not wise to check for this value, but rather, check for NULL or !NULL instead as to eliminate the need for #ifdef in the calling code. Kernel Hackers Manual July 2017 securityfs_remove 9 4.1.27 securityfs_remove removes a file or directory from the securityfs filesystem void securityfs_remove struct dentry * dentry dentry a pointer to a the dentry of the file or directory to be removed. This function removes a file or directory in securityfs that was previously created with a call to another securityfs function (like securityfs_create_file or variants thereof.) This function is required to be called in order for the file to be removed. No automatic cleanup of files will happen when a module is removed; you are responsible here. Kernel Hackers Manual July 2017 audit_log_start 9 4.1.27 audit_log_start obtain an audit buffer struct audit_buffer * audit_log_start struct audit_context * ctx gfp_t gfp_mask int type ctx audit_context (may be NULL) gfp_mask type of allocation type audit message type Returns audit_buffer pointer on success or NULL on error. Obtain an audit buffer. This routine does locking to obtain the audit buffer, but then no locking is required for calls to audit_log_*format. If the task (ctx) is a task that is currently in a syscall, then the syscall is marked as auditable and an audit record will be written at syscall exit. If there is no associated task, then task context (ctx) should be NULL. Kernel Hackers Manual July 2017 audit_log_format 9 4.1.27 audit_log_format format a message into the audit buffer. void audit_log_format struct audit_buffer * ab const char * fmt ... ab audit_buffer fmt format string @...: optional parameters matching fmt string ... variable arguments All the work is done in audit_log_vformat. Kernel Hackers Manual July 2017 audit_log_end 9 4.1.27 audit_log_end end one audit record void audit_log_end struct audit_buffer * ab ab the audit_buffer netlink_unicast cannot be called inside an irq context because it blocks (last arg, flags, is not set to MSG_DONTWAIT), so the audit buffer is placed on a queue and a tasklet is scheduled to remove them from the queue outside the irq context. May be called in any context. Kernel Hackers Manual July 2017 audit_log 9 4.1.27 audit_log Log an audit record void audit_log struct audit_context * ctx gfp_t gfp_mask int type const char * fmt ... ctx audit context gfp_mask type of allocation type audit message type fmt format string to use @...: variable parameters matching the format string ... variable arguments This is a convenience function that calls audit_log_start, audit_log_vformat, and audit_log_end. It may be called in any context. Kernel Hackers Manual July 2017 audit_log_secctx 9 4.1.27 audit_log_secctx Converts and logs SELinux context void audit_log_secctx struct audit_buffer * ab u32 secid ab audit_buffer secid security number This is a helper function that calls security_secid_to_secctx to convert secid to secctx and then adds the (converted) SELinux context to the audit log by calling audit_log_format, thus also preventing leak of internal secid to userspace. If secid cannot be converted audit_panic is called. Kernel Hackers Manual July 2017 audit_alloc 9 4.1.27 audit_alloc allocate an audit context block for a task int audit_alloc struct task_struct * tsk tsk task Filter on the task information and allocate a per-task audit context if necessary. Doing so turns on system call auditing for the specified task. This is called from copy_process, so no lock is needed. Kernel Hackers Manual July 2017 __audit_free 9 4.1.27 __audit_free free a per-task audit context void __audit_free struct task_struct * tsk tsk task whose audit context block to free Called from copy_process and do_exit Kernel Hackers Manual July 2017 __audit_syscall_entry 9 4.1.27 __audit_syscall_entry fill in an audit record at syscall entry void __audit_syscall_entry int major unsigned long a1 unsigned long a2 unsigned long a3 unsigned long a4 major major syscall type (function) a1 additional syscall register 1 a2 additional syscall register 2 a3 additional syscall register 3 a4 additional syscall register 4 Fill in audit context at syscall entry. This only happens if the audit context was created when the task was created and the state or filters demand the audit context be built. If the state from the per-task filter or from the per-syscall filter is AUDIT_RECORD_CONTEXT, then the record will be written at syscall exit time (otherwise, it will only be written if another part of the kernel requests that it be written). Kernel Hackers Manual July 2017 __audit_syscall_exit 9 4.1.27 __audit_syscall_exit deallocate audit context after a system call void __audit_syscall_exit int success long return_code success success value of the syscall return_code return value of the syscall Tear down after system call. If the audit context has been marked as auditable (either because of the AUDIT_RECORD_CONTEXT state from filtering, or because some other part of the kernel wrote an audit message), then write out the syscall information. In call cases, free the names stored from getname. Kernel Hackers Manual July 2017 __audit_reusename 9 4.1.27 __audit_reusename fill out filename with info from existing entry struct filename * __audit_reusename const __user char * uptr uptr userland ptr to pathname Search the audit_names list for the current audit context. If there is an existing entry with a matching uptr then return the filename associated with that audit_name. If not, return NULL. Kernel Hackers Manual July 2017 __audit_getname 9 4.1.27 __audit_getname add a name to the list void __audit_getname struct filename * name name name to add Add a name to the list of audit names for this context. Called from fs/namei.c:getname. Kernel Hackers Manual July 2017 __audit_inode 9 4.1.27 __audit_inode store the inode and device from a lookup void __audit_inode struct filename * name const struct dentry * dentry unsigned int flags name name being audited dentry dentry being audited flags attributes for this particular entry Kernel Hackers Manual July 2017 auditsc_get_stamp 9 4.1.27 auditsc_get_stamp get local copies of audit_context values int auditsc_get_stamp struct audit_context * ctx struct timespec * t unsigned int * serial ctx audit_context for the task t timespec to store time recorded in the audit_context serial serial value that is recorded in the audit_context Also sets the context as auditable. Kernel Hackers Manual July 2017 audit_set_loginuid 9 4.1.27 audit_set_loginuid set current task's audit_context loginuid int audit_set_loginuid kuid_t loginuid loginuid loginuid value Returns 0. Called (set) from fs/proc/base.c::proc_loginuid_write. Kernel Hackers Manual July 2017 __audit_mq_open 9 4.1.27 __audit_mq_open record audit data for a POSIX MQ open void __audit_mq_open int oflag umode_t mode struct mq_attr * attr oflag open flag mode mode bits attr queue attributes Kernel Hackers Manual July 2017 __audit_mq_sendrecv 9 4.1.27 __audit_mq_sendrecv record audit data for a POSIX MQ timed send/receive void __audit_mq_sendrecv mqd_t mqdes size_t msg_len unsigned int msg_prio const struct timespec * abs_timeout mqdes MQ descriptor msg_len Message length msg_prio Message priority abs_timeout Message timeout in absolute time Kernel Hackers Manual July 2017 __audit_mq_notify 9 4.1.27 __audit_mq_notify record audit data for a POSIX MQ notify void __audit_mq_notify mqd_t mqdes const struct sigevent * notification mqdes MQ descriptor notification Notification event Kernel Hackers Manual July 2017 __audit_mq_getsetattr 9 4.1.27 __audit_mq_getsetattr record audit data for a POSIX MQ get/set attribute void __audit_mq_getsetattr mqd_t mqdes struct mq_attr * mqstat mqdes MQ descriptor mqstat MQ flags Kernel Hackers Manual July 2017 __audit_ipc_obj 9 4.1.27 __audit_ipc_obj record audit data for ipc object void __audit_ipc_obj struct kern_ipc_perm * ipcp ipcp ipc permissions Kernel Hackers Manual July 2017 __audit_ipc_set_perm 9 4.1.27 __audit_ipc_set_perm record audit data for new ipc permissions void __audit_ipc_set_perm unsigned long qbytes uid_t uid gid_t gid umode_t mode qbytes msgq bytes uid msgq user id gid msgq group id mode msgq mode (permissions) Called only after audit_ipc_obj. Kernel Hackers Manual July 2017 __audit_socketcall 9 4.1.27 __audit_socketcall record audit data for sys_socketcall int __audit_socketcall int nargs unsigned long * args nargs number of args, which should not be more than AUDITSC_ARGS. args args array Kernel Hackers Manual July 2017 __audit_fd_pair 9 4.1.27 __audit_fd_pair record audit data for pipe and socketpair void __audit_fd_pair int fd1 int fd2 fd1 the first file descriptor fd2 the second file descriptor Kernel Hackers Manual July 2017 __audit_sockaddr 9 4.1.27 __audit_sockaddr record audit data for sys_bind, sys_connect, sys_sendto int __audit_sockaddr int len void * a len data length in user space a data address in kernel space Returns 0 for success or NULL context or < 0 on error. Kernel Hackers Manual July 2017 __audit_signal_info 9 4.1.27 __audit_signal_info record signal info for shutting down audit subsystem int __audit_signal_info int sig struct task_struct * t sig signal value t task being signaled If the audit subsystem is being terminated, record the task (pid) and uid that is doing that. Kernel Hackers Manual July 2017 __audit_log_bprm_fcaps 9 4.1.27 __audit_log_bprm_fcaps store information about a loading bprm and relevant fcaps int __audit_log_bprm_fcaps struct linux_binprm * bprm const struct cred * new const struct cred * old bprm pointer to the bprm being processed new the proposed new credentials old the old credentials Simply check if the proc already has the caps given by the file and if not store the priv escalation info for later auditing at the end of the syscall -Eric Kernel Hackers Manual July 2017 __audit_log_capset 9 4.1.27 __audit_log_capset store information about the arguments to the capset syscall void __audit_log_capset const struct cred * new const struct cred * old new the new credentials old the old (current) credentials Record the arguments userspace sent to sys_capset for later printing by the audit system if applicable Kernel Hackers Manual July 2017 audit_core_dumps 9 4.1.27 audit_core_dumps record information about processes that end abnormally void audit_core_dumps long signr signr signal value If a process ends with a core dump, something fishy is going on and we should record the event for investigation. Kernel Hackers Manual July 2017 audit_rule_change 9 4.1.27 audit_rule_change apply all rules to the specified message type int audit_rule_change int type __u32 portid int seq void * data size_t datasz type audit message type portid target port id for netlink audit messages seq netlink audit message sequence (serial) number data payload data datasz size of payload data Kernel Hackers Manual July 2017 audit_list_rules_send 9 4.1.27 audit_list_rules_send list the audit rules int audit_list_rules_send struct sk_buff * request_skb int seq request_skb skb of request we are replying to (used to target the reply) seq netlink audit message sequence (serial) number Kernel Hackers Manual July 2017 parent_len 9 4.1.27 parent_len find the length of the parent portion of a pathname int parent_len const char * path path pathname of which to determine length Kernel Hackers Manual July 2017 audit_compare_dname_path 9 4.1.27 audit_compare_dname_path compare given dentry name with last component in given path. Return of 0 indicates a match. int audit_compare_dname_path const char * dname const char * path int parentlen dname dentry name that we're comparing path full pathname that we're comparing parentlen length of the parent if known. Passing in AUDIT_NAME_FULL here indicates that we must compute this value. Kernel Hackers Manual July 2017 sys_acct 9 4.1.27 sys_acct enable/disable process accounting long sys_acct const char __user * name name file name for accounting records or NULL to shutdown accounting Returns 0 for success or negative errno values for failure. sys_acct is the only system call needed to implement process accounting. It takes the name of the file where accounting records should be written. If the filename is NULL, accounting will be shutdown. Kernel Hackers Manual July 2017 acct_collect 9 4.1.27 acct_collect collect accounting information into pacct_struct void acct_collect long exitcode int group_dead exitcode task exit code group_dead not 0, if this thread is the last one in the process. Kernel Hackers Manual July 2017 acct_process 9 4.1.27 acct_process void acct_process void void no arguments handles process accounting for an exiting task Kernel Hackers Manual July 2017 blk_get_backing_dev_info 9 4.1.27 blk_get_backing_dev_info get the address of a queue's backing_dev_info struct backing_dev_info * blk_get_backing_dev_info struct block_device * bdev bdev device Locates the passed device's request queue and returns the address of its backing_dev_info. This function can only be called if bdev is opened and the return value is never NULL. Kernel Hackers Manual July 2017 blk_delay_queue 9 4.1.27 blk_delay_queue restart queueing after defined interval void blk_delay_queue struct request_queue * q unsigned long msecs q The struct request_queue in question msecs Delay in msecs Sometimes queueing needs to be postponed for a little while, to allow resources to come back. This function will make sure that queueing is restarted around the specified time. Queue lock must be held. Kernel Hackers Manual July 2017 blk_start_queue 9 4.1.27 blk_start_queue restart a previously stopped queue void blk_start_queue struct request_queue * q q The struct request_queue in question blk_start_queue will clear the stop flag on the queue, and call the request_fn for the queue if it was in a stopped state when entered. Also see blk_stop_queue. Queue lock must be held. Kernel Hackers Manual July 2017 blk_stop_queue 9 4.1.27 blk_stop_queue stop a queue void blk_stop_queue struct request_queue * q q The struct request_queue in question The Linux block layer assumes that a block driver will consume all entries on the request queue when the request_fn strategy is called. Often this will not happen, because of hardware limitations (queue depth settings). If a device driver gets a 'queue full' response, or if it simply chooses not to queue more I/O at one point, it can call this function to prevent the request_fn from being called until the driver has signalled it's ready to go again. This happens by calling blk_start_queue to restart queue operations. Queue lock must be held. Kernel Hackers Manual July 2017 blk_sync_queue 9 4.1.27 blk_sync_queue cancel any pending callbacks on a queue void blk_sync_queue struct request_queue * q q the queue The block layer may perform asynchronous callback activity on a queue, such as calling the unplug function after a timeout. A block device may call blk_sync_queue to ensure that any such activity is cancelled, thus allowing it to release resources that the callbacks might use. The caller must already have made sure that its ->make_request_fn will not re-add plugging prior to calling this function. This function does not cancel any asynchronous activity arising out of elevator or throttling code. That would require elevator_exit and blkcg_exit_queue to be called with queue lock initialized. Kernel Hackers Manual July 2017 __blk_run_queue 9 4.1.27 __blk_run_queue run a single device queue void __blk_run_queue struct request_queue * q q The queue to run See blk_run_queue. This variant must be called with the queue lock held and interrupts disabled. Kernel Hackers Manual July 2017 blk_run_queue_async 9 4.1.27 blk_run_queue_async run a single device queue in workqueue context void blk_run_queue_async struct request_queue * q q The queue to run Tells kblockd to perform the equivalent of blk_run_queue on behalf of us. The caller must hold the queue lock. Kernel Hackers Manual July 2017 blk_run_queue 9 4.1.27 blk_run_queue run a single device queue void blk_run_queue struct request_queue * q q The queue to run Invoke request handling on this queue, if it has pending work to do. May be used to restart queueing when a request has completed. Kernel Hackers Manual July 2017 blk_queue_bypass_start 9 4.1.27 blk_queue_bypass_start enter queue bypass mode void blk_queue_bypass_start struct request_queue * q q queue of interest In bypass mode, only the dispatch FIFO queue of q is used. This function makes q enter bypass mode and drains all requests which were throttled or issued before. On return, it's guaranteed that no request is being throttled or has ELVPRIV set and blk_queue_bypass true inside queue or RCU read lock. Kernel Hackers Manual July 2017 blk_queue_bypass_end 9 4.1.27 blk_queue_bypass_end leave queue bypass mode void blk_queue_bypass_end struct request_queue * q q queue of interest Leave bypass mode and restore the normal queueing behavior. Kernel Hackers Manual July 2017 blk_cleanup_queue 9 4.1.27 blk_cleanup_queue shutdown a request queue void blk_cleanup_queue struct request_queue * q q request queue to shutdown Mark q DYING, drain all pending requests, mark q DEAD, destroy and put it. All future requests will be failed immediately with -ENODEV. Kernel Hackers Manual July 2017 blk_init_queue 9 4.1.27 blk_init_queue prepare a request queue for use with a block device struct request_queue * blk_init_queue request_fn_proc * rfn spinlock_t * lock rfn The function to be called to process requests that have been placed on the queue. lock Request queue spin lock If a block device wishes to use the standard request handling procedures, which sorts requests and coalesces adjacent requests, then it must call blk_init_queue. The function rfn will be called when there are requests on the queue that need to be processed. If the device supports plugging, then rfn may not be called immediately when requests are available on the queue, but may be called at some time later instead. Plugged queues are generally unplugged when a buffer belonging to one of the requests on the queue is needed, or due to memory pressure. rfn is not required, or even expected, to remove all requests off the queue, but only as many as it can handle at a time. If it does leave requests on the queue, it is responsible for arranging that the requests get dealt with eventually. The queue spin lock must be held while manipulating the requests on the request queue; this lock will be taken also from interrupt context, so irq disabling is needed for it. Function returns a pointer to the initialized request queue, or NULL if it didn't succeed. blk_init_queue must be paired with a blk_cleanup_queue call when the block device is deactivated (such as at module unload). Kernel Hackers Manual July 2017 blk_make_request 9 4.1.27 blk_make_request given a bio, allocate a corresponding struct request. struct request * blk_make_request struct request_queue * q struct bio * bio gfp_t gfp_mask q target request queue bio The bio describing the memory mappings that will be submitted for IO. It may be a chained-bio properly constructed by block/bio layer. gfp_mask gfp flags to be used for memory allocation blk_make_request is the parallel of generic_make_request for BLOCK_PC type commands. Where the struct request needs to be farther initialized by the caller. It is passed a struct bio, which describes the memory info of the I/O transfer. The caller of blk_make_request must make sure that bi_io_vec are set to describe the memory buffers. That bio_data_dir will return the needed direction of the request. (And all bio's in the passed bio-chain are properly set accordingly) If called under none-sleepable conditions, mapped bio buffers must not need bouncing, by calling the appropriate masked or flagged allocator, suitable for the target device. Otherwise the call to blk_queue_bounce will BUG. When allocating/cloning a bio-chain, careful consideration should be given to how you allocate bios. In particular, you cannot use __GFP_WAIT for anything but the first bio in the chain. Otherwise you risk waiting for IO completion of a bio that hasn't been submitted yet, thus resulting in a deadlock. Alternatively bios should be allocated using bio_kmalloc instead of bio_alloc, as that avoids the mempool deadlock. If possible a big IO should be split into smaller parts when allocation fails. Partial allocation should not be an error, or you risk a live-lock. Kernel Hackers Manual July 2017 blk_rq_set_block_pc 9 4.1.27 blk_rq_set_block_pc initialize a request to type BLOCK_PC void blk_rq_set_block_pc struct request * rq rq request to be initialized Kernel Hackers Manual July 2017 blk_requeue_request 9 4.1.27 blk_requeue_request put a request back on queue void blk_requeue_request struct request_queue * q struct request * rq q request queue where request should be inserted rq request to be inserted Drivers often keep queueing requests until the hardware cannot accept more, when that condition happens we need to put the request back on the queue. Must be called with queue lock held. Kernel Hackers Manual July 2017 part_round_stats 9 4.1.27 part_round_stats Round off the performance stats on a struct disk_stats. void part_round_stats int cpu struct hd_struct * part cpu cpu number for stats access part target partition The average IO queue length and utilisation statistics are maintained by observing the current state of the queue length and the amount of time it has been in this state for. Normally, that accounting is done on IO completion, but that can result in more than a second's worth of IO being accounted for within any one second, leading to >100% utilisation. To deal with that, we call this function to do a round-off before returning the results when reading /proc/diskstats. This accounts immediately for all queue usage up to the current jiffies and restarts the counters again. Kernel Hackers Manual July 2017 blk_add_request_payload 9 4.1.27 blk_add_request_payload add a payload to a request void blk_add_request_payload struct request * rq struct page * page unsigned int len rq request to update page page backing the payload len length of the payload. This allows to later add a payload to an already submitted request by a block driver. The driver needs to take care of freeing the payload itself. Note that this is a quite horrible hack and nothing but handling of discard requests should ever use it. Kernel Hackers Manual July 2017 generic_make_request 9 4.1.27 generic_make_request hand a buffer to its device driver for I/O void generic_make_request struct bio * bio bio The bio describing the location in memory and on the device. generic_make_request is used to make I/O requests of block devices. It is passed a struct bio, which describes the I/O that needs to be done. generic_make_request does not return any status. The success/failure status of the request, along with notification of completion, is delivered asynchronously through the bio->bi_end_io function described (one day) else where. The caller of generic_make_request must make sure that bi_io_vec are set to describe the memory buffer, and that bi_dev and bi_sector are set to describe the device address, and the bi_end_io and optionally bi_private are set to describe how completion notification should be signaled. generic_make_request and the drivers it calls may use bi_next if this bio happens to be merged with someone else, and may resubmit the bio to a lower device by calling into generic_make_request recursively, which means the bio should NOT be touched after the call to ->make_request_fn. Kernel Hackers Manual July 2017 submit_bio 9 4.1.27 submit_bio submit a bio to the block device layer for I/O void submit_bio int rw struct bio * bio rw whether to READ or WRITE, or maybe to READA (read ahead) bio The struct bio which describes the I/O submit_bio is very similar in purpose to generic_make_request, and uses that function to do most of the work. Both are fairly rough interfaces; bio must be presetup and ready for I/O. Kernel Hackers Manual July 2017 blk_rq_check_limits 9 4.1.27 blk_rq_check_limits Helper function to check a request for the queue limit int blk_rq_check_limits struct request_queue * q struct request * rq q the queue rq the request being checked rq may have been made based on weaker limitations of upper-level queues in request stacking drivers, and it may violate the limitation of q. Since the block layer and the underlying device driver trust rq after it is inserted to q, it should be checked against q before the insertion using this generic function. This function should also be useful for request stacking drivers in some cases below, so export this function. Request stacking drivers like request-based dm may change the queue limits while requests are in the queue (e.g. dm's table swapping). Such request stacking drivers should check those requests against the new queue limits again when they dispatch those requests, although such checkings are also done against the old queue limits when submitting requests. Kernel Hackers Manual July 2017 blk_insert_cloned_request 9 4.1.27 blk_insert_cloned_request Helper for stacking drivers to submit a request int blk_insert_cloned_request struct request_queue * q struct request * rq q the queue to submit the request rq the request being queued Kernel Hackers Manual July 2017 blk_rq_err_bytes 9 4.1.27 blk_rq_err_bytes determine number of bytes till the next failure boundary unsigned int blk_rq_err_bytes const struct request * rq rq request to examine A request could be merge of IOs which require different failure handling. This function determines the number of bytes which can be failed from the beginning of the request without crossing into area which need to be retried further. The number of bytes to fail. queue_lock must be held. Kernel Hackers Manual July 2017 blk_peek_request 9 4.1.27 blk_peek_request peek at the top of a request queue struct request * blk_peek_request struct request_queue * q q request queue to peek at Return the request at the top of q. The returned request should be started using blk_start_request before LLD starts processing it. Pointer to the request at the top of q if available. Null otherwise. queue_lock must be held. Kernel Hackers Manual July 2017 blk_start_request 9 4.1.27 blk_start_request start request processing on the driver void blk_start_request struct request * req req request to dequeue Dequeue req and start timeout timer on it. This hands off the request to the driver. Block internal functions which don't want to start timer should call blk_dequeue_request. queue_lock must be held. Kernel Hackers Manual July 2017 blk_fetch_request 9 4.1.27 blk_fetch_request fetch a request from a request queue struct request * blk_fetch_request struct request_queue * q q request queue to fetch a request from Return the request at the top of q. The request is started on return and LLD can start processing it immediately. Pointer to the request at the top of q if available. Null otherwise. queue_lock must be held. Kernel Hackers Manual July 2017 blk_update_request 9 4.1.27 blk_update_request Special helper function for request stacking drivers bool blk_update_request struct request * req int error unsigned int nr_bytes req the request being processed error 0 for success, < 0 for error nr_bytes number of bytes to complete req Ends I/O on a number of bytes attached to req, but doesn't complete the request structure even if req doesn't have leftover. If req has leftover, sets it up for the next range of segments. This special helper function is only for request stacking drivers (e.g. request-based dm) so that they can handle partial completion. Actual device drivers should use blk_end_request instead. Passing the result of blk_rq_bytes as nr_bytes guarantees false return from this function. false - this request doesn't have any more data true - this request has more data Kernel Hackers Manual July 2017 blk_unprep_request 9 4.1.27 blk_unprep_request unprepare a request void blk_unprep_request struct request * req req the request This function makes a request ready for complete resubmission (or completion). It happens only after all error handling is complete, so represents the appropriate moment to deallocate any resources that were allocated to the request in the prep_rq_fn. The queue lock is held when calling this. Kernel Hackers Manual July 2017 blk_end_request 9 4.1.27 blk_end_request Helper function for drivers to complete the request. bool blk_end_request struct request * rq int error unsigned int nr_bytes rq the request being processed error 0 for success, < 0 for error nr_bytes number of bytes to complete Ends I/O on a number of bytes attached to rq. If rq has leftover, sets it up for the next range of segments. false - we are done with this request true - still buffers pending for this request Kernel Hackers Manual July 2017 blk_end_request_all 9 4.1.27 blk_end_request_all Helper function for drives to finish the request. void blk_end_request_all struct request * rq int error rq the request to finish error 0 for success, < 0 for error Completely finish rq. Kernel Hackers Manual July 2017 blk_end_request_cur 9 4.1.27 blk_end_request_cur Helper function to finish the current request chunk. bool blk_end_request_cur struct request * rq int error rq the request to finish the current chunk for error 0 for success, < 0 for error Complete the current consecutively mapped chunk from rq. false - we are done with this request true - still buffers pending for this request Kernel Hackers Manual July 2017 blk_end_request_err 9 4.1.27 blk_end_request_err Finish a request till the next failure boundary. bool blk_end_request_err struct request * rq int error rq the request to finish till the next failure boundary for error must be negative errno Complete rq till the next failure boundary. false - we are done with this request true - still buffers pending for this request Kernel Hackers Manual July 2017 __blk_end_request 9 4.1.27 __blk_end_request Helper function for drivers to complete the request. bool __blk_end_request struct request * rq int error unsigned int nr_bytes rq the request being processed error 0 for success, < 0 for error nr_bytes number of bytes to complete Must be called with queue lock held unlike blk_end_request. false - we are done with this request true - still buffers pending for this request Kernel Hackers Manual July 2017 __blk_end_request_all 9 4.1.27 __blk_end_request_all Helper function for drives to finish the request. void __blk_end_request_all struct request * rq int error rq the request to finish error 0 for success, < 0 for error Completely finish rq. Must be called with queue lock held. Kernel Hackers Manual July 2017 __blk_end_request_cur 9 4.1.27 __blk_end_request_cur Helper function to finish the current request chunk. bool __blk_end_request_cur struct request * rq int error rq the request to finish the current chunk for error 0 for success, < 0 for error Complete the current consecutively mapped chunk from rq. Must be called with queue lock held. false - we are done with this request true - still buffers pending for this request Kernel Hackers Manual July 2017 __blk_end_request_err 9 4.1.27 __blk_end_request_err Finish a request till the next failure boundary. bool __blk_end_request_err struct request * rq int error rq the request to finish till the next failure boundary for error must be negative errno Complete rq till the next failure boundary. Must be called with queue lock held. false - we are done with this request true - still buffers pending for this request Kernel Hackers Manual July 2017 rq_flush_dcache_pages 9 4.1.27 rq_flush_dcache_pages Helper function to flush all pages in a request void rq_flush_dcache_pages struct request * rq rq the request to be flushed Flush all pages in rq. Kernel Hackers Manual July 2017 blk_lld_busy 9 4.1.27 blk_lld_busy Check if underlying low-level drivers of a device are busy int blk_lld_busy struct request_queue * q q the queue of the device being checked Check if underlying low-level drivers of a device are busy. If the drivers want to export their busy state, they must set own exporting function using blk_queue_lld_busy first. Basically, this function is used only by request stacking drivers to stop dispatching requests to underlying devices when underlying devices are busy. This behavior helps more I/O merging on the queue of the request stacking driver and prevents I/O throughput regression on burst I/O load. 0 - Not busy (The request stacking driver should dispatch request) 1 - Busy (The request stacking driver should stop dispatching request) Kernel Hackers Manual July 2017 blk_rq_unprep_clone 9 4.1.27 blk_rq_unprep_clone Helper function to free all bios in a cloned request void blk_rq_unprep_clone struct request * rq rq the clone request to be cleaned up Free all bios in rq for a cloned request. Kernel Hackers Manual July 2017 blk_rq_prep_clone 9 4.1.27 blk_rq_prep_clone Helper function to setup clone request int blk_rq_prep_clone struct request * rq struct request * rq_src struct bio_set * bs gfp_t gfp_mask int (*bio_ctr) struct bio *, struct bio *, void * void * data rq the request to be setup rq_src original request to be cloned bs bio_set that bios for clone are allocated from gfp_mask memory allocation mask for bio bio_ctr setup function to be called for each clone bio. Returns 0 for success, non 0 for failure. data private data to be passed to bio_ctr Clones bios in rq_src to rq, and copies attributes of rq_src to rq. The actual data parts of rq_src (e.g. ->cmd, ->sense) are not copied, and copying such parts is the caller's responsibility. Also, pages which the original bios are pointing to are not copied and the cloned bios just point same pages. So cloned bios must be completed before original bios, which means the caller must complete rq before rq_src. Kernel Hackers Manual July 2017 blk_start_plug 9 4.1.27 blk_start_plug initialize blk_plug and track it inside the task_struct void blk_start_plug struct blk_plug * plug plug The struct blk_plug that needs to be initialized Tracking blk_plug inside the task_struct will help with auto-flushing the pending I/O should the task end up blocking between blk_start_plug and blk_finish_plug. This is important from a performance perspective, but also ensures that we don't deadlock. For instance, if the task is blocking for a memory allocation, memory reclaim could end up wanting to free a page belonging to that request that is currently residing in our private plug. By flushing the pending I/O when the process goes to sleep, we avoid this kind of deadlock. Kernel Hackers Manual July 2017 blk_pm_runtime_init 9 4.1.27 blk_pm_runtime_init Block layer runtime PM initialization routine void blk_pm_runtime_init struct request_queue * q struct device * dev q the queue of the device dev the device the queue belongs to Initialize runtime-PM-related fields for q and start auto suspend for dev. Drivers that want to take advantage of request-based runtime PM should call this function after dev has been initialized, and its request queue q has been allocated, and runtime PM for it can not happen yet(either due to disabled/forbidden or its usage_count > 0). In most cases, driver should call this function before any I/O has taken place. This function takes care of setting up using auto suspend for the device, the autosuspend delay is set to -1 to make runtime suspend impossible until an updated value is either set by user or by driver. Drivers do not need to touch other autosuspend settings. The block layer runtime PM is request based, so only works for drivers that use request as their IO unit instead of those directly use bio's. Kernel Hackers Manual July 2017 blk_pre_runtime_suspend 9 4.1.27 blk_pre_runtime_suspend Pre runtime suspend check int blk_pre_runtime_suspend struct request_queue * q q the queue of the device This function will check if runtime suspend is allowed for the device by examining if there are any requests pending in the queue. If there are requests pending, the device can not be runtime suspended; otherwise, the queue's status will be updated to SUSPENDING and the driver can proceed to suspend the device. For the not allowed case, we mark last busy for the device so that runtime PM core will try to autosuspend it some time later. This function should be called near the start of the device's runtime_suspend callback. 0 - OK to runtime suspend the device -EBUSY - Device should not be runtime suspended Kernel Hackers Manual July 2017 blk_post_runtime_suspend 9 4.1.27 blk_post_runtime_suspend Post runtime suspend processing void blk_post_runtime_suspend struct request_queue * q int err q the queue of the device err return value of the device's runtime_suspend function Update the queue's runtime status according to the return value of the device's runtime suspend function and mark last busy for the device so that PM core will try to auto suspend the device at a later time. This function should be called near the end of the device's runtime_suspend callback. Kernel Hackers Manual July 2017 blk_pre_runtime_resume 9 4.1.27 blk_pre_runtime_resume Pre runtime resume processing void blk_pre_runtime_resume struct request_queue * q q the queue of the device Update the queue's runtime status to RESUMING in preparation for the runtime resume of the device. This function should be called near the start of the device's runtime_resume callback. Kernel Hackers Manual July 2017 blk_post_runtime_resume 9 4.1.27 blk_post_runtime_resume Post runtime resume processing void blk_post_runtime_resume struct request_queue * q int err q the queue of the device err return value of the device's runtime_resume function Update the queue's runtime status according to the return value of the device's runtime_resume function. If it is successfully resumed, process the requests that are queued into the device's queue when it is resuming and then mark last busy and initiate autosuspend for it. This function should be called near the end of the device's runtime_resume callback. Kernel Hackers Manual July 2017 __blk_run_queue_uncond 9 4.1.27 __blk_run_queue_uncond run a queue whether or not it has been stopped void __blk_run_queue_uncond struct request_queue * q q The queue to run Invoke request handling on a queue if there are any pending requests. May be used to restart request handling after a request has completed. This variant runs the queue whether or not the queue has been stopped. Must be called with the queue lock held and interrupts disabled. See also blk_run_queue. Kernel Hackers Manual July 2017 __blk_drain_queue 9 4.1.27 __blk_drain_queue drain requests from request_queue void __blk_drain_queue struct request_queue * q bool drain_all q queue to drain drain_all whether to drain all requests or only the ones w/ ELVPRIV Drain requests from q. If drain_all is set, all requests are drained. If not, only ELVPRIV requests are drained. The caller is responsible for ensuring that no new requests which need to be drained are queued. Kernel Hackers Manual July 2017 rq_ioc 9 4.1.27 rq_ioc determine io_context for request allocation struct io_context * rq_ioc struct bio * bio bio request being allocated is for this bio (can be NULL) Determine io_context to use for request allocation for bio. May return NULL if current->io_context doesn't exist. Kernel Hackers Manual July 2017 __get_request 9 4.1.27 __get_request get a free request struct request * __get_request struct request_list * rl int rw_flags struct bio * bio gfp_t gfp_mask rl request list to allocate from rw_flags RW and SYNC flags bio bio to allocate request for (can be NULL) gfp_mask allocation mask Get a free request from q. This function may fail under memory pressure or if q is dead. Must be called with q->queue_lock held and, Returns ERR_PTR on failure, with q->queue_lock held. Returns request pointer on success, with q->queue_lock *not held*. Kernel Hackers Manual July 2017 get_request 9 4.1.27 get_request get a free request struct request * get_request struct request_queue * q int rw_flags struct bio * bio gfp_t gfp_mask q request_queue to allocate request from rw_flags RW and SYNC flags bio bio to allocate request for (can be NULL) gfp_mask allocation mask Get a free request from q. If __GFP_WAIT is set in gfp_mask, this function keeps retrying under memory pressure and fails iff q is dead. Must be called with q->queue_lock held and, Returns ERR_PTR on failure, with q->queue_lock held. Returns request pointer on success, with q->queue_lock *not held*. Kernel Hackers Manual July 2017 blk_attempt_plug_merge 9 4.1.27 blk_attempt_plug_merge try to merge with current's plugged list bool blk_attempt_plug_merge struct request_queue * q struct bio * bio unsigned int * request_count q request_queue new bio is being queued at bio new bio being queued request_count out parameter for number of traversed plugged requests Determine whether bio being queued on q can be merged with a request on current's plugged list. Returns true if merge was successful, otherwise false. Plugging coalesces IOs from the same issuer for the same purpose without going through q->queue_lock. As such it's more of an issuing mechanism than scheduling, and the request, while may have elvpriv data, is not added on the elevator at this point. In addition, we don't have reliable access to the elevator outside queue lock. Only check basic merging parameters without querying the elevator. Caller must ensure !blk_queue_nomerges(q) beforehand. Kernel Hackers Manual July 2017 blk_end_bidi_request 9 4.1.27 blk_end_bidi_request Complete a bidi request bool blk_end_bidi_request struct request * rq int error unsigned int nr_bytes unsigned int bidi_bytes rq the request to complete error 0 for success, < 0 for error nr_bytes number of bytes to complete rq bidi_bytes number of bytes to complete rq->next_rq Ends I/O on a number of bytes attached to rq and rq->next_rq. Drivers that supports bidi can safely call this member for any type of request, bidi or uni. In the later case bidi_bytes is just ignored. false - we are done with this request true - still buffers pending for this request Kernel Hackers Manual July 2017 __blk_end_bidi_request 9 4.1.27 __blk_end_bidi_request Complete a bidi request with queue lock held bool __blk_end_bidi_request struct request * rq int error unsigned int nr_bytes unsigned int bidi_bytes rq the request to complete error 0 for success, < 0 for error nr_bytes number of bytes to complete rq bidi_bytes number of bytes to complete rq->next_rq Identical to blk_end_bidi_request except that queue lock is assumed to be locked on entry and remains so on return. false - we are done with this request true - still buffers pending for this request Kernel Hackers Manual July 2017 blk_rq_map_user_iov 9 4.1.27 blk_rq_map_user_iov map user data to a request, for REQ_TYPE_BLOCK_PC usage int blk_rq_map_user_iov struct request_queue * q struct request * rq struct rq_map_data * map_data const struct iov_iter * iter gfp_t gfp_mask q request queue where request should be inserted rq request to map data to map_data pointer to the rq_map_data holding pages (if necessary) iter iovec iterator gfp_mask memory allocation flags Data will be mapped directly for zero copy I/O, if possible. Otherwise a kernel bounce buffer is used. A matching blk_rq_unmap_user must be issued at the end of I/O, while still in process context. The mapped bio may need to be bounced through blk_queue_bounce before being submitted to the device, as pages mapped may be out of reach. It's the callers responsibility to make sure this happens. The original bio must be passed back in to blk_rq_unmap_user for proper unmapping. Kernel Hackers Manual July 2017 blk_rq_unmap_user 9 4.1.27 blk_rq_unmap_user unmap a request with user data int blk_rq_unmap_user struct bio * bio bio start of bio list Unmap a rq previously mapped by blk_rq_map_user. The caller must supply the original rq->bio from the blk_rq_map_user return, since the I/O completion may have changed rq->bio. Kernel Hackers Manual July 2017 blk_rq_map_kern 9 4.1.27 blk_rq_map_kern map kernel data to a request, for REQ_TYPE_BLOCK_PC usage int blk_rq_map_kern struct request_queue * q struct request * rq void * kbuf unsigned int len gfp_t gfp_mask q request queue where request should be inserted rq request to fill kbuf the kernel buffer len length of user data gfp_mask memory allocation flags Data will be mapped directly if possible. Otherwise a bounce buffer is used. Can be called multiple times to append multiple buffers. Kernel Hackers Manual July 2017 blk_release_queue 9 4.1.27 blk_release_queue release a struct request_queue when it is no longer needed void blk_release_queue struct kobject * kobj kobj the kobj belonging to the request queue to be released blk_release_queue is the pair to blk_init_queue or blk_queue_make_request. It should be called when a request queue is being released; typically when a block device is being de-registered. Currently, its primary task it to free all the struct request structures that were allocated to the queue and the queue itself. The low level driver must have finished any outstanding requests first via blk_cleanup_queue. Kernel Hackers Manual July 2017 blk_queue_prep_rq 9 4.1.27 blk_queue_prep_rq set a prepare_request function for queue void blk_queue_prep_rq struct request_queue * q prep_rq_fn * pfn q queue pfn prepare_request function It's possible for a queue to register a prepare_request callback which is invoked before the request is handed to the request_fn. The goal of the function is to prepare a request for I/O, it can be used to build a cdb from the request data for instance. Kernel Hackers Manual July 2017 blk_queue_unprep_rq 9 4.1.27 blk_queue_unprep_rq set an unprepare_request function for queue void blk_queue_unprep_rq struct request_queue * q unprep_rq_fn * ufn q queue ufn unprepare_request function It's possible for a queue to register an unprepare_request callback which is invoked before the request is finally completed. The goal of the function is to deallocate any data that was allocated in the prepare_request callback. Kernel Hackers Manual July 2017 blk_queue_merge_bvec 9 4.1.27 blk_queue_merge_bvec set a merge_bvec function for queue void blk_queue_merge_bvec struct request_queue * q merge_bvec_fn * mbfn q queue mbfn merge_bvec_fn Usually queues have static limitations on the max sectors or segments that we can put in a request. Stacking drivers may have some settings that are dynamic, and thus we have to query the queue whether it is ok to add a new bio_vec to a bio at a given offset or not. If the block device has such limitations, it needs to register a merge_bvec_fn to control the size of bio's sent to it. Note that a block device *must* allow a single page to be added to an empty bio. The block device driver may want to use the bio_split function to deal with these bio's. By default no merge_bvec_fn is defined for a queue, and only the fixed limits are honored. Kernel Hackers Manual July 2017 blk_set_default_limits 9 4.1.27 blk_set_default_limits reset limits to default values void blk_set_default_limits struct queue_limits * lim lim the queue_limits structure to reset Returns a queue_limit struct to its default state. Kernel Hackers Manual July 2017 blk_set_stacking_limits 9 4.1.27 blk_set_stacking_limits set default limits for stacking devices void blk_set_stacking_limits struct queue_limits * lim lim the queue_limits structure to reset Returns a queue_limit struct to its default state. Should be used by stacking drivers like DM that have no internal limits. Kernel Hackers Manual July 2017 blk_queue_make_request 9 4.1.27 blk_queue_make_request define an alternate make_request function for a device void blk_queue_make_request struct request_queue * q make_request_fn * mfn q the request queue for the device to be affected mfn the alternate make_request function The normal way for struct bios to be passed to a device driver is for them to be collected into requests on a request queue, and then to allow the device driver to select requests off that queue when it is ready. This works well for many block devices. However some block devices (typically virtual devices such as md or lvm) do not benefit from the processing on the request queue, and are served best by having the requests passed directly to them. This can be achieved by providing a function to blk_queue_make_request. The driver that does this *must* be able to deal appropriately with buffers in highmemory. This can be accomplished by either calling __bio_kmap_atomic to get a temporary kernel mapping, or by calling blk_queue_bounce to create a buffer in normal memory. Kernel Hackers Manual July 2017 blk_queue_bounce_limit 9 4.1.27 blk_queue_bounce_limit set bounce buffer limit for queue void blk_queue_bounce_limit struct request_queue * q u64 max_addr q the request queue for the device max_addr the maximum address the device can handle Different hardware can have different requirements as to what pages it can do I/O directly to. A low level driver can call blk_queue_bounce_limit to have lower memory pages allocated as bounce buffers for doing I/O to pages residing above max_addr. Kernel Hackers Manual July 2017 blk_limits_max_hw_sectors 9 4.1.27 blk_limits_max_hw_sectors set hard and soft limit of max sectors for request void blk_limits_max_hw_sectors struct queue_limits * limits unsigned int max_hw_sectors limits the queue limits max_hw_sectors max hardware sectors in the usual 512b unit Enables a low level driver to set a hard upper limit, max_hw_sectors, on the size of requests. max_hw_sectors is set by the device driver based upon the capabilities of the I/O controller. max_sectors is a soft limit imposed by the block layer for filesystem type requests. This value can be overridden on a per-device basis in /sys/block/<device>/queue/max_sectors_kb. The soft limit can not exceed max_hw_sectors. Kernel Hackers Manual July 2017 blk_queue_max_hw_sectors 9 4.1.27 blk_queue_max_hw_sectors set max sectors for a request for this queue void blk_queue_max_hw_sectors struct request_queue * q unsigned int max_hw_sectors q the request queue for the device max_hw_sectors max hardware sectors in the usual 512b unit See description for blk_limits_max_hw_sectors. Kernel Hackers Manual July 2017 blk_queue_chunk_sectors 9 4.1.27 blk_queue_chunk_sectors set size of the chunk for this queue void blk_queue_chunk_sectors struct request_queue * q unsigned int chunk_sectors q the request queue for the device chunk_sectors chunk sectors in the usual 512b unit If a driver doesn't want IOs to cross a given chunk size, it can set this limit and prevent merging across chunks. Note that the chunk size must currently be a power-of-2 in sectors. Also note that the block layer must accept a page worth of data at any offset. So if the crossing of chunks is a hard limitation in the driver, it must still be prepared to split single page bios. Kernel Hackers Manual July 2017 blk_queue_max_discard_sectors 9 4.1.27 blk_queue_max_discard_sectors set max sectors for a single discard void blk_queue_max_discard_sectors struct request_queue * q unsigned int max_discard_sectors q the request queue for the device max_discard_sectors maximum number of sectors to discard Kernel Hackers Manual July 2017 blk_queue_max_write_same_sectors 9 4.1.27 blk_queue_max_write_same_sectors set max sectors for a single write same void blk_queue_max_write_same_sectors struct request_queue * q unsigned int max_write_same_sectors q the request queue for the device max_write_same_sectors maximum number of sectors to write per command Kernel Hackers Manual July 2017 blk_queue_max_segments 9 4.1.27 blk_queue_max_segments set max hw segments for a request for this queue void blk_queue_max_segments struct request_queue * q unsigned short max_segments q the request queue for the device max_segments max number of segments Enables a low level driver to set an upper limit on the number of hw data segments in a request. Kernel Hackers Manual July 2017 blk_queue_max_segment_size 9 4.1.27 blk_queue_max_segment_size set max segment size for blk_rq_map_sg void blk_queue_max_segment_size struct request_queue * q unsigned int max_size q the request queue for the device max_size max size of segment in bytes Enables a low level driver to set an upper limit on the size of a coalesced segment Kernel Hackers Manual July 2017 blk_queue_logical_block_size 9 4.1.27 blk_queue_logical_block_size set logical block size for the queue void blk_queue_logical_block_size struct request_queue * q unsigned short size q the request queue for the device size the logical block size, in bytes This should be set to the lowest possible block size that the storage device can address. The default of 512 covers most hardware. Kernel Hackers Manual July 2017 blk_queue_physical_block_size 9 4.1.27 blk_queue_physical_block_size set physical block size for the queue void blk_queue_physical_block_size struct request_queue * q unsigned int size q the request queue for the device size the physical block size, in bytes This should be set to the lowest possible sector size that the hardware can operate on without reverting to read-modify-write operations. Kernel Hackers Manual July 2017 blk_queue_alignment_offset 9 4.1.27 blk_queue_alignment_offset set physical block alignment offset void blk_queue_alignment_offset struct request_queue * q unsigned int offset q the request queue for the device offset alignment offset in bytes Some devices are naturally misaligned to compensate for things like the legacy DOS partition table 63-sector offset. Low-level drivers should call this function for devices whose first sector is not naturally aligned. Kernel Hackers Manual July 2017 blk_limits_io_min 9 4.1.27 blk_limits_io_min set minimum request size for a device void blk_limits_io_min struct queue_limits * limits unsigned int min limits the queue limits min smallest I/O size in bytes Some devices have an internal block size bigger than the reported hardware sector size. This function can be used to signal the smallest I/O the device can perform without incurring a performance penalty. Kernel Hackers Manual July 2017 blk_queue_io_min 9 4.1.27 blk_queue_io_min set minimum request size for the queue void blk_queue_io_min struct request_queue * q unsigned int min q the request queue for the device min smallest I/O size in bytes Storage devices may report a granularity or preferred minimum I/O size which is the smallest request the device can perform without incurring a performance penalty. For disk drives this is often the physical block size. For RAID arrays it is often the stripe chunk size. A properly aligned multiple of minimum_io_size is the preferred request size for workloads where a high number of I/O operations is desired. Kernel Hackers Manual July 2017 blk_limits_io_opt 9 4.1.27 blk_limits_io_opt set optimal request size for a device void blk_limits_io_opt struct queue_limits * limits unsigned int opt limits the queue limits opt smallest I/O size in bytes Storage devices may report an optimal I/O size, which is the device's preferred unit for sustained I/O. This is rarely reported for disk drives. For RAID arrays it is usually the stripe width or the internal track size. A properly aligned multiple of optimal_io_size is the preferred request size for workloads where sustained throughput is desired. Kernel Hackers Manual July 2017 blk_queue_io_opt 9 4.1.27 blk_queue_io_opt set optimal request size for the queue void blk_queue_io_opt struct request_queue * q unsigned int opt q the request queue for the device opt optimal request size in bytes Storage devices may report an optimal I/O size, which is the device's preferred unit for sustained I/O. This is rarely reported for disk drives. For RAID arrays it is usually the stripe width or the internal track size. A properly aligned multiple of optimal_io_size is the preferred request size for workloads where sustained throughput is desired. Kernel Hackers Manual July 2017 blk_queue_stack_limits 9 4.1.27 blk_queue_stack_limits inherit underlying queue limits for stacked drivers void blk_queue_stack_limits struct request_queue * t struct request_queue * b t the stacking driver (top) b the underlying device (bottom) Kernel Hackers Manual July 2017 blk_stack_limits 9 4.1.27 blk_stack_limits adjust queue_limits for stacked devices int blk_stack_limits struct queue_limits * t struct queue_limits * b sector_t start t the stacking driver limits (top device) b the underlying queue limits (bottom, component device) start first data sector within component device This function is used by stacking drivers like MD and DM to ensure that all component devices have compatible block sizes and alignments. The stacking driver must provide a queue_limits struct (top) and then iteratively call the stacking function for all component (bottom) devices. The stacking function will attempt to combine the values and ensure proper alignment. Returns 0 if the top and bottom queue_limits are compatible. The top device's block sizes and alignment offsets may be adjusted to ensure alignment with the bottom device. If no compatible sizes and alignments exist, -1 is returned and the resulting top queue_limits will have the misaligned flag set to indicate that the alignment_offset is undefined. Kernel Hackers Manual July 2017 bdev_stack_limits 9 4.1.27 bdev_stack_limits adjust queue limits for stacked drivers int bdev_stack_limits struct queue_limits * t struct block_device * bdev sector_t start t the stacking driver limits (top device) bdev the component block_device (bottom) start first data sector within component device Merges queue limits for a top device and a block_device. Returns 0 if alignment didn't change. Returns -1 if adding the bottom device caused misalignment. Kernel Hackers Manual July 2017 disk_stack_limits 9 4.1.27 disk_stack_limits adjust queue limits for stacked drivers void disk_stack_limits struct gendisk * disk struct block_device * bdev sector_t offset disk MD/DM gendisk (top) bdev the underlying block device (bottom) offset offset to beginning of data within component device Merges the limits for a top level gendisk and a bottom level block_device. Kernel Hackers Manual July 2017 blk_queue_dma_pad 9 4.1.27 blk_queue_dma_pad set pad mask void blk_queue_dma_pad struct request_queue * q unsigned int mask q the request queue for the device mask pad mask Set dma pad mask. Appending pad buffer to a request modifies the last entry of a scatter list such that it includes the pad buffer. Kernel Hackers Manual July 2017 blk_queue_update_dma_pad 9 4.1.27 blk_queue_update_dma_pad update pad mask void blk_queue_update_dma_pad struct request_queue * q unsigned int mask q the request queue for the device mask pad mask Update dma pad mask. Appending pad buffer to a request modifies the last entry of a scatter list such that it includes the pad buffer. Kernel Hackers Manual July 2017 blk_queue_dma_drain 9 4.1.27 blk_queue_dma_drain Set up a drain buffer for excess dma. int blk_queue_dma_drain struct request_queue * q dma_drain_needed_fn * dma_drain_needed void * buf unsigned int size q the request queue for the device dma_drain_needed fn which returns non-zero if drain is necessary buf physically contiguous buffer size size of the buffer in bytes Some devices have excess DMA problems and can't simply discard (or zero fill) the unwanted piece of the transfer. They have to have a real area of memory to transfer it into. The use case for this is ATAPI devices in DMA mode. If the packet command causes a transfer bigger than the transfer size some HBAs will lock up if there aren't DMA elements to contain the excess transfer. What this API does is adjust the queue so that the buf is always appended silently to the scatterlist. This routine adjusts max_hw_segments to make room for appending the drain buffer. If you call blk_queue_max_segments after calling this routine, you must set the limit to one fewer than your device can support otherwise there won't be room for the drain buffer. Kernel Hackers Manual July 2017 blk_queue_segment_boundary 9 4.1.27 blk_queue_segment_boundary set boundary rules for segment merging void blk_queue_segment_boundary struct request_queue * q unsigned long mask q the request queue for the device mask the memory boundary mask Kernel Hackers Manual July 2017 blk_queue_dma_alignment 9 4.1.27 blk_queue_dma_alignment set dma length and memory alignment void blk_queue_dma_alignment struct request_queue * q int mask q the request queue for the device mask alignment mask set required memory and length alignment for direct dma transactions. this is used when building direct io requests for the queue. Kernel Hackers Manual July 2017 blk_queue_update_dma_alignment 9 4.1.27 blk_queue_update_dma_alignment update dma length and memory alignment void blk_queue_update_dma_alignment struct request_queue * q int mask q the request queue for the device mask alignment mask update required memory and length alignment for direct dma transactions. If the requested alignment is larger than the current alignment, then the current queue alignment is updated to the new value, otherwise it is left alone. The design of this is to allow multiple objects (driver, device, transport etc) to set their respective alignments without having them interfere. Kernel Hackers Manual July 2017 blk_queue_flush 9 4.1.27 blk_queue_flush configure queue's cache flush capability void blk_queue_flush struct request_queue * q unsigned int flush q the request queue for the device flush 0, REQ_FLUSH or REQ_FLUSH | REQ_FUA Tell block layer cache flush capability of q. If it supports flushing, REQ_FLUSH should be set. If it supports bypassing write cache for individual writes, REQ_FUA should be set. Kernel Hackers Manual July 2017 blk_execute_rq_nowait 9 4.1.27 blk_execute_rq_nowait insert a request into queue for execution void blk_execute_rq_nowait struct request_queue * q struct gendisk * bd_disk struct request * rq int at_head rq_end_io_fn * done q queue to insert the request in bd_disk matching gendisk rq request to insert at_head insert request at head or tail of queue done I/O completion handler Insert a fully prepared request at the back of the I/O scheduler queue for execution. Don't wait for completion. This function will invoke done directly if the queue is dead. Kernel Hackers Manual July 2017 blk_execute_rq 9 4.1.27 blk_execute_rq insert a request into queue for execution int blk_execute_rq struct request_queue * q struct gendisk * bd_disk struct request * rq int at_head q queue to insert the request in bd_disk matching gendisk rq request to insert at_head insert request at head or tail of queue Insert a fully prepared request at the back of the I/O scheduler queue for execution and wait for completion. Kernel Hackers Manual July 2017 blkdev_issue_flush 9 4.1.27 blkdev_issue_flush queue a flush int blkdev_issue_flush struct block_device * bdev gfp_t gfp_mask sector_t * error_sector bdev blockdev to issue flush for gfp_mask memory allocation flags (for bio_alloc) error_sector error sector Issue a flush for the block device in question. Caller can supply room for storing the error offset in case of a flush error, if they wish to. If WAIT flag is not passed then caller may check only what request was pushed in some internal queue for later handling. Kernel Hackers Manual July 2017 blkdev_issue_discard 9 4.1.27 blkdev_issue_discard queue a discard int blkdev_issue_discard struct block_device * bdev sector_t sector sector_t nr_sects gfp_t gfp_mask unsigned long flags bdev blockdev to issue discard for sector start sector nr_sects number of sectors to discard gfp_mask memory allocation flags (for bio_alloc) flags BLKDEV_IFL_* flags to control behaviour Issue a discard request for the sectors in question. Kernel Hackers Manual July 2017 blkdev_issue_write_same 9 4.1.27 blkdev_issue_write_same queue a write same operation int blkdev_issue_write_same struct block_device * bdev sector_t sector sector_t nr_sects gfp_t gfp_mask struct page * page bdev target blockdev sector start sector nr_sects number of sectors to write gfp_mask memory allocation flags (for bio_alloc) page page containing data to write Issue a write same request for the sectors in question. Kernel Hackers Manual July 2017 blkdev_issue_zeroout 9 4.1.27 blkdev_issue_zeroout zero-fill a block range int blkdev_issue_zeroout struct block_device * bdev sector_t sector sector_t nr_sects gfp_t gfp_mask bool discard bdev blockdev to write sector start sector nr_sects number of sectors to write gfp_mask memory allocation flags (for bio_alloc) discard whether to discard the block range Zero-fill a block range. If the discard flag is set and the block device guarantees that subsequent READ operations to the block range in question will return zeroes, the blocks will be discarded. Should the discard request fail, if the discard flag is not set, or if discard_zeroes_data is not supported, this function will resort to zeroing the blocks manually, thus provisioning (allocating, anchoring) them. If the block device supports the WRITE SAME command blkdev_issue_zeroout will use it to optimize the process of clearing the block range. Otherwise the zeroing will be performed using regular WRITE calls. Kernel Hackers Manual July 2017 blk_queue_find_tag 9 4.1.27 blk_queue_find_tag find a request by its tag and queue struct request * blk_queue_find_tag struct request_queue * q int tag q The request queue for the device tag The tag of the request Should be used when a device returns a tag and you want to match it with a request. no locks need be held. Kernel Hackers Manual July 2017 blk_free_tags 9 4.1.27 blk_free_tags release a given set of tag maintenance info void blk_free_tags struct blk_queue_tag * bqt bqt the tag map to free Drop the reference count on bqt and frees it when the last reference is dropped. Kernel Hackers Manual July 2017 blk_queue_free_tags 9 4.1.27 blk_queue_free_tags release tag maintenance info void blk_queue_free_tags struct request_queue * q q the request queue for the device This is used to disable tagged queuing to a device, yet leave queue in function. Kernel Hackers Manual July 2017 blk_init_tags 9 4.1.27 blk_init_tags initialize the tag info for an external tag map struct blk_queue_tag * blk_init_tags int depth int alloc_policy depth the maximum queue depth supported alloc_policy tag allocation policy Kernel Hackers Manual July 2017 blk_queue_init_tags 9 4.1.27 blk_queue_init_tags initialize the queue tag info int blk_queue_init_tags struct request_queue * q int depth struct blk_queue_tag * tags int alloc_policy q the request queue for the device depth the maximum queue depth supported tags the tag to use alloc_policy tag allocation policy Queue lock must be held here if the function is called to resize an existing map. Kernel Hackers Manual July 2017 blk_queue_resize_tags 9 4.1.27 blk_queue_resize_tags change the queueing depth int blk_queue_resize_tags struct request_queue * q int new_depth q the request queue for the device new_depth the new max command queueing depth Must be called with the queue lock held. Kernel Hackers Manual July 2017 blk_queue_end_tag 9 4.1.27 blk_queue_end_tag end tag operations for a request void blk_queue_end_tag struct request_queue * q struct request * rq q the request queue for the device rq the request that has completed Typically called when end_that_request_first returns 0, meaning all transfers have been done for a request. It's important to call this function before end_that_request_last, as that will put the request back on the free list thus corrupting the internal tag list. queue lock must be held. Kernel Hackers Manual July 2017 blk_queue_start_tag 9 4.1.27 blk_queue_start_tag find a free tag and assign it int blk_queue_start_tag struct request_queue * q struct request * rq q the request queue for the device rq the block request that needs tagging This can either be used as a stand-alone helper, or possibly be assigned as the queue prep_rq_fn (in which case struct request automagically gets a tag assigned). Note that this function assumes that any type of request can be queued! if this is not true for your device, you must check the request type before calling this function. The request will also be removed from the request queue, so it's the drivers responsibility to readd it if it should need to be restarted for some reason. queue lock must be held. Kernel Hackers Manual July 2017 blk_queue_invalidate_tags 9 4.1.27 blk_queue_invalidate_tags invalidate all pending tags void blk_queue_invalidate_tags struct request_queue * q q the request queue for the device Hardware conditions may dictate a need to stop all pending requests. In this case, we will safely clear the block side of the tag queue and readd all requests to the request queue in the right order. queue lock must be held. Kernel Hackers Manual July 2017 __blk_queue_free_tags 9 4.1.27 __blk_queue_free_tags release tag maintenance info void __blk_queue_free_tags struct request_queue * q q the request queue for the device blk_cleanup_queue will take care of calling this function, if tagging has been used. So there's no need to call this directly. Kernel Hackers Manual July 2017 blk_rq_count_integrity_sg 9 4.1.27 blk_rq_count_integrity_sg Count number of integrity scatterlist elements int blk_rq_count_integrity_sg struct request_queue * q struct bio * bio q request queue bio bio with integrity metadata attached Returns the number of elements required in a scatterlist corresponding to the integrity metadata in a bio. Kernel Hackers Manual July 2017 blk_rq_map_integrity_sg 9 4.1.27 blk_rq_map_integrity_sg Map integrity metadata into a scatterlist int blk_rq_map_integrity_sg struct request_queue * q struct bio * bio struct scatterlist * sglist q request queue bio bio with integrity metadata attached sglist target scatterlist Map the integrity vectors in request into a scatterlist. The scatterlist must be big enough to hold all elements. I.e. sized using blk_rq_count_integrity_sg. Kernel Hackers Manual July 2017 blk_integrity_compare 9 4.1.27 blk_integrity_compare Compare integrity profile of two disks int blk_integrity_compare struct gendisk * gd1 struct gendisk * gd2 gd1 Disk to compare gd2 Disk to compare Meta-devices like DM and MD need to verify that all sub-devices use the same integrity format before advertising to upper layers that they can send/receive integrity metadata. This function can be used to check whether two gendisk devices have compatible integrity formats. Kernel Hackers Manual July 2017 blk_integrity_register 9 4.1.27 blk_integrity_register Register a gendisk as being integrity-capable int blk_integrity_register struct gendisk * disk struct blk_integrity * template disk struct gendisk pointer to make integrity-aware template optional integrity profile to register When a device needs to advertise itself as being able to send/receive integrity metadata it must use this function to register the capability with the block layer. The template is a blk_integrity struct with values appropriate for the underlying hardware. If template is NULL the new profile is allocated but not filled out. See Documentation/block/data-integrity.txt. Kernel Hackers Manual July 2017 blk_integrity_unregister 9 4.1.27 blk_integrity_unregister Remove block integrity profile void blk_integrity_unregister struct gendisk * disk disk disk whose integrity profile to deallocate This function frees all memory used by the block integrity profile. To be called at device teardown. Kernel Hackers Manual July 2017 blk_trace_ioctl 9 4.1.27 blk_trace_ioctl handle the ioctls associated with tracing int blk_trace_ioctl struct block_device * bdev unsigned cmd char __user * arg bdev the block device cmd the ioctl cmd arg the argument data, if any Kernel Hackers Manual July 2017 blk_trace_shutdown 9 4.1.27 blk_trace_shutdown stop and cleanup trace structures void blk_trace_shutdown struct request_queue * q q the request queue associated with the device Kernel Hackers Manual July 2017 blk_add_trace_rq 9 4.1.27 blk_add_trace_rq Add a trace for a request oriented action void blk_add_trace_rq struct request_queue * q struct request * rq unsigned int nr_bytes u32 what q queue the io is for rq the source request nr_bytes number of completed bytes what the action Records an action against a request. Will log the bio offset + size. Kernel Hackers Manual July 2017 blk_add_trace_bio 9 4.1.27 blk_add_trace_bio Add a trace for a bio oriented action void blk_add_trace_bio struct request_queue * q struct bio * bio u32 what int error q queue the io is for bio the source bio what the action error error, if any Records an action against a bio. Will log the bio offset + size. Kernel Hackers Manual July 2017 blk_add_trace_bio_remap 9 4.1.27 blk_add_trace_bio_remap Add a trace for a bio-remap operation void blk_add_trace_bio_remap void * ignore struct request_queue * q struct bio * bio dev_t dev sector_t from ignore trace callback data parameter (not used) q queue the io is for bio the source bio dev target device from source sector Device mapper or raid target sometimes need to split a bio because it spans a stripe (or similar). Add a trace for that action. Kernel Hackers Manual July 2017 blk_add_trace_rq_remap 9 4.1.27 blk_add_trace_rq_remap Add a trace for a request-remap operation void blk_add_trace_rq_remap void * ignore struct request_queue * q struct request * rq dev_t dev sector_t from ignore trace callback data parameter (not used) q queue the io is for rq the source request dev target device from source sector Device mapper remaps request to other devices. Add a trace for that action. Kernel Hackers Manual July 2017 blk_mangle_minor 9 4.1.27 blk_mangle_minor scatter minor numbers apart int blk_mangle_minor int minor minor minor number to mangle Scatter consecutively allocated minor number apart if MANGLE_DEVT is enabled. Mangling twice gives the original value. Mangled value. Don't care. Kernel Hackers Manual July 2017 blk_alloc_devt 9 4.1.27 blk_alloc_devt allocate a dev_t for a partition int blk_alloc_devt struct hd_struct * part dev_t * devt part partition to allocate dev_t for devt out parameter for resulting dev_t Allocate a dev_t for block device. 0 on success, allocated dev_t is returned in *devt. -errno on failure. Might sleep. Kernel Hackers Manual July 2017 blk_free_devt 9 4.1.27 blk_free_devt free a dev_t void blk_free_devt dev_t devt devt dev_t to free Free devt which was allocated using blk_alloc_devt. Might sleep. Kernel Hackers Manual July 2017 disk_replace_part_tbl 9 4.1.27 disk_replace_part_tbl replace disk->part_tbl in RCU-safe way void disk_replace_part_tbl struct gendisk * disk struct disk_part_tbl * new_ptbl disk disk to replace part_tbl for new_ptbl new part_tbl to install Replace disk->part_tbl with new_ptbl in RCU-safe way. The original ptbl is freed using RCU callback. Matching bd_mutx locked. Kernel Hackers Manual July 2017 disk_expand_part_tbl 9 4.1.27 disk_expand_part_tbl expand disk->part_tbl int disk_expand_part_tbl struct gendisk * disk int partno disk disk to expand part_tbl for partno expand such that this partno can fit in Expand disk->part_tbl such that partno can fit in. disk->part_tbl uses RCU to allow unlocked dereferencing for stats and other stuff. Matching bd_mutex locked, might sleep. 0 on success, -errno on failure. Kernel Hackers Manual July 2017 disk_block_events 9 4.1.27 disk_block_events block and flush disk event checking void disk_block_events struct gendisk * disk disk disk to block events for On return from this function, it is guaranteed that event checking isn't in progress and won't happen until unblocked by disk_unblock_events. Events blocking is counted and the actual unblocking happens after the matching number of unblocks are done. Note that this intentionally does not block event checking from disk_clear_events. Might sleep. Kernel Hackers Manual July 2017 disk_unblock_events 9 4.1.27 disk_unblock_events unblock disk event checking void disk_unblock_events struct gendisk * disk disk disk to unblock events for Undo disk_block_events. When the block count reaches zero, it starts events polling if configured. Don't care. Safe to call from irq context. Kernel Hackers Manual July 2017 disk_flush_events 9 4.1.27 disk_flush_events schedule immediate event checking and flushing void disk_flush_events struct gendisk * disk unsigned int mask disk disk to check and flush events for mask events to flush Schedule immediate event checking on disk if not blocked. Events in mask are scheduled to be cleared from the driver. Note that this doesn't clear the events from disk->ev. If mask is non-zero must be called with bdev->bd_mutex held. Kernel Hackers Manual July 2017 disk_clear_events 9 4.1.27 disk_clear_events synchronously check, clear and return pending events unsigned int disk_clear_events struct gendisk * disk unsigned int mask disk disk to fetch and clear events from mask mask of events to be fetched and cleared Disk events are synchronously checked and pending events in mask are cleared and returned. This ignores the block count. Might sleep. Kernel Hackers Manual July 2017 disk_get_part 9 4.1.27 disk_get_part get partition struct hd_struct * disk_get_part struct gendisk * disk int partno disk disk to look partition from partno partition number Look for partition partno from disk. If found, increment reference count and return it. Don't care. Pointer to the found partition on success, NULL if not found. Kernel Hackers Manual July 2017 disk_part_iter_init 9 4.1.27 disk_part_iter_init initialize partition iterator void disk_part_iter_init struct disk_part_iter * piter struct gendisk * disk unsigned int flags piter iterator to initialize disk disk to iterate over flags DISK_PITER_* flags Initialize piter so that it iterates over partitions of disk. Don't care. Kernel Hackers Manual July 2017 disk_part_iter_next 9 4.1.27 disk_part_iter_next proceed iterator to the next partition and return it struct hd_struct * disk_part_iter_next struct disk_part_iter * piter piter iterator of interest Proceed piter to the next partition and return it. Don't care. Kernel Hackers Manual July 2017 disk_part_iter_exit 9 4.1.27 disk_part_iter_exit finish up partition iteration void disk_part_iter_exit struct disk_part_iter * piter piter iter of interest Called when iteration is over. Cleans up piter. Don't care. Kernel Hackers Manual July 2017 disk_map_sector_rcu 9 4.1.27 disk_map_sector_rcu map sector to partition struct hd_struct * disk_map_sector_rcu struct gendisk * disk sector_t sector disk gendisk of interest sector sector to map Find out which partition sector maps to on disk. This is primarily used for stats accounting. RCU read locked. The returned partition pointer is valid only while preemption is disabled. Found partition on success, part0 is returned if no partition matches Kernel Hackers Manual July 2017 register_blkdev 9 4.1.27 register_blkdev register a new block device int register_blkdev unsigned int major const char * name major the requested major device number [1..255]. If major=0, try to allocate any unused major number. name the name of the new block device as a zero terminated string The name must be unique within the system. The return value depends on the major input parameter. - if a major device number was requested in range [1..255] then the function returns zero on success, or a negative error code - if any unused major number was requested with major=0 parameter then the return value is the allocated major number in range [1..255] or a negative error code otherwise Kernel Hackers Manual July 2017 add_disk 9 4.1.27 add_disk add partitioning information to kernel list void add_disk struct gendisk * disk disk per-device partitioning information This function registers the partitioning information in disk with the kernel. error handling Kernel Hackers Manual July 2017 get_gendisk 9 4.1.27 get_gendisk get partitioning information for a given device struct gendisk * get_gendisk dev_t devt int * partno devt device to get partitioning information for partno returned partition index This function gets the structure containing partitioning information for the given device devt. Kernel Hackers Manual July 2017 bdget_disk 9 4.1.27 bdget_disk do bdget by gendisk and partition number struct block_device * bdget_disk struct gendisk * disk int partno disk gendisk of interest partno partition number Find partition partno from disk, do bdget on it. Don't care. Resulting block_device on success, NULL on failure. Kernel Hackers Manual July 2017 register_chrdev_region 9 4.1.27 register_chrdev_region register a range of device numbers int register_chrdev_region dev_t from unsigned count const char * name from the first in the desired range of device numbers; must include the major number. count the number of consecutive device numbers required name the name of the device or driver. Return value is zero on success, a negative error code on failure. Kernel Hackers Manual July 2017 alloc_chrdev_region 9 4.1.27 alloc_chrdev_region register a range of char device numbers int alloc_chrdev_region dev_t * dev unsigned baseminor unsigned count const char * name dev output parameter for first assigned number baseminor first of the requested range of minor numbers count the number of minor numbers required name the name of the associated device or driver Allocates a range of char device numbers. The major number will be chosen dynamically, and returned (along with the first minor number) in dev. Returns zero or a negative error code. Kernel Hackers Manual July 2017 __register_chrdev 9 4.1.27 __register_chrdev create and register a cdev occupying a range of minors int __register_chrdev unsigned int major unsigned int baseminor unsigned int count const char * name const struct file_operations * fops major major device number or 0 for dynamic allocation baseminor first of the requested range of minor numbers count the number of minor numbers required name name of this range of devices fops file operations associated with this devices If major == 0 this functions will dynamically allocate a major and return its number. If major > 0 this function will attempt to reserve a device with the given major number and will return zero on success. Returns a -ve errno on failure. The name of this device has nothing to do with the name of the device in /dev. It only helps to keep track of the different owners of devices. If your module name has only one type of devices it's ok to use e.g. the name of the module here. Kernel Hackers Manual July 2017 unregister_chrdev_region 9 4.1.27 unregister_chrdev_region return a range of device numbers void unregister_chrdev_region dev_t from unsigned count from the first in the range of numbers to unregister count the number of device numbers to unregister This function will unregister a range of count device numbers, starting with from. The caller should normally be the one who allocated those numbers in the first place... Kernel Hackers Manual July 2017 __unregister_chrdev 9 4.1.27 __unregister_chrdev unregister and destroy a cdev void __unregister_chrdev unsigned int major unsigned int baseminor unsigned int count const char * name major major device number baseminor first of the range of minor numbers count the number of minor numbers this cdev is occupying name name of this range of devices Unregister and destroy the cdev occupying the region described by major, baseminor and count. This function undoes what __register_chrdev did. Kernel Hackers Manual July 2017 cdev_add 9 4.1.27 cdev_add add a char device to the system int cdev_add struct cdev * p dev_t dev unsigned count p the cdev structure for the device dev the first device number for which this device is responsible count the number of consecutive minor numbers corresponding to this device cdev_add adds the device represented by p to the system, making it live immediately. A negative error code is returned on failure. Kernel Hackers Manual July 2017 cdev_del 9 4.1.27 cdev_del remove a cdev from the system void cdev_del struct cdev * p p the cdev structure to be removed cdev_del removes p from the system, possibly freeing the structure itself. Kernel Hackers Manual July 2017 cdev_alloc 9 4.1.27 cdev_alloc allocate a cdev structure struct cdev * cdev_alloc void void no arguments Allocates and returns a cdev structure, or NULL on failure. Kernel Hackers Manual July 2017 cdev_init 9 4.1.27 cdev_init initialize a cdev structure void cdev_init struct cdev * cdev const struct file_operations * fops cdev the structure to initialize fops the file_operations for this device Initializes cdev, remembering fops, making it ready to add to the system with cdev_add. Kernel Hackers Manual July 2017 misc_register 9 4.1.27 misc_register register a miscellaneous device int misc_register struct miscdevice * misc misc device structure Register a miscellaneous device with the kernel. If the minor number is set to MISC_DYNAMIC_MINOR a minor number is assigned and placed in the minor field of the structure. For other cases the minor number requested is used. The structure passed is linked into the kernel and may not be destroyed until it has been unregistered. By default, an open syscall to the device sets file->private_data to point to the structure. Drivers don't need open in fops for this. A zero is returned on success and a negative errno code for failure. Kernel Hackers Manual July 2017 misc_deregister 9 4.1.27 misc_deregister unregister a miscellaneous device int misc_deregister struct miscdevice * misc misc device to unregister Unregister a miscellaneous device that was previously successfully registered with misc_register. Success is indicated by a zero return, a negative errno code indicates an error. The clock framework defines programming interfaces to support software management of the system clock tree. This framework is widely used with System-On-Chip (SOC) platforms to support power management and various devices which may need custom clock rates. Note that these "clocks" don't relate to timekeeping or real time clocks (RTCs), each of which have separate frameworks. These struct clk instances may be used to manage for example a 96 MHz signal that is used to shift bits into and out of peripherals or busses, or otherwise trigger synchronous state machine transitions in system hardware. Power management is supported by explicit software clock gating: unused clocks are disabled, so the system doesn't waste power changing the state of transistors that aren't in active use. On some systems this may be backed by hardware clock gating, where clocks are gated without being disabled in software. Sections of chips that are powered but not clocked may be able to retain their last state. This low power state is often called a retention mode. This mode still incurs leakage currents, especially with finer circuit geometries, but for CMOS circuits power is mostly used by clocked state changes. Power-aware drivers only enable their clocks when the device they manage is in active use. Also, system sleep states often differ according to which clock domains are active: while a "standby" state may allow wakeup from several active domains, a "mem" (suspend-to-RAM) state may require a more wholesale shutdown of clocks derived from higher speed PLLs and oscillators, limiting the number of possible wakeup event sources. A driver's suspend method may need to be aware of system-specific clock constraints on the target sleep state. Some platforms support programmable clock generators. These can be used by external chips of various kinds, such as other CPUs, multimedia codecs, and devices with strict requirements for interface clocking. Kernel Hackers Manual July 2017 struct clk_notifier 9 4.1.27 struct clk_notifier associate a clk with a notifier struct clk_notifier { struct clk * clk; struct srcu_notifier_head notifier_head; struct list_head node; }; clk struct clk * to associate the notifier with notifier_head a blocking_notifier_head for this clk node linked list pointers A list of struct clk_notifier is maintained by the notifier code. An entry is created whenever code registers the first notifier on a particular clk. Future notifiers on that clk are added to the notifier_head. Kernel Hackers Manual July 2017 struct clk_notifier_data 9 4.1.27 struct clk_notifier_data rate data to pass to the notifier callback struct clk_notifier_data { struct clk * clk; unsigned long old_rate; unsigned long new_rate; }; clk struct clk * being changed old_rate previous rate of this clk new_rate new rate of this clk For a pre-notifier, old_rate is the clk's rate before this rate change, and new_rate is what the rate will be in the future. For a post-notifier, old_rate and new_rate are both set to the clk's current rate (this was done to optimize the implementation). Kernel Hackers Manual July 2017 clk_notifier_register 9 4.1.27 clk_notifier_register change notifier callback int clk_notifier_register struct clk * clk struct notifier_block * nb clk clock whose rate we are interested in nb notifier block with callback function pointer debugging across notifier chains can be frustrating. Make sure that your notifier callback function prints a nice big warning in case of failure. Kernel Hackers Manual July 2017 clk_notifier_unregister 9 4.1.27 clk_notifier_unregister change notifier callback int clk_notifier_unregister struct clk * clk struct notifier_block * nb clk clock whose rate we are no longer interested in nb notifier block which will be unregistered Kernel Hackers Manual July 2017 clk_get_accuracy 9 4.1.27 clk_get_accuracy obtain the clock accuracy in ppb (parts per billion) for a clock source. long clk_get_accuracy struct clk * clk clk clock source This gets the clock source accuracy expressed in ppb. A perfect clock returns 0. Kernel Hackers Manual July 2017 clk_set_phase 9 4.1.27 clk_set_phase adjust the phase shift of a clock signal int clk_set_phase struct clk * clk int degrees clk clock signal source degrees number of degrees the signal is shifted Shifts the phase of a clock signal by the specified degrees. Returns 0 on success, -EERROR otherwise. Kernel Hackers Manual July 2017 clk_get_phase 9 4.1.27 clk_get_phase return the phase shift of a clock signal int clk_get_phase struct clk * clk clk clock signal source Returns the phase shift of a clock node in degrees, otherwise returns -EERROR. Kernel Hackers Manual July 2017 clk_is_match 9 4.1.27 clk_is_match check if two clk's point to the same hardware clock bool clk_is_match const struct clk * p const struct clk * q p clk compared against q q clk compared against p Returns true if the two struct clk pointers both point to the same hardware clock node. Put differently, returns true if struct clk *p and struct clk *q share the same struct clk_core object. Returns false otherwise. Note that two NULL clks are treated as matching. Kernel Hackers Manual July 2017 clk_prepare 9 4.1.27 clk_prepare prepare a clock source int clk_prepare struct clk * clk clk clock source This prepares the clock source for use. Must not be called from within atomic context. Kernel Hackers Manual July 2017 clk_unprepare 9 4.1.27 clk_unprepare undo preparation of a clock source void clk_unprepare struct clk * clk clk clock source This undoes a previously prepared clock. The caller must balance the number of prepare and unprepare calls. Must not be called from within atomic context. Kernel Hackers Manual July 2017 clk_get 9 4.1.27 clk_get lookup and obtain a reference to a clock producer. struct clk * clk_get struct device * dev const char * id dev device for clock consumer id clock consumer ID Returns a struct clk corresponding to the clock producer, or valid IS_ERR condition containing errno. The implementation uses dev and id to determine the clock consumer, and thereby the clock producer. (IOW, id may be identical strings, but clk_get may return different clock producers depending on dev.) Drivers must assume that the clock source is not enabled. clk_get should not be called from within interrupt context. Kernel Hackers Manual July 2017 devm_clk_get 9 4.1.27 devm_clk_get lookup and obtain a managed reference to a clock producer. struct clk * devm_clk_get struct device * dev const char * id dev device for clock consumer id clock consumer ID Returns a struct clk corresponding to the clock producer, or valid IS_ERR condition containing errno. The implementation uses dev and id to determine the clock consumer, and thereby the clock producer. (IOW, id may be identical strings, but clk_get may return different clock producers depending on dev.) Drivers must assume that the clock source is not enabled. devm_clk_get should not be called from within interrupt context. The clock will automatically be freed when the device is unbound from the bus. Kernel Hackers Manual July 2017 clk_enable 9 4.1.27 clk_enable inform the system when the clock source should be running. int clk_enable struct clk * clk clk clock source If the clock can not be enabled/disabled, this should return success. May be called from atomic contexts. Returns success (0) or negative errno. Kernel Hackers Manual July 2017 clk_disable 9 4.1.27 clk_disable inform the system when the clock source is no longer required. void clk_disable struct clk * clk clk clock source Inform the system that a clock source is no longer required by a driver and may be shut down. May be called from atomic contexts. if the clock source is shared between multiple drivers, clk_enable calls must be balanced by the same number of clk_disable calls for the clock source to be disabled. Kernel Hackers Manual July 2017 clk_get_rate 9 4.1.27 clk_get_rate obtain the current clock rate (in Hz) for a clock source. This is only valid once the clock source has been enabled. unsigned long clk_get_rate struct clk * clk clk clock source Kernel Hackers Manual July 2017 clk_put 9 4.1.27 clk_put "free" the clock source void clk_put struct clk * clk clk clock source drivers must ensure that all clk_enable calls made on this clock source are balanced by clk_disable calls prior to calling this function. clk_put should not be called from within interrupt context. Kernel Hackers Manual July 2017 devm_clk_put 9 4.1.27 devm_clk_put "free" a managed clock source void devm_clk_put struct device * dev struct clk * clk dev device used to acquire the clock clk clock source acquired with devm_clk_get drivers must ensure that all clk_enable calls made on this clock source are balanced by clk_disable calls prior to calling this function. clk_put should not be called from within interrupt context. Kernel Hackers Manual July 2017 clk_round_rate 9 4.1.27 clk_round_rate adjust a rate to the exact rate a clock can provide long clk_round_rate struct clk * clk unsigned long rate clk clock source rate desired clock rate in Hz Returns rounded clock rate in Hz, or negative errno. Kernel Hackers Manual July 2017 clk_set_rate 9 4.1.27 clk_set_rate set the clock rate for a clock source int clk_set_rate struct clk * clk unsigned long rate clk clock source rate desired clock rate in Hz Returns success (0) or negative errno. Kernel Hackers Manual July 2017 clk_has_parent 9 4.1.27 clk_has_parent check if a clock is a possible parent for another bool clk_has_parent struct clk * clk struct clk * parent clk clock source parent parent clock source This function can be used in drivers that need to check that a clock can be the parent of another without actually changing the parent. Returns true if parent is a possible parent for clk, false otherwise. Kernel Hackers Manual July 2017 clk_set_rate_range 9 4.1.27 clk_set_rate_range set a rate range for a clock source int clk_set_rate_range struct clk * clk unsigned long min unsigned long max clk clock source min desired minimum clock rate in Hz, inclusive max desired maximum clock rate in Hz, inclusive Returns success (0) or negative errno. Kernel Hackers Manual July 2017 clk_set_min_rate 9 4.1.27 clk_set_min_rate set a minimum clock rate for a clock source int clk_set_min_rate struct clk * clk unsigned long rate clk clock source rate desired minimum clock rate in Hz, inclusive Returns success (0) or negative errno. Kernel Hackers Manual July 2017 clk_set_max_rate 9 4.1.27 clk_set_max_rate set a maximum clock rate for a clock source int clk_set_max_rate struct clk * clk unsigned long rate clk clock source rate desired maximum clock rate in Hz, inclusive Returns success (0) or negative errno. Kernel Hackers Manual July 2017 clk_set_parent 9 4.1.27 clk_set_parent set the parent clock source for this clock int clk_set_parent struct clk * clk struct clk * parent clk clock source parent parent clock source Returns success (0) or negative errno. Kernel Hackers Manual July 2017 clk_get_parent 9 4.1.27 clk_get_parent get the parent clock source for this clock struct clk * clk_get_parent struct clk * clk clk clock source Returns struct clk corresponding to parent clock source, or valid IS_ERR condition containing errno. Kernel Hackers Manual July 2017 clk_get_sys 9 4.1.27 clk_get_sys get a clock based upon the device name struct clk * clk_get_sys const char * dev_id const char * con_id dev_id device name con_id connection ID Returns a struct clk corresponding to the clock producer, or valid IS_ERR condition containing errno. The implementation uses dev_id and con_id to determine the clock consumer, and thereby the clock producer. In contrast to clk_get this function takes the device name instead of the device itself for identification. Drivers must assume that the clock source is not enabled. clk_get_sys should not be called from within interrupt context. Kernel Hackers Manual July 2017 clk_add_alias 9 4.1.27 clk_add_alias add a new clock alias int clk_add_alias const char * alias const char * alias_dev_name char * id struct device * dev alias name for clock alias alias_dev_name device name id platform specific clock name dev device Allows using generic clock names for drivers by adding a new alias. Assumes clkdev, see clkdev.h for more info.