The Kernel Core API Manual Release 4.13.0-Rc4+
Total Page:16
File Type:pdf, Size:1020Kb
The kernel core API manual Release 4.13.0-rc4+ The kernel development community Sep 05, 2017 CONTENTS 1 Core utilities 3 2 Interfaces for kernel debugging 225 Index 237 i ii The kernel core API manual, Release 4.13.0-rc4+ This is the beginning of a manual for core kernel APIs. The conversion (and writing!) of documents for this manual is much appreciated! CONTENTS 1 The kernel core API manual, Release 4.13.0-rc4+ 2 CONTENTS CHAPTER ONE CORE UTILITIES 1.1 The Linux Kernel API 1.1.1 Data Types Doubly Linked Lists void list_add(struct list_head * new, struct list_head * head) add a new entry Parameters struct list_head * new new entry to be added struct list_head * head list head to add it after Description Insert a new entry after the specified head. This is good for implementing stacks. void list_add_tail(struct list_head * new, struct list_head * head) add a new entry Parameters struct list_head * new new entry to be added struct list_head * head list head to add it before Description Insert a new entry before the specified head. This is useful for implementing queues. void __list_del_entry(struct list_head * entry) deletes entry from list. Parameters struct list_head * entry the element to delete from the list. Note list_empty() on entry does not return true after this, the entry is in an undefined state. void list_replace(struct list_head * old, struct list_head * new) replace old entry by new one Parameters struct list_head * old the element to be replaced struct list_head * new the new element to insert Description If old was empty, it will be overwritten. 3 The kernel core API manual, Release 4.13.0-rc4+ void list_del_init(struct list_head * entry) deletes entry from list and reinitialize it. Parameters struct list_head * entry the element to delete from the list. void list_move(struct list_head * list, struct list_head * head) delete from one list and add as another’s head Parameters struct list_head * list the entry to move struct list_head * head the head that will precede our entry void list_move_tail(struct list_head * list, struct list_head * head) delete from one list and add as another’s tail Parameters struct list_head * list the entry to move struct list_head * head the head that will follow our entry int list_is_last(const struct list_head * list, const struct list_head * head) tests whether list is the last entry in list head Parameters const struct list_head * list the entry to test const struct list_head * head the head of the list int list_empty(const struct list_head * head) tests whether a list is empty Parameters const struct list_head * head the list to test. int list_empty_careful(const struct list_head * head) tests whether a list is empty and not being modified Parameters const struct list_head * head the list to test Description tests whether a list is empty _and_ checks that no other CPU might be in the process of modifying either member (next or prev) NOTE using list_empty_careful() without synchronization can only be safe if the only activity that can happen to the list entry is list_del_init(). Eg. it cannot be used if another CPU could re-list_add() it. void list_rotate_left(struct list_head * head) rotate the list to the left Parameters struct list_head * head the head of the list int list_is_singular(const struct list_head * head) tests whether a list has just one entry. Parameters const struct list_head * head the list to test. void list_cut_position(struct list_head * list, struct list_head * head, struct list_head * entry) cut a list into two 4 Chapter 1. Core utilities The kernel core API manual, Release 4.13.0-rc4+ Parameters struct list_head * list a new list to add all removed entries struct list_head * head a list with entries struct list_head * entry an entry within head, could be the head itself and if so we won’t cut the list Description 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. void list_splice(const struct list_head * list, struct list_head * head) join two lists, this is designed for stacks Parameters const struct list_head * list the new list to add. struct list_head * head the place to add it in the first list. void list_splice_tail(struct list_head * list, struct list_head * head) join two lists, each list being a queue Parameters struct list_head * list the new list to add. struct list_head * head the place to add it in the first list. void list_splice_init(struct list_head * list, struct list_head * head) join two lists and reinitialise the emptied list. Parameters struct list_head * list the new list to add. struct list_head * head the place to add it in the first list. Description The list at list is reinitialised void list_splice_tail_init(struct list_head * list, struct list_head * head) join two lists and reinitialise the emptied list Parameters struct list_head * list the new list to add. struct list_head * head the place to add it in the first list. Description Each of the lists is a queue. The list at list is reinitialised list_entry(ptr, type, member) get the struct for this entry Parameters 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. list_first_entry(ptr, type, member) get the first element from a list Parameters ptr the list head to take the element from. 1.1. The Linux Kernel API 5 The kernel core API manual, Release 4.13.0-rc4+ type the type of the struct this is embedded in. member the name of the list_head within the struct. Description Note, that list is expected to be not empty. list_last_entry(ptr, type, member) get the last element from a list Parameters 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. Description Note, that list is expected to be not empty. list_first_entry_or_null(ptr, type, member) get the first element from a list Parameters 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. Description Note that if the list is empty, it returns NULL. list_next_entry(pos, member) get the next element in list Parameters pos the type * to cursor member the name of the list_head within the struct. list_prev_entry(pos, member) get the prev element in list Parameters pos the type * to cursor member the name of the list_head within the struct. list_for_each(pos, head) iterate over a list Parameters pos the struct list_head to use as a loop cursor. head the head for your list. list_for_each_prev(pos, head) iterate over a list backwards Parameters pos the struct list_head to use as a loop cursor. head the head for your list. 6 Chapter 1. Core utilities The kernel core API manual, Release 4.13.0-rc4+ list_for_each_safe(pos, n, head) iterate over a list safe against removal of list entry Parameters 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. list_for_each_prev_safe(pos, n, head) iterate over a list backwards safe against removal of list entry Parameters 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. list_for_each_entry(pos, head, member) iterate over list of given type Parameters 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. list_for_each_entry_reverse(pos, head, member) iterate backwards over list of given type. Parameters 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. list_prepare_entry(pos, head, member) prepare a pos entry for use in list_for_each_entry_continue() Parameters 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. Description Prepares a pos entry for use as a start point in list_for_each_entry_continue(). list_for_each_entry_continue(pos, head, member) continue iteration over list of given type Parameters 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. Description Continue to iterate over list of given type, continuing after the current position. 1.1. The Linux Kernel API 7 The kernel core API manual, Release 4.13.0-rc4+ list_for_each_entry_continue_reverse(pos, head, member) iterate backwards from the given point Parameters 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. Description Start to iterate over list of given type backwards, continuing after the current position. list_for_each_entry_from(pos, head, member) iterate over list of given type from the current point Parameters 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. Description Iterate over list of given type, continuing from current position. list_for_each_entry_from_reverse(pos, head, member) iterate backwards over list of given type from the current point Parameters 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. Description Iterate backwards over list of given type, continuing from current position. list_for_each_entry_safe(pos, n, head, member) iterate over list of given type safe against removal of list entry Parameters pos the type * to use as a loop cursor.