【内核】内核链表使用说明，list.h注释

list_entry定义

/**
* list_entry - get the struct for this entry
* @ptr:        the &struct list_head pointer.
* @type:       the type of the struct this is embedded in.
* @member:     the name of the list_struct within the struct.
*/
#define list_entry(ptr, type, member) /
        ((type *)((char *)(ptr)-(unsigned long)(&((type *))->member)))

　　在Linux内核中，函数list_entry()用来获取节点地址.

　　其不难理解为:从一个结构的成员指针找到其容器的指针。

1. ptr是找容器的那个变量的指针，把它减去自己在容器中的偏移量的值就应该 得到容器的指针。（容器就是包含自己的那个结构）。
2. 指针的加减要注意类型，用(char*)ptr是为了计算字节偏移。
3. ((type *)0)->member是一个小技巧。
4. 前面的（type *）再转回容器的类型。

#define list_entry(ptr, type, member) /
        ((type *)((char *)(ptr)-(unsigned long)(&((type *))->member))

• ptr是指向list_head类型链表的指针
• type为一个结构
• 而member为结构type中的一个域，类型为list_head
• 这个宏返回指向type结构的指针

　　在内核代码中大量引用了这个宏，因此，搞清楚这个宏的含义和用法非常重要。

设有如下结构体定义：

typedef struct xxx
{
     ……（结构体中其他域，令其总大小为size1）
     type1 member;
     ……（结构体中其他域）
}type;

定义变量：

type a;
type * b;
type1 * ptr;

执行：

ptr=&(a.member);
b=list_entry(ptr,type,member);

　　这样就使b指向a，得到了a的地址。

如何做到的呢？

&((type *))->member

　　把“0”强制转化为指针类型，则该指针一定指向“0”（数据段基址）。

　　因为指针是“type *”型的，所以可取到以“0”为基地址的一个type型变量member域的地址。

　　那么这个地址也就等于member域到结构体基地址的偏移字节数。

 ((type *)((char *)(ptr)-(unsigned long)(&((type *))->member)))

　　(char *)(ptr)使得指针的加减操作步长为一字节，(unsigned long)(&((type *)0)->member)等于ptr指向的member到该member所在结构体基地址的偏移字节数。二者一减便得出该结构体的地址。转换为 (type *)型的指针，便大功告成。

---

list.h注释

　　每一个熟悉内核的程序员，写出来的程序会更加优美和高效，因为内核代码本身就是优美和高效的，我们可以加以借荐；

　　但是内核的庞大程度与复杂的各种结构使很多人望而生畏，因此我把经常使用的内核链表核心文件给加了注释，以方便使用。

 //################  注释：By 成鹏致远　    ################//
 //################  net ：infodown.tap.cn　################//
 //################  time：2013-7-30     　 ################//

 #ifndef __DLIST_H
 #define __DLIST_H

 /* This file is from Linux Kernel (include/linux/list.h)    //————————>位置
 * and modified by simply removing hardware prefetching of list items.    //————————>在预处理阶段对链表项进行替换
 * Here by copyright, credits attributed to wherever they belong.
 * Kulesh Shanmugasundaram (kulesh [squiggly] isis.poly.edu)
 */

 /*
 * Simple doubly linked list implementation.    //————————>简单的双向链表实现
 *
 * Some of the internal functions (“__xxx”) are useful when
 * manipulating whole lists rather than single entries, as    //————————>最好对整个链表进行操作
 * sometimes we already know the next/prev entries and we can
 * generate better code by using them directly rather than
 * using the generic single-entry routines.
 */

 //################ 通过内部结构指针返回外部容器指针　################//
 /**
  * container_of - cast a member of a structure out to the containing structure    //————————>container_of：从一个结构的成员指针找到其容器的指针
  *
  * @ptr:    the pointer to the member.    //————————>ptr：指向menber的指针，即找容器的那个变量的指针
  * @type:    the type of the container struct this is embedded in.    //————————>type：容器的类型
  * @member:    the name of the member within the struct.    //————————>member：容器中struct类型成员
  *
  */
 #define offsetof(TYPE, MEMBER) ((size_t) &((TYPE *)0)->MEMBER)            //————————>offsetof：TYPE结构类型中MEMBER结构指针与TYPE结构指针的偏移量

 #define container_of(ptr, type, member) ({            \                    //————————>container_of：从一个结构的成员指针找到其容器的指针
         const typeof( ((type *))->member ) *__mptr = (ptr);    \        //————————>ptr：指向menber的指针，即找容器的那个变量的指针
         (type *)( (char *)__mptr - offsetof(type,member) );})            //————————>type：容器的类型
                                                                         //————————>member：容器中struct类型成员

 //################ 链表初始化　################//
 /*
  * These are non-NULL pointers that will result in page faults    //————————>野指针会导致页面出错
  * under normal circumstances, used to verify that nobody uses    //————————>以下初始化方法保证了不会出现野指针（确认没有空指针传入）
  * non-initialized list entries.
  */
 #define LIST_POISON1  ((void *) 0x00100100)
 #define LIST_POISON2  ((void *) 0x00200

 struct list_head {    //————————>内核链表结构
     struct list_head *next, *prev;
 };

 #define LIST_HEAD_INIT(name) { &(name), &(name) }    //————————>LIST_HEAD_INIT(name)：用name来初始化链表

 #define LIST_HEAD(name) \    //————————>LIST_HEAD(name)：间接用LIST_HEAD_INIT(name)来初始化链表，本质：LIST_HEAD(name)用来定义+初始化
 struct list_head name = LIST_HEAD_INIT(name)

 #define INIT_LIST_HEAD(ptr) do { \    //————————>运行时初始化，功能相同：初始化
     (ptr)->next = (ptr); (ptr)->prev = (ptr); \
 } while ()

 //################ 链表插入算法　################//
 /*
 * Insert a new entry between two known consecutive entries.    //————————>在两个连续的结点间插入新的结点
 *
 * This is only for internal list manipulation where we know    //————————>只能用于操作已知prev和next指针的内部链表
 * the prev/next entries already!
 */
 static inline void __list_add(struct list_head *new,    //————————>__list_add：内联静态函数
                 struct list_head *prev,                    //————————>参数：三个指向list_head的结构体指针（新结点，前向结点，后向结点）
                 struct list_head *next)
 {
     next->prev = new;    //————————>双向链表中插入new结点
     new->next = next;
     new->prev = prev;
     prev->next = new;
 }

 /**
 * list_add – add a new entry    //————————>list_add：头插法增加新节点
 * @new: new entry to be added    //————————>new：新节点指针
 * @head: list head to add it after    //————————>head：链表头结点指针，在之后插入
 *
 * Insert a new entry after the specified head.    //————————>头插法
 * This is good for implementing stacks.    //————————>符合栈操作
 */
 static inline void list_add(struct list_head *new, struct list_head *head)    //————————>list_add：在head后面插入new
 {                                                                            //————————>new：新节点指针
     __list_add(new, head, head->next);                                        //————————>head：链表头结点指针
 }

 /**
 * list_add_tail – add a new entry    //————————>list_add_tail ：尾插法增加新节点
 * @new: new entry to be added    //————————>new：新节点指针
 * @head: list head to add it beforer    //————————>head：链表头结点指针，在之前插入
 *
 * Insert a new entry before the specified head.
 * This is useful for implementing queues.    //————————>符合队列操作
 */
 static inline void list_add_tail(struct list_head *new, struct list_head *head)    //————————>list_add_tail ：在head前面插入new
 {
     __list_add(new, head->prev, head);
 }

 //################ 链表删除算法　################//
 /*
 * Delete a list entry by making the prev/next entries    //————————>通过改变prev和next的指向来删除节点
 * point to each other.
 *
 * This is only for internal list manipulation where we know    //————————>同样只能用于操作已知prev和next指针的内部链表
 * the prev/next entries already!
 */
 static inline void __list_del(struct list_head *prev, struct list_head *next)    //————————>__list_del：删除结点
 {                                                                                //————————>prev：待删除结点的前向指针
     next->prev = prev;                                                            //————————>next：待删除结点的后向指针
     prev->next = next;
 }

 /**
 * list_del – deletes entry from list.    //————————>list_del：删除节点
 * @entry: the element to delete from the list.    //————————>entry：要删除的结点
 * Note: list_empty on entry does not return true after this, the entry is in an undefined state.    //————————>操作后调用list_empty则返回随机值
 */
 static inline void list_del(struct list_head *entry)    //————————>删除entry结点
 {
     __list_del(entry->prev, entry->next);
     entry->next = (void *) ;    //————————>置空
     entry->prev = (void *) ;
 }

 /**
 * list_del_init – deletes entry from list and reinitialize it.    //————————>list_del_init：删除并初始化节点
 * @entry: the element to delete from the list.
 */
 static inline void list_del_init(struct list_head *entry)    //————————>删除并初始化entry指向的结点
 {
     __list_del(entry->prev, entry->next);    //————————>删除
     INIT_LIST_HEAD(entry);    //————————>然后初始化
 }

 //################ 链表移动算法　################//
 /**
 * list_move – delete from one list and add as another’s head    //————————>list_move：从链表中删除一个节点并添加到另一个链表头部
 * @list: the entry to move    //————————>list：要移动的节点
 * @head: the head that will precede our entry    //————————>head：目标链表的头结点
 */
 static inline void list_move(struct list_head *list,    //————————>list_move：从链表中删除list并添加到head后面
                 struct list_head *head)
 {
     __list_del(list->prev, list->next);    //————————>先删除
     list_add(list, head);    //————————>然后在head后面添加list
 }

 /**
 * list_move_tail – delete from one list and add as another’s tail    //————————>list_move_tail：从链表中删除一个节点并添加到另一个链表尾部
 * @list: the entry to move
 * @head: the head that will follow our entry
 */
 static inline void list_move_tail(struct list_head *list,    //————————>list_move_tail：从链表中删除list并添加到head前部
                     struct list_head *head)
 {
     __list_del(list->prev, list->next);    //————————>先删除
     list_add_tail(list, head);    //————————>然后在head前面添加list
 }

 //################ 判断链表空状态　################//
 /**
 * list_empty – tests whether a list is empty
 * @head: the list to test.
 */
 static inline int list_empty(struct list_head *head)    //————————>list_empty：判断head指向的链表是否为空
 {
     return head->next == head;    //————————>只有一个头结点
 }

 //################ 链表合并算法　################//

 static inline void __list_splice(struct list_head *list,    //————————>__list_splice：将list链表合并到head链表上
                     struct list_head *head)
 {
     struct list_head *first = list->next;    //————————>list的首结点
     struct list_head *last = list->prev;    //————————>list的尾结点
     struct list_head *at = head->next;    //————————>head的首结点
                         //————————>将list所以结点链接到head的后面
     first->prev = head;    //————————>list首结点向前指向head
     head->next = first;    //————————>head向后指向list的首结点

     last->next = at;    //————————>list的尾结点向后指向head的首结点
     at->prev = last;    //————————>head的首结点向前指向list的尾结点
 }

 /**
 * list_splice – join two lists    //————————>list_splice：合并两个链表
 * @list: the new list to add.    //————————>list：要合并的链表
 * @head: the place to add it in the first list.    //————————>目标链表
 */
 static inline void list_splice(struct list_head *list, struct list_head *head)    //————————>list_splice：将list合并到head后面
 {
 if (!list_empty(list))    //————————>条件：list链表不为空
 __list_splice(list, head);
 }

 /**
 * list_splice_init – join two lists and reinitialise the emptied list.    //————————>list_splice_init：合并两个链表并重新初始化被链接的链表2013-7-30
 * @list: the new list to add.    //————————>list：要合并的链表
 * @head: the place to add it in the first list.    //————————>目标链表
 *
 * The list at @list is reinitialised    //————————>list：被重新初始化
 */
 static inline void list_splice_init(struct list_head *list,    //————————>list_splice_init：将list合并到head，并重新初始化list
 struct list_head *head)
 {
 if (!list_empty(list)) {    //————————>条件：list链表不为空
 __list_splice(list, head);
 INIT_LIST_HEAD(list);
 }
 }

 //################ 通过内部结构指针返回外部容器指针　################//
 /**
 * list_entry – get the struct for this entry    //————————>list_entry：得到结点的外部结构地址
 * @ptr:    the &struct list_head pointer.    //————————>ptr：指向struct list_head类型链表的指针
 * @type:    the type of the struct this is embedded in.    //————————>type：包含结点的结构体类型
 * @member:    the name of the list_struct within the struct.    //————————>member：type结构中的结点类型
 */
 #define list_entry(ptr, type, member) \                            //————————>list_entry：得到type结构的指针
 ((type *)((char *)(ptr)-(unsigned long)(&((type *))->member)))    //————————>ptr：指向struct list_head类型链表的指针
                                                                 //————————>type：包含结点的结构体类型
                                                                 //————————>member：type结构中的结点类型

 //################ 链表遍历算法　################//
 /**
 * list_for_each    -    iterate over a list    //————————>list_for_each：迭代一个链表
 * @pos:    the &struct list_head to use as a loop counter.    //————————>pos：循环计数器，struct list_head类型
 * @head:    the head for your list.    //————————>遍历链表头指针
 */
 #define list_for_each(pos, head) \    //————————>list_for_each：利用for循环迭代head指向的链表
 for (pos = (head)->next; pos != (head); \
 pos = pos->next)    //————————>通过next指针逐项后移

 /**
 * list_for_each_prev    -    iterate over a list backwards    //————————>list_for_each_prev：反向迭代一个链表
 * @pos:    the &struct list_head to use as a loop counter.    //————————>pos：循环计数器，struct list_head类型
 * @head:    the head for your list.    //————————>遍历链表头指针
 */
 #define list_for_each_prev(pos, head) \    //————————>list_for_each_prev：利用for循环反向迭代head指向的链表
 for (pos = (head)->prev; pos != (head); \
 pos = pos->prev)    //————————>也是通过next指针逐项后移

 /**
 * list_for_each_safe    -    iterate over a list safe against removal of list entry    //————————>list_for_each_safe：迭代一个链表
 * @pos:    the &struct list_head to use as a loop counter.
 * @n:        another &struct list_head to use as temporary storage    //————————>多用一个临时辅助变量进行迭代
 * @head:    the head for your list.
 */
 #define list_for_each_safe(pos, n, head) \
 for (pos = (head)->next, n = pos->next; pos != (head); \
 pos = n, n = pos->next)

 /**
 * list_for_each_entry    -    iterate over list of given type    //————————>list_for_each_entry：遍历链表中的内核链表容器结构
 * @pos:    the type * to use as a loop counter.    //————————>数据项结构指针类型，指向外部结构体
 * @head:    the head for your list.    //————————>遍历链表头指针
 * @member:    the name of the list_struct within the struct.    //————————>链表中结构成员的名字
 */
 #define list_for_each_entry(pos, head, member)                \    //————————>list_for_each_entry：遍历head指向的链表的容器结构（外部结构体）
 for (pos = list_entry((head)->next, typeof(*pos), member);    \
 &pos->member != (head);                     \
 pos = list_entry(pos->member.next, typeof(*pos), member))    //————————>通过list_entry传入next来遍历外部结构

 /**
 * list_for_each_entry_safe – iterate over list of given type safe against removal of list entry    //————————>llist_for_each_entry_safe：遍历链表中的内核链表容器结构
 * @pos:    the type * to use as a loop counter.
 * @n:        another type * to use as temporary storage    //————————>多用一个临时辅助变量进行迭代
 * @head:    the head for your list.
 * @member:    the name of the list_struct within the struct.
 */
 #define list_for_each_entry_safe(pos, n, head, member)            \    //————————>list_for_each_entry_safe：遍历head指向的链表的容器结构（外部结构体）
 for (pos = list_entry((head)->next, typeof(*pos), member),    \
 n = list_entry(pos->member.next, typeof(*pos), member);    \
 &pos->member != (head);                     \
 pos = n, n = list_entry(n->member.next, typeof(*n), member))

 #endif