From 92b8d13f2c0acb333b8f2fd045ea9a1d9195a99e Mon Sep 17 00:00:00 2001 From: gatieme Date: Fri, 3 Jun 2016 11:28:40 +0800 Subject: [PATCH] =?UTF-8?q?Linux=E8=BF=9B=E7=A8=8B=E5=86=85=E6=A0=B8?= =?UTF-8?q?=E6=A0=88=E4=B8=8Ethread=5Finfo=E7=BB=93=E6=9E=84=E8=AF=A6?= =?UTF-8?q?=E8=A7=A3--Linux=E8=BF=9B=E7=A8=8B=E7=9A=84=E7=AE=A1=E7=90=86?= =?UTF-8?q?=E4=B8=8E=E8=B0=83=E5=BA=A6=EF=BC=88=E4=B9=9D=EF=BC=89--http://?= =?UTF-8?q?blog.csdn.net/gatieme/article/details/51577479?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../02-create/06-thread_info/README.md | 316 ++++++++++++++++++ .../06-thread_info/images/thread_info.gif | Bin 0 -> 14645 bytes .../kernel_thread/Makefile | 0 .../kernel_thread/test_kernel_thread.c | 0 .../.test_kthread_create.ko.cmd | 0 .../.test_kthread_create.mod.o.cmd | 0 .../kthread_create/.test_kthread_create.o.cmd | 0 .../kthread_create/Makefile | 0 .../kthread_create/Module.symvers | 0 .../kthread_create/modules.order | 0 .../kthread_create/test_kthread_create.c | 0 .../kthread_create/test_kthread_create.c.2 | 0 .../kthread_create/test_kthread_create.mod.c | 0 .../kthread_run/Makefile | 0 .../kthread_run/test_kthread_run.c | 0 .../kthread_run/test_kthread_run.c.2 | 0 16 files changed, 316 insertions(+) create mode 100644 study/kernel/01-process/02-create/06-thread_info/README.md create mode 100644 study/kernel/01-process/02-create/06-thread_info/images/thread_info.gif rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kernel_thread/Makefile (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kernel_thread/test_kernel_thread.c (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_create/.test_kthread_create.ko.cmd (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_create/.test_kthread_create.mod.o.cmd (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_create/.test_kthread_create.o.cmd (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_create/Makefile (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_create/Module.symvers (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_create/modules.order (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_create/test_kthread_create.c (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_create/test_kthread_create.c.2 (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_create/test_kthread_create.mod.c (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_run/Makefile (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_run/test_kthread_run.c (100%) rename study/kernel/01-process/02-create/{06-kernel_thead => 07-kernel_thead}/kthread_run/test_kthread_run.c.2 (100%) diff --git a/study/kernel/01-process/02-create/06-thread_info/README.md b/study/kernel/01-process/02-create/06-thread_info/README.md new file mode 100644 index 0000000..237d3d7 --- /dev/null +++ b/study/kernel/01-process/02-create/06-thread_info/README.md @@ -0,0 +1,316 @@ +Linux进程内核栈与thread_info结构详解 +======= + +| 日期 | 内核版本 | 架构| 作者 | GitHub| CSDN | +| ------------- |:-------------:|:-------------:|:-------------:|:-------------:|:-------------:| +| 2016-06-02 | [Linux-4.5](http://lxr.free-electrons.com/source/?v=4.5) | X86 & arm | [gatieme](http://blog.csdn.net/gatieme) | [LinuxDeviceDrivers](https://github.com/gatieme/LDD-LinuxDeviceDrivers) | [Linux进程管理与调度-之-进程的描述](http://blog.csdn.net/gatieme/article/category/6225543) | + + + +#前言 +------- + + +##为什么需要内核栈 +------- + +* 进程在内核态运行时需要自己的堆栈信息, 因此linux内核为每个进程都提供了一个内核栈kernel stack, + +```c +struct task_struct +{ + // ... + void *stack; // 指向内核栈的指针 + // ... +}; +``` + +内核态的进程访问处于内核数据段的栈，这个栈不同于用户态的进程所用的栈。 + +用户态进程所用的栈，是在进程线性地址空间中； + +而内核栈是当进程从用户空间进入内核空间时，特权级发生变化，需要切换堆栈，那么内核空间中使用的就是这个内核栈。因为内核控制路径使用很少的栈空间，所以只需要几千个字节的内核态堆栈。 + +>需要注意的是，**内核态堆栈**仅用于内核例程，Linux内核另外为中断提供了单独的**硬中断栈**和**软中断栈** + + +##为什么需要thread_info +------- + +* 内核还需要存储每个进程的PCB信息, linux内核是支持不同体系的的, 但是不同的体系结构可能进程需要存储的信息不尽相同, 这就需要我们实现一种通用的方式, 我们将体系结构相关的部分和无关的部门进行分离 + +用一种通用的方式来描述进程, 这就是struct task_struct, 而thread_info就保存了特定体系结构的汇编代码段需要访问的那部分进程的数据,我们在thread_info中嵌入指向task_struct的指针, 则我们可以很方便的通过thread_info来查找task_struct + + +##将两种结构融合在一起 +------- + +linux将内核栈和进程控制块thread_info融合在一起, 组成一个联合体thread_union + +通常内核栈和thread_info一同保存在一个联合体中, thread_info保存了线程所需的所有特定处理器的信息, 以及通用的task_struct的指针 + + + +#内核数据结构描述 +------- + +##thread_union +------- + +对每个进程，Linux内核都把两个不同的数据结构紧凑的存放在一个单独为进程分配的内存区域中： + +* 一个是内核态的进程堆栈stack + +* 另一个是紧挨着进程描述符的小数据结构thread_info，叫做线程描述符。 + + +这两个结构被紧凑的放在一个联合体中thread_union中, +```c +union thread_union +{ + struct thread_info thread_info; + unsigned long stack[THREAD_SIZE/sizeof(long)]; +}; +``` + +这块区域32位上通常是8K=8192（占两个页框），64位上通常是16K,其实地址必须是8192的整数倍。 + +| 架构 | THREAD_SIZE | +| ------------- |:-------------:| +| x86 | [arch/x86/include/asm/page_32_types.h, line 21](http://lxr.free-electrons.com/source/arch/x86/include/asm/page_32_types.h?v=4.5#L21) | +| x86_64 | [arch/x86/include/asm/page_64_types.h, line 11](http://lxr.free-electrons.com/source/arch/x86/include/asm/page_64_types.h?v=4.5#L11) | +| arm | [arch/arm/include/asm/thread_info.h, line 20](http://lxr.free-electrons.com/source/arch/arm/include/asm/thread_info.h?v=4.5#L20) | +| arm64 | [arch/arm64/include/asm/thread_info.h, line 32](http://lxr.free-electrons.com/source/arch/arm64/include/asm/thread_info.h?v=4.5#L32) | + +出于效率考虑，内核让这8K(或者16K)空间占据连续的两个页框并让第一个页框的起始地址是213的倍数。 + + + + +下图中显示了在物理内存中存放两种数据结构的方式。线程描述符驻留与这个内存区的开始，而栈顶末端向下增长。 下图摘自ULK3,进程内核栈与进程描述符的关系如下图： + +![thread_info](./images/thread_info.gif) + + +在这个图中，esp寄存器是CPU栈指针，用来存放栈顶单元的地址。在80x86系统中，栈起始于顶端，并朝着这个内存区开始的方向增长。从用户态刚切换到内核态以后，进程的内核栈总是空的。因此，esp寄存器指向这个栈的顶端。一旦数据写入堆栈，esp的值就递减。 + +同时我们可以看到, thread_info和内核栈虽然共用了thread_union结构, 但是thread_info大小固定, 存储在联合体的开始部分, 而内核栈由高地址向低地址扩展, 当内核栈的栈顶到达thread_info的存储空间时, 则会发生栈溢出 + +##task_struct中的内核栈stack +------- + +我们之前在描述task_struct时就提到了其stack指针指向的是内核栈的地址。 + +>参见 [ Linux进程描述符task_struct结构体详解--Linux进程的管理与调度（一）](http://blog.csdn.net/gatieme/article/details/51383272#t6) + +其被定义在include/linux/sched.h中 + +>http://lxr.free-electrons.com/source/include/linux/sched.h?v=4.5#L1391 + +形式如下 + +```c +struct task_struct +{ + // ... + void *stack; // 指向内核栈的指针 + // ... +}; +``` + +在早期的linux内核中进程描述符中是不包含内核栈的, 相反包含着指向`thread_info`的指针 + +但是在2007年的一次更新(since 2.6.22)中加入了`stack`内核栈指针, 替代了原来的`thread_info`的指针 + +进程描述符task_struct结构中没有直接指向thread_info结构的指针，而是用一个void指针类型的成员表示，然后通过类型转换来访问thread_info结构。 + +stack指向了内核栈的地址(其实也就是thread_info和thread_union的地址),因为联合体中stack和thread_info都在起始地址, 因此可以很方便的转型 + +相关代码在[include/linux/sched.h](http://lxr.free-electrons.com/source/include/linux/sched.h?v=4.5#L2812)中 +task_thread_info用于通过task_struct来查找其thread_info的信息, 只需要一次指针类型转换即可 +```c +#define task_thread_info(task) ((struct thread_info *)(task)->stack) +``` + + +##内核栈数据结构描述thread_info +------- + +thread_info是体系结构相关的，结构的定义在[thread_info.h](http://lxr.free-electrons.com/ident?v=4.5;i=thread_info)中 + +| 架构 | 定义链接 | +| ------------- |:-------------:| +| x86 | [linux-4.5/arch/x86/include/asm/thread_info.h, line 55](http://lxr.free-electrons.com/source/arch/x86/include/asm/thread_info.h?v=4.5#L55) | +| arm | [linux-4.5arch/arm/include/asm/thread_info.h, line 49](http://lxr.free-electrons.com/source/arch/arm/include/asm/thread_info.h#L49) +| arm64 | [linux/4.5/arch/arm64/include/asm/thread_info.h, line 47](http://lxr.free-electrons.com/source/arch/arm64/include/asm/thread_info.h#L47) | + + + +#函数接口 +------- + + +##内核栈与thread_info的通用操作 +------- + +原则上, 只要设置了预处理器常数`__HAVE_THREAD_FUNCTIONS`通知内核, 那么各个体系结构就可以随意在stack数组中存储数据。 + +在这种情况下, 他们必须自行实现**task_thread_info**和**task_stack_page**， 这两个函数用于获取给定task_struct实例的线程信息和内核栈。 + +另外, 他们必须实现dup_task_struct中调用的函数**setup_thread_stack**, 以便确定stack成员的具体内存布局, 当前只有ia64等少数架构不依赖于内核的默认方法 + + +下标给出了不同架构的task_thread_info和task_stack_page的实现 + +| 架构 | 定义链接 | +| ------------- |:-------------:| +| ia64 | [arch/ia64/include/asm/thread_info.h, line 53](http://lxr.free-electrons.com/source/arch/ia64/include/asm/thread_info.h?v=4.5#L53) | +| 通用 | [include/linux/sched.h, line 2812](http://lxr.free-electrons.com/source/include/linux/sched.h?v=4.5#L2812) | + +```c +// 未定义__HAVE_THREAD_FUNCTIONS的时候使用内核的默认操作 +#ifndef __HAVE_THREAD_FUNCTIONS + +// 通过进程的task_struct来获取进程的thread_info +#define task_thread_info(task) ((struct thread_info *)(task)->stack) +// 通过进程的task_struct来获取进程的内核栈 +#define task_stack_page(task) ((task)->stack) + +// 初始化thread_info, 指定其存储结构的内存布局 +static inline void setup_thread_stack(struct task_struct *p, struct task_struct *org) +{ + *task_thread_info(p) = *task_thread_info(org); + task_thread_info(p)->task = p; +} + +/* + * Return the address of the last usable long on the stack. + * + * When the stack grows down, this is just above the thread + * info struct. Going any lower will corrupt the threadinfo. + * + * When the stack grows up, this is the highest address. + * Beyond that position, we corrupt data on the next page. + */ +static inline unsigned long *end_of_stack(struct task_struct *p) +{ +#ifdef CONFIG_STACK_GROWSUP + return (unsigned long *)((unsigned long)task_thread_info(p) + THREAD_SIZE) - 1; +#else + return (unsigned long *)(task_thread_info(p) + 1); +#endif +} + +#endif +``` + + + +在内核的某个特定组建使用了较多的栈空间时, 内核栈会溢出到thread_info部分, 因此内核提供了**kstack_end**函数来判断给出的地址是否位于栈的有效部分 + +```c +#ifndef __HAVE_ARCH_KSTACK_END +static inline int kstack_end(void *addr) +{ + /* Reliable end of stack detection: + * Some APM bios versions misalign the stack + */ + return !(((unsigned long)addr+sizeof(void*)-1) & (THREAD_SIZE-sizeof(void*))); +} +#endif +``` + +>前面我们在讲[_do_fork创建进程](http://blog.csdn.net/gatieme/article/details/51569932)的时候, 提到dup_task_struct会复制父进程的task_struct和thread_info实例的内容, 但是stack则与新的thread_info实例位于同一个内存, 这意味着父子进程的task_struct此时除了栈指针之外完全相同。 + +##获取当前在CPU上正在运行进程的thread_info +------- + +所有的体系结构都必须实现两个current和current_thread_info的符号定义宏或者函数, + +* current_thread_info可获得当前执行进程的thread_info实例指针, 其地址可以根据内核指针来确定, 因为thread_info总是位于起始位置, + + 因为每个进程都有自己的内核栈, 因此进程到内核栈的映射是唯一的, 那么指向内核栈的指针通常保存在一个特别保留的寄存器中(多数情况下是esp) + +* current给出了当前进程进程描述符task_struct的地址，该地址往往通过current_thread_info来确定 + current = current_thread_info()->task + + +因此我们的关键就是current_thread_info的实现了，即如何通过esp栈指针来获取当前在CPU上正在运行进程的thread_info结构。 + + +早期的版本中，不需要对64位处理器的支持，所以，内核通过简单的屏蔽掉esp的低13位有效位就可以获得thread_info结构的基地址了。 + + + +我们在下面对比了，获取正在运行的进程的thread_info的实现方式 + +| 架构 | 版本 | 定义链接 | 实现方式 | 思路解析 | +| ------------- |:-------------:|:-------------:|:-------------:|:-------------:| +| x86 | [3.14](http://lxr.free-electrons.com/ident?v=3.14;i=current_thread_info) | [current_thread_info(void)](http://lxr.free-electrons.com/source/arch/x86/include/asm/thread_info.h#L164) |return (struct thread_info *)(sp & ~(THREAD_SIZE - 1)); | 屏蔽了esp的低十三位，最终得到的是thread_info的地址 | +| x86 | [3.15](http://lxr.free-electrons.com/ident?v=3.15;i=current_thread_info) | [current_thread_info(void)](http://lxr.free-electrons.com/source/arch/x86/include/asm/thread_info.h?v=3.15#L163) | ti = (void *)(this_cpu_read_stable(kernel_stack) + KERNEL_STACK_OFFSET - THREAD_SIZE); | +| x86 | [4.1](http://lxr.free-electrons.com/ident?v=4.1&i=current_thread_info) | [current_thread_info(void)](http://lxr.free-electrons.com/source/arch/x86/include/asm/thread_info.h?v=4.1#L182) | (struct thread_info *)(current_top_of_stack() - THREAD_SIZE); + +>**早期版本** +> +>当前的栈指针(current_stack_pointer == sp)就是esp， +> +>THREAD_SIZE为8K，二进制的表示为0000 0000 0000 0000 0010 0000 0000 0000。 +> +>~(THREAD_SIZE-1)的结果刚好为1111 1111 1111 1111 1110 0000 0000 0000，第十三位是全为零，也就是刚好屏蔽了esp的低十三位，最终得到的是thread_info的地址。 + + +进程最常用的是进程描述符结构task_struct而不是thread_info结构的地址。为了获取当前CPU上运行进程的task_struct结构，内核提供了current宏，由于task_struct *task在thread_info的起始位置，该宏本质上等价于current_thread_info()->task，在[include/asm-generic/current.h](http://lxr.free-electrons.com/source/include/asm-generic/current.h?v=4.5#L6)中定义： +```c +#define get_current() (current_thread_info()->task) +#define current get_current() +``` + +这个定义是体系结构无关的，当然linux也为各个体系结构定义了更加方便或者快速的current + +>>请参见 ：http://lxr.free-electrons.com/ident?v=4.5;i=current + + +##分配和销毁thread_info +------- + +进程通过[alloc_thread_info_node](http://lxr.free-electrons.com/source/kernel/fork.c?v=4.5;#L161)函数分配它的内核栈，通过[free_thread_info](http://lxr.free-electrons.com/source/kernel/fork.c?v=4.5#L170)函数释放所分配的内核栈。 + +```c +# if THREAD_SIZE >= PAGE_SIZE +static struct thread_info *alloc_thread_info_node(struct task_struct *tsk, + int node) +{ + struct page *page = alloc_kmem_pages_node(node, THREADINFO_GFP, + THREAD_SIZE_ORDER); + + return page ? page_address(page) : NULL; +} + +static inline void free_thread_info(struct thread_info *ti) +{ + free_kmem_pages((unsigned long)ti, THREAD_SIZE_ORDER); +} +# else +static struct kmem_cache *thread_info_cache; + +static struct thread_info *alloc_thread_info_node(struct task_struct *tsk, + int node) +{ + return kmem_cache_alloc_node(thread_info_cache, THREADINFO_GFP, node); +} + +static void free_thread_info(struct thread_info *ti) +{ + kmem_cache_free(thread_info_cache, ti); +} +``` + +其中，[THREAD_SIZE_ORDER](http://lxr.free-electrons.com/ident?v=4.5;i=THREAD_SIZE_ORDER)宏的定义请查看 + +| 架构 | 版本 | 定义链接 | 实现方式 | 思路解析 | +| ------------- |:-------------:|:-------------:|:-------------:|:-------------:| +| x86 | 4.5 | [arch/x86/include/asm/page_32_types.h, line 20](http://lxr.free-electrons.com/source/arch/x86/include/asm/page_32_types.h?v=4.5#L20) | #define THREAD_SIZE_ORDER 1 | __get_free_pages函数分配2个页的内存（它的首地址是8192字节对齐的）| +| x86_64 | 4.5 | [arch/x86/include/asm/page_64_types.h, line 10](http://lxr.free-electrons.com/source/arch/x86/include/asm/page_64_types.h?v=4.5#L10)|#define THREAD_SIZE_ORDER (2 + KASAN_STACK_ORDER) + + + diff --git a/study/kernel/01-process/02-create/06-thread_info/images/thread_info.gif b/study/kernel/01-process/02-create/06-thread_info/images/thread_info.gif new file mode 100644 index 0000000000000000000000000000000000000000..f0342d52e63afaacb5655a76f168418ad8cce904 GIT binary patch literal 14645 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 qN|l-`(O77eS{Tt-T9#TmV$xW-ms