diff options
Diffstat (limited to 'Documentation/translations/zh_CN')
28 files changed, 2523 insertions, 16 deletions
diff --git a/Documentation/translations/zh_CN/accounting/index.rst b/Documentation/translations/zh_CN/accounting/index.rst new file mode 100644 index 000000000000..362e907b41f9 --- /dev/null +++ b/Documentation/translations/zh_CN/accounting/index.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/accounting/index.rst +:Translator: Yang Yang <yang.yang29@zte.com.cn> + +.. _cn_accounting_index.rst: + + +==== +计数 +==== + +.. toctree:: + :maxdepth: 1 + + psi + +Todolist: + + cgroupstats + delay-accounting + taskstats + taskstats-struct diff --git a/Documentation/translations/zh_CN/accounting/psi.rst b/Documentation/translations/zh_CN/accounting/psi.rst new file mode 100644 index 000000000000..a0ddb7bd257c --- /dev/null +++ b/Documentation/translations/zh_CN/accounting/psi.rst @@ -0,0 +1,155 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/accounting/psi.rst +:Translator: Yang Yang <yang.yang29@zte.com.cn> + +.. _cn_psi.rst: + + +================= +PSI——压力阻塞信息 +================= + +:日期: April, 2018 +:作者: Johannes Weiner <hannes@cmpxchg.org> + +当CPU、memory或IO设备处于竞争状态，业务负载会遭受时延毛刺、吞吐量降低， +及面临OOM的风险。 + +如果没有一种准确的方法度量系统竞争程度，则有两种后果：一种是用户过于节制， +未充分利用系统资源；另一种是过度使用，经常性面临业务中断的风险。 + +psi特性能够识别和量化资源竞争导致的业务中断，及其对复杂负载乃至整个系统在 +时间上的影响。 + +准确度量因资源不足造成的生产力损失，有助于用户基于硬件调整业务负载，或基 +于业务负载配置硬件。 + +psi能够实时的提供相关信息，因此系统可基于psi实现动态的负载管理。如实施 +卸载、迁移、策略性的停止或杀死低优先级或可重启的批处理任务。 + +psi帮助用户实现硬件资源利用率的最大化。同时无需牺牲业务负载健康度，也无需 +面临OOM等造成业务中断的风险。 + +压力接口 +======== + +压力信息可通过/proc/pressure/ --cpu、memory、io文件分别获取。 + +CPU相关信息格式如下： + + some avg10=0.00 avg60=0.00 avg300=0.00 total=0 + +内存和IO相关信息如下： + + some avg10=0.00 avg60=0.00 avg300=0.00 total=0 + full avg10=0.00 avg60=0.00 avg300=0.00 total=0 + +some行代表至少有一个任务阻塞于特定资源的时间占比。 + +full行代表所有非idle任务同时阻塞于特定资源的时间占比。在这种状态下CPU资源 +完全被浪费，相对于正常运行，业务负载由于耗费更多时间等待而受到严重影响。 + +由于此情况严重影响系统性能，因此清楚的识别本情况并与some行所代表的情况区分开， +将有助于分析及提升系统性能。这就是full独立于some行的原因。 + +avg代表阻塞时间占比（百分比），为最近10秒、60秒、300秒内的均值。这样我们 +既可观察到短期事件的影响，也可看到中等及长时间内的趋势。total代表总阻塞 +时间（单位微秒），可用于观察时延毛刺，这种毛刺可能在均值中无法体现。 + +监控压力门限 +============ + +用户可注册触发器，通过poll()监控资源压力是否超过门限。 + +触发器定义：指定时间窗口期内累积阻塞时间的最大值。比如可定义500ms内积累 +100ms阻塞，即触发一次唤醒事件。 + +触发器注册方法：用户打开代表特定资源的psi接口文件，写入门限、时间窗口的值。 +所打开的文件描述符用于等待事件，可使用select()、poll()、epoll()。 +写入信息的格式如下： + + <some|full> <stall amount in us> <time window in us> + +示例：向/proc/pressure/memory写入"some 150000 1000000"将新增触发器，将在 +1秒内至少一个任务阻塞于内存的总时间超过150ms时触发。向/proc/pressure/io写入 +"full 50000 1000000"将新增触发器，将在1秒内所有任务都阻塞于io的总时间超过50ms时触发。 + +触发器可针对多个psi度量值设置，同一个psi度量值可设置多个触发器。每个触发器需要 +单独的文件描述符用于轮询，以区分于其他触发器。所以即使对于同一个psi接口文件， +每个触发器也需要单独的调用open()。 + +监控器在被监控资源进入阻塞状态时启动，在系统退出阻塞状态后停用。系统进入阻塞 +状态后，监控psi增长的频率为每监控窗口刷新10次。 + +内核接受的窗口为500ms~10s，所以监控间隔为50ms~1s。设置窗口下限目的是为了 +防止过于频繁的轮询。设置窗口上限的目的是因为窗口过长则无意义，此时查看 +psi接口提供的均值即可。 + +监控器在激活后，至少在跟踪窗口期间将保持活动状态。以避免随着系统进入和退出 +阻塞状态，监控器过于频繁的进入和退出活动状态。 + +用户态通知在监控窗口内会受到速率限制。当对应的文件描述符关闭，触发器会自动注销。 + +用户态监控器使用示例 +==================== + +:: + + #include <errno.h> + #include <fcntl.h> + #include <stdio.h> + #include <poll.h> + #include <string.h> + #include <unistd.h> + + /* 监控内存部分阻塞，监控时间窗口为1秒、阻塞门限为150毫秒。*/ + int main() { + const char trig[] = "some 150000 1000000"; + struct pollfd fds; + int n; + + fds.fd = open("/proc/pressure/memory", O_RDWR | O_NONBLOCK); + if (fds.fd < 0) { + printf("/proc/pressure/memory open error: %s\n", + strerror(errno)); + return 1; + } + fds.events = POLLPRI; + + if (write(fds.fd, trig, strlen(trig) + 1) < 0) { + printf("/proc/pressure/memory write error: %s\n", + strerror(errno)); + return 1; + } + + printf("waiting for events...\n"); + while (1) { + n = poll(&fds, 1, -1); + if (n < 0) { + printf("poll error: %s\n", strerror(errno)); + return 1; + } + if (fds.revents & POLLERR) { + printf("got POLLERR, event source is gone\n"); + return 0; + } + if (fds.revents & POLLPRI) { + printf("event triggered!\n"); + } else { + printf("unknown event received: 0x%x\n", fds.revents); + return 1; + } + } + + return 0; + } + +Cgroup2接口 +=========== + +对于CONFIG_CGROUP=y及挂载了cgroup2文件系统的系统，能够获取cgroups内任务的psi。 +此场景下cgroupfs挂载点的子目录包含cpu.pressure、memory.pressure、io.pressure文件， +内容格式与/proc/pressure/下的文件相同。 + +可设置基于cgroup的psi监控器，方法与系统级psi监控器相同。 diff --git a/Documentation/translations/zh_CN/core-api/cachetlb.rst b/Documentation/translations/zh_CN/core-api/cachetlb.rst index 8376485a534d..55827b8a7c53 100644 --- a/Documentation/translations/zh_CN/core-api/cachetlb.rst +++ b/Documentation/translations/zh_CN/core-api/cachetlb.rst @@ -298,15 +298,6 @@ HyperSparc cpu就是这样一个具有这种属性的cpu。 用。默认的实现是nop（对于所有相干的架构应该保持这样）。对于不一致性 的架构，它应该刷新vmaddr处的页面缓存。 - ``void flush_kernel_dcache_page(struct page *page)`` - - 当内核需要修改一个用kmap获得的用户页时，它会在所有修改完成后（但在 - kunmapping之前）调用这个函数，以使底层页面达到最新状态。这里假定用 - 户没有不一致性的缓存副本（即原始页面是从类似get_user_pages()的机制 - 中获得的）。默认的实现是一个nop，在所有相干的架构上都应该如此。在不 - 一致性的架构上，这应该刷新内核缓存中的页面（使用page_address(page)）。 - - ``void flush_icache_range(unsigned long start, unsigned long end)`` 当内核存储到它将执行的地址中时（例如在加载模块时），这个函数被调用。 diff --git a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst new file mode 100644 index 000000000000..85a264287426 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst @@ -0,0 +1,348 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/cpu_hotplug.rst +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. _cn_core_api_cpu_hotplug: + +================= +内核中的CPU热拔插 +================= + +:时间: 2016年12月 +:作者: Sebastian Andrzej Siewior <bigeasy@linutronix.de>, + Rusty Russell <rusty@rustcorp.com.au>, + Srivatsa Vaddagiri <vatsa@in.ibm.com>, + Ashok Raj <ashok.raj@intel.com>, + Joel Schopp <jschopp@austin.ibm.com> + +简介 +==== + +现代系统架构的演进已经在处理器中引入了先进的错误报告和纠正能力。有一些OEM也支 +持可热拔插的NUMA（Non Uniform Memory Access，非统一内存访问）硬件,其中物理 +节点的插入和移除需要支持CPU热插拔。 + +这样的进步要求内核可用的CPU被移除，要么是出于配置的原因，要么是出于RAS的目的， +以保持一个不需要的CPU不在系统执行路径。因此需要在Linux内核中支持CPU热拔插。 + +CPU热拔插支持的一个更新颖的用途是它在SMP的暂停恢复支持中的应用。双核和超线程支 +持使得即使是笔记本电脑也能运行不支持这些方法的SMP内核。 + + +命令行开关 +========== + +``maxcpus=n`` + 限制启动时的CPU为 *n* 个。例如，如果你有四个CPU，使用 ``maxcpus=2`` 将只能启 + 动两个。你可以选择稍后让其他CPU上线。 + +``nr_cpus=n`` + 限制内核将支持的CPU总量。如果这里提供的数量低于实际可用的CPU数量，那么其他CPU + 以后就不能上线了。 + +``additional_cpus=n`` + 使用它来限制可热插拔的CPU。该选项设置 + ``cpu_possible_mask = cpu_present_mask + additional_cpus`` + + 这个选项只限于IA64架构。 + +``possible_cpus=n`` + 这个选项设置 ``cpu_possible_mask`` 中的 ``possible_cpus`` 位。 + + 这个选项只限于X86和S390架构。 + +``cpu0_hotplug`` + 允许关闭CPU0。 + + 这个选项只限于X86架构。 + +CPU位图 +======= + +``cpu_possible_mask`` + 系统中可能可用CPU的位图。这是用来为per_cpu变量分配一些启动时的内存，这些变量 + 不会随着CPU的可用或移除而增加/减少。一旦在启动时的发现阶段被设置，该映射就是静态 + 的，也就是说，任何时候都不会增加或删除任何位。根据你的系统需求提前准确地调整它 + 可以节省一些启动时的内存。 + +``cpu_online_mask`` + 当前在线的所有CPU的位图。在一个CPU可用于内核调度并准备接收设备的中断后，它被 + 设置在 ``__cpu_up()`` 中。当使用 ``__cpu_disable()`` 关闭一个CPU时，它被清 + 空，在此之前，所有的操作系统服务包括中断都被迁移到另一个目标CPU。 + +``cpu_present_mask`` + 系统中当前存在的CPU的位图。它们并非全部在线。当物理热拔插被相关的子系统 + （如ACPI）处理时，可以改变和添加新的位或从位图中删除，这取决于事件是 + hot-add/hot-remove。目前还没有定死规定。典型的用法是在启动时启动拓扑结构，这时 + 热插拔被禁用。 + +你真的不需要操作任何系统的CPU映射。在大多数情况下，它们应该是只读的。当设置每个 +CPU资源时，几乎总是使用 ``cpu_possible_mask`` 或 ``for_each_possible_cpu()`` +来进行迭代。宏 ``for_each_cpu()`` 可以用来迭代一个自定义的CPU掩码。 + +不要使用 ``cpumask_t`` 以外的任何东西来表示CPU的位图。 + + +使用CPU热拔插 +============= + +内核选项 *CONFIG_HOTPLUG_CPU* 需要被启用。它目前可用于多种架构，包括ARM、MIPS、 +PowerPC和X86。配置是通过sysfs接口完成的:: + + $ ls -lh /sys/devices/system/cpu + total 0 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu0 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu1 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu2 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu3 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu4 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu5 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu6 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu7 + drwxr-xr-x 2 root root 0 Dec 21 16:33 hotplug + -r--r--r-- 1 root root 4.0K Dec 21 16:33 offline + -r--r--r-- 1 root root 4.0K Dec 21 16:33 online + -r--r--r-- 1 root root 4.0K Dec 21 16:33 possible + -r--r--r-- 1 root root 4.0K Dec 21 16:33 present + +文件 *offline* 、 *online* 、*possible* 、*present* 代表CPU掩码。每个CPU文件 +夹包含一个 *online* 文件，控制逻辑上的开（1）和关（0）状态。要在逻辑上关闭CPU4:: + + $ echo 0 > /sys/devices/system/cpu/cpu4/online + smpboot: CPU 4 is now offline + +一旦CPU被关闭，它将从 */proc/interrupts* 、*/proc/cpuinfo* 中被删除，也不应该 +被 *top* 命令显示出来。要让CPU4重新上线:: + + $ echo 1 > /sys/devices/system/cpu/cpu4/online + smpboot: Booting Node 0 Processor 4 APIC 0x1 + +CPU又可以使用了。这应该对所有的CPU都有效。CPU0通常比较特殊，被排除在CPU热拔插之外。 +在X86上，内核选项 *CONFIG_BOOTPARAM_HOTPLUG_CPU0* 必须被启用，以便能够关闭CPU0。 +或者，可以使用内核命令选项 *cpu0_hotplug* 。CPU0的一些已知的依赖性: + +* 从休眠/暂停中恢复。如果CPU0处于离线状态，休眠/暂停将失败。 +* PIC中断。如果检测到PIC中断，CPU0就不能被移除。 + +如果你发现CPU0上有任何依赖性，请告知Fenghua Yu <fenghua.yu@intel.com>。 + +CPU的热拔插协作 +=============== + +下线情况 +-------- + +一旦CPU被逻辑关闭，注册的热插拔状态的清除回调将被调用，从 ``CPUHP_ONLINE`` 开始，在 +``CPUHP_OFFLINE`` 状态结束。这包括: + +* 如果任务因暂停操作而被冻结，那么 *cpuhp_tasks_frozen* 将被设置为true。 + +* 所有进程都会从这个将要离线的CPU迁移到新的CPU上。新的CPU是从每个进程的当前cpuset中 + 选择的，它可能是所有在线CPU的一个子集。 + +* 所有针对这个CPU的中断都被迁移到新的CPU上。 + +* 计时器也会被迁移到新的CPU上。 + +* 一旦所有的服务被迁移，内核会调用一个特定的例程 ``__cpu_disable()`` 来进行特定的清 + 理。 + +使用热插拔API +------------- + +一旦一个CPU下线或上线，就有可能收到通知。这对某些需要根据可用CPU数量执行某种设置或清 +理功能的驱动程序来说可能很重要:: + + #include <linux/cpuhotplug.h> + + ret = cpuhp_setup_state(CPUHP_AP_ONLINE_DYN, "X/Y:online", + Y_online, Y_prepare_down); + +*X* 是子系统， *Y* 是特定的驱动程序。 *Y_online* 回调将在所有在线CPU的注册过程中被调用。 +如果在线回调期间发生错误， *Y_prepare_down* 回调将在所有之前调用过在线回调的CPU上调 +用。注册完成后，一旦有CPU上线， *Y_online* 回调将被调用，当CPU关闭时， *Y_prepare_down* +将被调用。所有之前在 *Y_online* 中分配的资源都应该在 *Y_prepare_down* 中释放。如果在 +注册过程中发生错误，返回值 *ret* 为负值。否则会返回一个正值，其中包含动态分配状态 +（ *CPUHP_AP_ONLINE_DYN* ）的分配热拔插。对于预定义的状态，它将返回0。 + +该回调可以通过调用 ``cpuhp_remove_state()`` 来删除。如果是动态分配的状态 +（ *CPUHP_AP_ONLINE_DYN* ），则使用返回的状态。在移除热插拔状态的过程中，将调用拆解回调。 + +多个实例 +~~~~~~~~ + +如果一个驱动程序有多个实例，并且每个实例都需要独立执行回调，那么很可能应该使用 +``multi-state`` 。首先需要注册一个多状态的状态:: + + ret = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "X/Y:online, + Y_online, Y_prepare_down); + Y_hp_online = ret; + +``cpuhp_setup_state_multi()`` 的行为与 ``cpuhp_setup_state()`` 类似，只是它 +为多状态准备了回调，但不调用回调。这是一个一次性的设置。 +一旦分配了一个新的实例，你需要注册这个新实例:: + + ret = cpuhp_state_add_instance(Y_hp_online, &d->node); + +这个函数将把这个实例添加到你先前分配的 ``Y_hp_online`` 状态，并在所有在线的 +CPU上调用先前注册的回调（ ``Y_online`` ）。 *node* 元素是你的每个实例数据结构 +中的一个 ``struct hlist_node`` 成员。 + +在移除该实例时:: + + cpuhp_state_remove_instance(Y_hp_online, &d->node) + +应该被调用，这将在所有在线CPU上调用拆分回调。 + +手动设置 +~~~~~~~~ + +通常情况下，在注册或移除状态时调用setup和teamdown回调是很方便的，因为通常在CPU上线 +（下线）和驱动的初始设置（关闭）时需要执行该操作。然而，每个注册和删除功能也有一个 +_nocalls的后缀，如果不希望调用回调，则不调用所提供的回调。在手动设置（或关闭）期间， +应该使用 ``get_online_cpus()`` 和 ``put_online_cpus()`` 函数来抑制CPU热插拔操作。 + + +事件的顺序 +---------- + +热插拔状态被定义在 ``include/linux/cpuhotplug.h``: + +* ``CPUHP_OFFLINE`` ... ``CPUHP_AP_OFFLINE`` 状态是在CPU启动前调用的。 + +* ``CPUHP_AP_OFFLINE`` ... ``CPUHP_AP_ONLINE`` 状态是在CPU被启动后被调用的。 + 中断是关闭的，调度程序还没有在这个CPU上活动。从 ``CPUHP_AP_OFFLINE`` 开始， + 回调被调用到目标CPU上。 + +* ``CPUHP_AP_ONLINE_DYN`` 和 ``CPUHP_AP_ONLINE_DYN_END`` 之间的状态被保留 + 给动态分配。 + +* 这些状态在CPU关闭时以相反的顺序调用，从 ``CPUHP_ONLINE`` 开始，在 ``CPUHP_OFFLINE`` + 停止。这里的回调是在将被关闭的CPU上调用的，直到 ``CPUHP_AP_OFFLINE`` 。 + +通过 ``CPUHP_AP_ONLINE_DYN`` 动态分配的状态通常已经足够了。然而，如果在启动或关闭 +期间需要更早的调用，那么应该获得一个显式状态。如果热拔插事件需要相对于另一个热拔插事 +件的特定排序，也可能需要一个显式状态。 + +测试热拔插状态 +============== + +验证自定义状态是否按预期工作的一个方法是关闭一个CPU，然后再把它上线。也可以把CPU放到某 +些状态（例如 ``CPUHP_AP_ONLINE`` ），然后再回到 ``CPUHP_ONLINE`` 。这将模拟在 +``CPUHP_AP_ONLINE`` 之后的一个状态出现错误，从而导致回滚到在线状态。 + +所有注册的状态都被列举在 ``/sys/devices/system/cpu/hotplug/states`` :: + + $ tail /sys/devices/system/cpu/hotplug/states + 138: mm/vmscan:online + 139: mm/vmstat:online + 140: lib/percpu_cnt:online + 141: acpi/cpu-drv:online + 142: base/cacheinfo:online + 143: virtio/net:online + 144: x86/mce:online + 145: printk:online + 168: sched:active + 169: online + +要将CPU4回滚到 ``lib/percpu_cnt:online`` ，再回到在线状态，只需发出:: + + $ cat /sys/devices/system/cpu/cpu4/hotplug/state + 169 + $ echo 140 > /sys/devices/system/cpu/cpu4/hotplug/target + $ cat /sys/devices/system/cpu/cpu4/hotplug/state + 140 + +需要注意的是，状态140的清除回调已经被调用。现在重新上线:: + + $ echo 169 > /sys/devices/system/cpu/cpu4/hotplug/target + $ cat /sys/devices/system/cpu/cpu4/hotplug/state + 169 + +启用追踪事件后，单个步骤也是可见的:: + + # TASK-PID CPU# TIMESTAMP FUNCTION + # | | | | | + bash-394 [001] 22.976: cpuhp_enter: cpu: 0004 target: 140 step: 169 (cpuhp_kick_ap_work) + cpuhp/4-31 [004] 22.977: cpuhp_enter: cpu: 0004 target: 140 step: 168 (sched_cpu_deactivate) + cpuhp/4-31 [004] 22.990: cpuhp_exit: cpu: 0004 state: 168 step: 168 ret: 0 + cpuhp/4-31 [004] 22.991: cpuhp_enter: cpu: 0004 target: 140 step: 144 (mce_cpu_pre_down) + cpuhp/4-31 [004] 22.992: cpuhp_exit: cpu: 0004 state: 144 step: 144 ret: 0 + cpuhp/4-31 [004] 22.993: cpuhp_multi_enter: cpu: 0004 target: 140 step: 143 (virtnet_cpu_down_prep) + cpuhp/4-31 [004] 22.994: cpuhp_exit: cpu: 0004 state: 143 step: 143 ret: 0 + cpuhp/4-31 [004] 22.995: cpuhp_enter: cpu: 0004 target: 140 step: 142 (cacheinfo_cpu_pre_down) + cpuhp/4-31 [004] 22.996: cpuhp_exit: cpu: 0004 state: 142 step: 142 ret: 0 + bash-394 [001] 22.997: cpuhp_exit: cpu: 0004 state: 140 step: 169 ret: 0 + bash-394 [005] 95.540: cpuhp_enter: cpu: 0004 target: 169 step: 140 (cpuhp_kick_ap_work) + cpuhp/4-31 [004] 95.541: cpuhp_enter: cpu: 0004 target: 169 step: 141 (acpi_soft_cpu_online) + cpuhp/4-31 [004] 95.542: cpuhp_exit: cpu: 0004 state: 141 step: 141 ret: 0 + cpuhp/4-31 [004] 95.543: cpuhp_enter: cpu: 0004 target: 169 step: 142 (cacheinfo_cpu_online) + cpuhp/4-31 [004] 95.544: cpuhp_exit: cpu: 0004 state: 142 step: 142 ret: 0 + cpuhp/4-31 [004] 95.545: cpuhp_multi_enter: cpu: 0004 target: 169 step: 143 (virtnet_cpu_online) + cpuhp/4-31 [004] 95.546: cpuhp_exit: cpu: 0004 state: 143 step: 143 ret: 0 + cpuhp/4-31 [004] 95.547: cpuhp_enter: cpu: 0004 target: 169 step: 144 (mce_cpu_online) + cpuhp/4-31 [004] 95.548: cpuhp_exit: cpu: 0004 state: 144 step: 144 ret: 0 + cpuhp/4-31 [004] 95.549: cpuhp_enter: cpu: 0004 target: 169 step: 145 (console_cpu_notify) + cpuhp/4-31 [004] 95.550: cpuhp_exit: cpu: 0004 state: 145 step: 145 ret: 0 + cpuhp/4-31 [004] 95.551: cpuhp_enter: cpu: 0004 target: 169 step: 168 (sched_cpu_activate) + cpuhp/4-31 [004] 95.552: cpuhp_exit: cpu: 0004 state: 168 step: 168 ret: 0 + bash-394 [005] 95.553: cpuhp_exit: cpu: 0004 state: 169 step: 140 ret: 0 + +可以看到，CPU4一直下降到时间戳22.996，然后又上升到95.552。所有被调用的回调， +包括它们的返回代码都可以在跟踪中看到。 + +架构的要求 +========== + +需要具备以下功能和配置： + +``CONFIG_HOTPLUG_CPU`` + 这个配置项需要在Kconfig中启用 + +``__cpu_up()`` + 调出一个cpu的架构接口 + +``__cpu_disable()`` + 关闭CPU的架构接口，在此程序返回后，内核不能再处理任何中断。这包括定时器的关闭。 + +``__cpu_die()`` + 这实际上是为了确保CPU的死亡。实际上，看看其他架构中实现CPU热拔插的一些示例代 + 码。对于那个特定的架构，处理器被从 ``idle()`` 循环中拿下来。 ``__cpu_die()`` + 通常会等待一些per_cpu状态的设置，以确保处理器的死亡例程被调用来保持活跃。 + +用户空间通知 +============ + +在CPU成功上线或下线后，udev事件被发送。一个udev规则，比如:: + + SUBSYSTEM=="cpu", DRIVERS=="processor", DEVPATH=="/devices/system/cpu/*", RUN+="the_hotplug_receiver.sh" + +将接收所有事件。一个像这样的脚本:: + + #!/bin/sh + + if [ "${ACTION}" = "offline" ] + then + echo "CPU ${DEVPATH##*/} offline" + + elif [ "${ACTION}" = "online" ] + then + echo "CPU ${DEVPATH##*/} online" + + fi + +可以进一步处理该事件。 + +内核内联文档参考 +================ + +该API在以下内核代码中: + +include/linux/cpuhotplug.h diff --git a/Documentation/translations/zh_CN/core-api/genericirq.rst b/Documentation/translations/zh_CN/core-api/genericirq.rst new file mode 100644 index 000000000000..05ccb954c18d --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/genericirq.rst @@ -0,0 +1,409 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/genericirq.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. include:: <isonum.txt> + +.. _cn_core-api_genericirq: + +================ +Linux通用IRQ处理 +================ + +:版权: |copy| 2005-2010: Thomas Gleixner +:版权: |copy| 2005-2006: Ingo Molnar + +简介 +==== + +通用中断处理层是为了给设备驱动程序提供一个完整的中断处理抽象（层）。它能够处 +理所有不同类型的中断控制器硬件。设备驱动程序使用通用API函数来请求、启用、禁 +用和释放中断。驱动程序不需要知道任何关于硬件处理中断的细节，所以它们可以在不同的 +平台上使用而不需要修改代码。 + +本文档提供给那些希望在通用IRQ处理层的帮助下实现基于其架构的中断子系统的开发 +者。 + +理论依据 +======== + +Linux中中断处理的原始实现使用__do_IRQ()超级处理程序，它能够处理每种类型的 +中断逻辑。 + +最初，Russell King确定了不同类型的处理程序，以便为Linux 2.5/2.6中的ARM中 +断处理程序实现建立一个相当通用的集合。他区分了以下几种类型: + +- 电平触发型 + +- 边沿触发型 + +- 简单型 + +在实现过程中，我们发现了另一种类型: + +- 响应EOI（end of interrupt）型 + +在SMP的__do_IRQ()超级处理程序中，还需定义一种类型： + +- 每cpu型（针对CPU SMP） + +这种高层IRQ处理程序的拆分实现使我们能够为每个特定的中断类型优化中断处理的流 +程。这减少了该特定代码路径的复杂性，并允许对特定类型进行优化处理。 + +最初的通用IRQ实现使用hw_interrupt_type结构体及其 ``->ack`` ``->end`` 等回 +调来区分超级处理程序中的流控制。这导致了流逻辑和低级硬件逻辑的混合，也导致了 +不必要的代码重复：例如i386中的 ``ioapic_level_irq`` 和 ``ioapic_edge_irq`` ， +这两个IRQ类型共享许多低级的细节，但有不同的流处理。 + +一个更自然的抽象是“irq流”和“芯片细节”的干净分离。 + +分析一些架构的IRQ子系统的实现可以发现，他们中的大多数可以使用一套通用的“irq +流”方法，只需要添加芯片级的特定代码。这种分离对于那些需要IRQ流本身而不需要芯 +片细节的特定（子）架构也很有价值——以提供了一个更透明的IRQ子系统设计。 + +每个中断描述符都被分配给它自己的高层流程处理程序，这通常是一个通用的实现。(这 +种高层次的流程处理程序的实现也使得提供解复用处理程序变得简单，这可以在各种架 +构的嵌入式平台上找到。) + +这种分离使得通用中断处理层更加灵活和可扩展。例如，一个（子）架构可以使用通用 +的IRQ流实现“电平触发型”中断，并添加一个（子）架构特定的“边沿型”实现。 + +为了使向新模型的过渡更容易，并防止破坏现有实现，__do_IRQ()超级处理程序仍然 +可用。这导致了一种暂时的双重性。随着时间的推移，新的模型应该在越来越多的架构中 +被使用，因为它能使IRQ子系统更小更干净。它已经被废弃三年了，即将被删除。 + +已知的缺陷和假设 +================ + +没有（但愿如此）。 + +抽象层 +====== + +中断代码中主要有三个抽象层次: + +1. 高级别的驱动API + +2. 高级别的IRQ流处理器 + +3. 芯片级的硬件封装 + +中断控制流 +---------- + +每个中断都由一个中断描述符结构体irq_desc来描述。中断是由一个“无符号整型”的数值来 +引用的，它在描述符结构体数组中选择相应的中断描述符结构体。描述符结构体包含状态 +信息和指向中断流方法和中断芯片结构的指针，这些都是分配给这个中断的。 + +每当中断触发时，低级架构代码通过调用desc->handle_irq()调用到通用中断代码中。 +这个高层IRQ处理函数只使用由分配的芯片描述符结构体引用的desc->irq_data.chip +基元。 + +高级驱动程序API +--------------- + +高层驱动API由以下函数组成: + +- request_irq() + +- request_threaded_irq() + +- free_irq() + +- disable_irq() + +- enable_irq() + +- disable_irq_nosync() (SMP only) + +- synchronize_irq() (SMP only) + +- irq_set_irq_type() + +- irq_set_irq_wake() + +- irq_set_handler_data() + +- irq_set_chip() + +- irq_set_chip_data() + +详见自动生成的函数文档。 + +.. note:: + + 由于文档构建流程所限，中文文档中并没有引入自动生成的函数文档，所以请读者直接 + 阅读源码注释。 + +电平触发型IRQ流处理程序 +----------------------- + +通用层提供了一套预定义的irq-flow方法: + +- handle_level_irq() + +- handle_edge_irq() + +- handle_fasteoi_irq() + +- handle_simple_irq() + +- handle_percpu_irq() + +- handle_edge_eoi_irq() + +- handle_bad_irq() + +中断流处理程序（无论是预定义的还是架构特定的）由架构在启动期间或设备初始化期间分配给 +特定中断。 + +默认流实现 +~~~~~~~~~~ + +辅助函数 +^^^^^^^^ + +辅助函数调用芯片基元，并被默认流实现所使用。以下是实现的辅助函数（简化摘录）:: + + default_enable(struct irq_data *data) + { + desc->irq_data.chip->irq_unmask(data); + } + + default_disable(struct irq_data *data) + { + if (!delay_disable(data)) + desc->irq_data.chip->irq_mask(data); + } + + default_ack(struct irq_data *data) + { + chip->irq_ack(data); + } + + default_mask_ack(struct irq_data *data) + { + if (chip->irq_mask_ack) { + chip->irq_mask_ack(data); + } else { + chip->irq_mask(data); + chip->irq_ack(data); + } + } + + noop(struct irq_data *data)) + { + } + + + +默认流处理程序的实现 +~~~~~~~~~~~~~~~~~~~~ + +电平触发型IRQ流处理器 +^^^^^^^^^^^^^^^^^^^^^ + +handle_level_irq为电平触发型的中断提供了一个通用实现。 + +实现的控制流如下（简化摘录）:: + + desc->irq_data.chip->irq_mask_ack(); + handle_irq_event(desc->action); + desc->irq_data.chip->irq_unmask(); + + +默认的需回应IRQ流处理器 +^^^^^^^^^^^^^^^^^^^^^^^ + +handle_fasteoi_irq为中断提供了一个通用的实现，它只需要在处理程序的末端有一个EOI。 + +实现的控制流如下（简化摘录）:: + + handle_irq_event(desc->action); + desc->irq_data.chip->irq_eoi(); + + +默认的边沿触发型IRQ流处理器 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +handle_edge_irq为边沿触发型的中断提供了一个通用的实现。 + +实现的控制流如下（简化摘录）:: + + if (desc->status & running) { + desc->irq_data.chip->irq_mask_ack(); + desc->status |= pending | masked; + return; + } + desc->irq_data.chip->irq_ack(); + desc->status |= running; + do { + if (desc->status & masked) + desc->irq_data.chip->irq_unmask(); + desc->status &= ~pending; + handle_irq_event(desc->action); + } while (status & pending); + desc->status &= ~running; + + +默认的简单型IRQ流处理器 +^^^^^^^^^^^^^^^^^^^^^^^ + +handle_simple_irq提供了一个简单型中断的通用实现。 + +.. note:: + + 简单型的流处理程序不调用任何处理程序/芯片基元。 + +实现的控制流程如下（简化摘录）:: + + handle_irq_event(desc->action); + + +默认的每CPU型流处理程序 +^^^^^^^^^^^^^^^^^^^^^^^ + +handle_percpu_irq为每CPU型中断提供一个通用的实现。 + +每个CPU中断只在SMP上可用，该处理程序提供了一个没有锁的简化版本。 + +以下是控制流的实现（简化摘录）:: + + if (desc->irq_data.chip->irq_ack) + desc->irq_data.chip->irq_ack(); + handle_irq_event(desc->action); + if (desc->irq_data.chip->irq_eoi) + desc->irq_data.chip->irq_eoi(); + + +EOI边沿型IRQ流处理器 +^^^^^^^^^^^^^^^^^^^^ + +handle_edge_eoi_irq提供了一个异常的边沿触发型处理程序，它只用于拯救powerpc/cell +上的一个严重失控的irq控制器。 + +坏的IRQ流处理器 +^^^^^^^^^^^^^^^ + +handle_bad_irq用于处理没有真正分配处理程序的假中断。 + +特殊性和优化 +~~~~~~~~~~~~ + +通用函数是为“干净”的架构和芯片设计的，它们没有平台特定的IRQ处理特殊性。如果一 +个架构需要在“流”的层面上实现特殊性，那么它可以通过覆盖高层的IRQ-流处理程序来实 +现。 + +延迟中断禁用 +~~~~~~~~~~~~ + +每个中断可选择的功能是由Russell King在ARM中断实现中引入的，当调用disable_irq() +时，不会在硬件层面上屏蔽中断。中断保持启用状态，而在中断事件发生时在流处理器中被 +屏蔽。这可以防止在硬件上丢失边沿中断，因为硬件上不存储边沿中断事件，而中断在硬件 +级被禁用。当一个中断在IRQ_DISABLED标志被设置时到达，那么该中断在硬件层面被屏蔽， +IRQ_PENDING位被设置。当中断被enable_irq()重新启用时，将检查挂起位，如果它被设置， +中断将通过硬件或软件重发机制重新发送。(当你想使用延迟中断禁用功能，而你的硬件又不 +能重新触发中断时，有必要启用CONFIG_HARDIRQS_SW_RESEND。) 延迟中断禁止功能是不可 +配置的。 + +芯片级硬件封装 +-------------- + +芯片级硬件描述符结构体 :c:type:`irq_chip` 包含了所有与芯片直接相关的功能，这些功 +能可以被irq流实现所利用。 + +- ``irq_ack`` + +- ``irq_mask_ack`` - 可选的，建议使用的性能 + +- ``irq_mask`` + +- ``irq_unmask`` + +- ``irq_eoi`` - 可选的，EOI流处理程序需要 + +- ``irq_retrigger`` - 可选的 + +- ``irq_set_type`` - 可选的 + +- ``irq_set_wake`` - 可选的 + +这些基元的意思是严格意义上的：ack是指ACK，masking是指对IRQ线的屏蔽，等等。这取决 +于流处理器如何使用这些基本的低级功能单元。 + +__do_IRQ入口点 +============== + +最初的实现__do_IRQ()是所有类型中断的替代入口点。它已经不存在了。 + +这个处理程序被证明不适合所有的中断硬件，因此被重新实现了边沿/级别/简单/超高速中断 +的拆分功能。这不仅是一个功能优化。它也缩短了中断的代码路径。 + +在SMP上的锁 +=========== + +芯片寄存器的锁定是由定义芯片基元的架构决定的。每个寄存器的结构通过desc->lock，由 +通用层保护。 + +通用中断芯片 +============ + +为了避免复制相同的IRQ芯片实现，核心提供了一个可配置的通用中断芯片实现。开发者在自 +己实现相同的功能之前，应该仔细检查通用芯片是否符合他们的需求，并以稍微不同的方式实 +现相同的功能。 + +该API在以下内核代码中: + +kernel/irq/generic-chip.c + +结构体 +====== + +本章包含自动生成的结构体文档，这些结构体在通用IRQ层中使用。 + +该API在以下内核代码中: + +include/linux/irq.h + +include/linux/interrupt.h + +提供的通用函数 +============== + +这一章包含了自动生成的内核API函数的文档，这些函数被导出。 + +该API在以下内核代码中: + +kernel/irq/manage.c + +kernel/irq/chip.c + +提供的内部函数 +============== + +本章包含自动生成的内部函数的文档。 + +该API在以下内核代码中: + +kernel/irq/irqdesc.c + +kernel/irq/handle.c + +kernel/irq/chip.c + +鸣谢 +==== + +感谢以下人士对本文档作出的贡献： + +1. Thomas Gleixner tglx@linutronix.de + +2. Ingo Molnar mingo@elte.hu diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst index b4bde9396339..d5e947d8b6f1 100644 --- a/Documentation/translations/zh_CN/core-api/index.rst +++ b/Documentation/translations/zh_CN/core-api/index.rst @@ -80,14 +80,17 @@ Todolist: :maxdepth: 1 cachetlb + cpu_hotplug + genericirq + memory-hotplug + protection-keys Todolist: - cpu_hotplug memory-hotplug + cpu_hotplug genericirq - protection-keys 内存管理 diff --git a/Documentation/translations/zh_CN/core-api/memory-hotplug.rst b/Documentation/translations/zh_CN/core-api/memory-hotplug.rst new file mode 100644 index 000000000000..161f4d2c18cc --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/memory-hotplug.rst @@ -0,0 +1,126 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/memory_hotplug.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. _cn_core-api_memory-hotplug: + +========== +内存热插拔 +========== + +内存热拔插事件通知器 +==================== + +热插拔事件被发送到一个通知队列中。 + +在 ``include/linux/memory.h`` 中定义了六种类型的通知： + +MEM_GOING_ONLINE + 在新内存可用之前生成，以便能够为子系统处理内存做准备。页面分配器仍然无法从新 + 的内存中进行分配。 + +MEM_CANCEL_ONLINE + 如果MEM_GOING_ONLINE失败，则生成。 + +MEM_ONLINE + 当内存成功上线时产生。回调可以从新的内存中分配页面。 + +MEM_GOING_OFFLINE + 在开始对内存进行下线处理时生成。从内存中的分配不再可能，但是一些要下线的内存 + 仍然在使用。回调可以用来释放一个子系统在指定内存块中已知的内存。 + +MEM_CANCEL_OFFLINE + 如果MEM_GOING_OFFLINE失败，则生成。来自我们试图离线的内存块中的内存又可以使 + 用了。 + +MEM_OFFLINE + 在内存下线完成后生成。 + +可以通过调用如下函数来注册一个回调程序: + + hotplug_memory_notifier(callback_func, priority) + +优先级数值较高的回调函数在数值较低的回调函数之前被调用。 + +一个回调函数必须有以下原型:: + + int callback_func( + struct notifier_block *self, unsigned long action, void *arg); + +回调函数的第一个参数（self）是指向回调函数本身的通知器链块的一个指针。第二个参 +数（action）是上述的事件类型之一。第三个参数（arg）传递一个指向 +memory_notify结构体的指针:: + + struct memory_notify { + unsigned long start_pfn; + unsigned long nr_pages; + int status_change_nid_normal; + int status_change_nid_high; + int status_change_nid; + } + +- start_pfn是在线/离线内存的start_pfn。 + +- nr_pages是在线/离线内存的页数。 + +- status_change_nid_normal是当nodemask的N_NORMAL_MEMORY被设置/清除时设置节 + 点id，如果是-1，则nodemask状态不改变。 + +- status_change_nid_high是当nodemask的N_HIGH_MEMORY被设置/清除时设置的节点 + id，如果这个值为-1，那么nodemask状态不会改变。 + +- status_change_nid是当nodemask的N_MEMORY被（将）设置/清除时设置的节点id。这 + 意味着一个新的（没上线的）节点通过联机获得新的内存，而一个节点失去了所有的内 + 存。如果这个值为-1，那么nodemask的状态就不会改变。 + + 如果 status_changed_nid* >= 0，回调应该在必要时为节点创建/丢弃结构体。 + +回调程序应返回 ``include/linux/notifier.h`` 中定义的NOTIFY_DONE, NOTIFY_OK, +NOTIFY_BAD, NOTIFY_STOP中的一个值。 + +NOTIFY_DONE和NOTIFY_OK对进一步处理没有影响。 + +NOTIFY_BAD是作为对MEM_GOING_ONLINE、MEM_GOING_OFFLINE、MEM_ONLINE或MEM_OFFLINE +动作的回应，用于取消热插拔。它停止对通知队列的进一步处理。 + +NOTIFY_STOP停止对通知队列的进一步处理。 + +内部锁 +====== + +当添加/删除使用内存块设备（即普通RAM）的内存时，device_hotplug_lock应该被保持 +为: + +- 针对在线/离线请求进行同步（例如，通过sysfs）。这样一来，内存块设备只有在内存 + 被完全添加后才能被用户空间访问（.online/.state属性）。而在删除内存时，我们知 + 道没有人在临界区。 + +- 与CPU热拔插或类似操作同步（例如ACPI和PPC相关操作） + +特别是，在添加内存和用户空间试图以比预期更快的速度上线该内存时，有可能出现锁反转， +使用device_hotplug_lock可以避免此情况: + +- device_online()将首先接受device_lock()，然后是mem_hotplug_lock。 + +- add_memory_resource()将首先使用mem_hotplug_lock，然后是device_lock()（在创 + 建设备时，在bus_add_device()期间）。 + +由于在使用device_lock()之前，设备对用户空间是可见的，这可能导致锁的反转。 + +内存的上线/下线应该通过device_online()/device_offline()完成————确保它与通过 +sysfs进行的操作正确同步。建议持有device_hotplug_lock（例如，保护online_type）。 + +当添加/删除/上线/下线内存或者添加/删除异构或设备内存时，我们应该始终持有写模式的 +mem_hotplug_lock，以序列化内存热插拔（例如访问全局/区域变量）。 + +此外，mem_hotplug_lock（与device_hotplug_lock相反）在读取模式下允许一个相当 +有效的get_online_mems/put_online_mems实现，所以访问内存的代码可以防止该内存 +消失。 diff --git a/Documentation/translations/zh_CN/core-api/protection-keys.rst b/Documentation/translations/zh_CN/core-api/protection-keys.rst new file mode 100644 index 000000000000..d07830050153 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/protection-keys.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/protection-keys.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. _cn_core-api_protection-keys: + +============ +内存保护密钥 +============ + +用户空间的内存保护密钥（Memory Protection Keys for Userspace，PKU，亦 +即PKEYs）是英特尔Skylake（及以后）“可扩展处理器”服务器CPU上的一项功能。 +它将在未来的非服务器英特尔处理器和未来的AMD处理器中可用。 + +对于任何希望测试或使用该功能的人来说，它在亚马逊的EC2 C5实例中是可用的， +并且已知可以在那里使用Ubuntu 17.04镜像运行。 + +内存保护密钥提供了一种机制来执行基于页面的保护，但在应用程序改变保护域 +时不需要修改页表。它的工作原理是在每个页表项中为“保护密钥”分配4个以 +前被忽略的位，从而提供16个可能的密钥。 + +还有一个新的用户可访问寄存器（PKRU），为每个密钥提供两个单独的位（访 +问禁止和写入禁止）。作为一个CPU寄存器，PKRU在本质上是线程本地的，可能 +会给每个线程提供一套不同于其他线程的保护措施。 + +有两条新指令（RDPKRU/WRPKRU）用于读取和写入新的寄存器。该功能仅在64位 +模式下可用，尽管物理地址扩展页表中理论上有空间。这些权限只在数据访问上 +强制执行，对指令获取没有影响。 + + +系统调用 +======== + +有3个系统调用可以直接与pkeys进行交互:: + + int pkey_alloc(unsigned long flags, unsigned long init_access_rights) + int pkey_free(int pkey); + int pkey_mprotect(unsigned long start, size_t len, + unsigned long prot, int pkey); + +在使用一个pkey之前，必须先用pkey_alloc()分配它。一个应用程序直接调用 +WRPKRU指令，以改变一个密钥覆盖的内存的访问权限。在这个例子中，WRPKRU +被一个叫做pkey_set()的C函数所封装:: + + int real_prot = PROT_READ|PROT_WRITE; + pkey = pkey_alloc(0, PKEY_DISABLE_WRITE); + ptr = mmap(NULL, PAGE_SIZE, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0); + ret = pkey_mprotect(ptr, PAGE_SIZE, real_prot, pkey); + ... application runs here + +现在，如果应用程序需要更新'ptr'处的数据，它可以获得访问权，进行更新， +然后取消其写访问权:: + + pkey_set(pkey, 0); // clear PKEY_DISABLE_WRITE + *ptr = foo; // assign something + pkey_set(pkey, PKEY_DISABLE_WRITE); // set PKEY_DISABLE_WRITE again + +现在，当它释放内存时，它也将释放pkey，因为它不再被使用了:: + + munmap(ptr, PAGE_SIZE); + pkey_free(pkey); + +.. note:: pkey_set()是RDPKRU和WRPKRU指令的一个封装器。在tools/testing/selftests/x86/protection_keys.c中可以找到一个实现实例。 + tools/testing/selftests/x86/protection_keys.c. + +行为 +==== + +内核试图使保护密钥与普通的mprotect()的行为一致。例如，如果你这样做:: + + mprotect(ptr, size, PROT_NONE); + something(ptr); + +这样做的时候，你可以期待保护密钥的相同效果:: + + pkey = pkey_alloc(0, PKEY_DISABLE_WRITE | PKEY_DISABLE_READ); + pkey_mprotect(ptr, size, PROT_READ|PROT_WRITE, pkey); + something(ptr); + +无论something()是否是对'ptr'的直接访问，这都应该为真。 +如:: + + *ptr = foo; + +或者当内核代表应用程序进行访问时，比如read():: + + read(fd, ptr, 1); + +在这两种情况下，内核都会发送一个SIGSEGV，但当违反保护密钥时，si_code +将被设置为SEGV_PKERR，而当违反普通的mprotect()权限时，则是SEGV_ACCERR。 diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst index e6c99f2f543f..0f770b8664e9 100644 --- a/Documentation/translations/zh_CN/dev-tools/index.rst +++ b/Documentation/translations/zh_CN/dev-tools/index.rst @@ -11,6 +11,9 @@ 目前这些文档已经整理在一起，不需要再花费额外的精力。 欢迎任何补丁。 +有关测试专用工具的简要概述，参见 +Documentation/translations/zh_CN/dev-tools/testing-overview.rst + .. class:: toc-title 目录 @@ -18,6 +21,7 @@ .. toctree:: :maxdepth: 2 + testing-overview gcov kasan @@ -29,6 +33,7 @@ Todolist: - ubsan - kmemleak - kcsan + - kfence - gdb-kernel-debugging - kgdb - kselftest diff --git a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst new file mode 100644 index 000000000000..b7a1d13da6c6 --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/testing-overview.rst +:Translator: 胡皓文 Hu Haowen <src.res@email.cn> + +============ +内核测试指南 +============ + +有许多不同的工具可以用于测试Linux内核，因此了解什么时候使用它们可能 +很困难。本文档粗略概述了它们之间的区别，并阐释了它们是怎样糅合在一起 +的。 + +编写和运行测试 +============== + +大多数内核测试都是用kselftest或KUnit框架之一编写的。它们都让运行测试 +更加简化，并为编写新测试提供帮助。 + +如果你想验证内核的行为——尤其是内核的特定部分——那你就要使用kUnit或 +kselftest。 + +KUnit和kselftest的区别 +---------------------- + +.. note:: + 由于本文段中部分术语尚无较好的对应中文释义，可能导致与原文含义 + 存在些许差异，因此建议读者结合原文 + （Documentation/dev-tools/testing-overview.rst）辅助阅读。 + 如对部分翻译有异议或有更好的翻译意见，欢迎联系译者进行修订。 + +KUnit（Documentation/dev-tools/kunit/index.rst）是用于“白箱”测 +试的一个完整的内核内部系统：因为测试代码是内核的一部分，所以它能够访 +问用户空间不能访问到的内部结构和功能。 + +因此，KUnit测试最好针对内核中较小的、自包含的部分，以便能够独立地测 +试。“单元”测试的概念亦是如此。 + +比如，一个KUnit测试可能测试一个单独的内核功能（甚至通过一个函数测试 +一个单一的代码路径，例如一个错误处理案例），而不是整个地测试一个特性。 + +这也使得KUnit测试构建和运行非常地快，从而能够作为开发流程的一部分被 +频繁地运行。 + +有关更详细的介绍，请参阅KUnit测试代码风格指南 +Documentation/dev-tools/kunit/style.rst + +kselftest（Documentation/dev-tools/kselftest.rst），相对来说，大量用 +于用户空间，并且通常测试用户空间的脚本或程序。 + +这使得编写复杂的测试，或者需要操作更多全局系统状态的测试更加容易（诸 +如生成进程之类）。然而，从kselftest直接调用内核函数是不行的。这也就 +意味着只有通过某种方式（如系统调用、驱动设备、文件系统等）导出到了用 +户空间的内核功能才能使用kselftest来测试。为此，有些测试包含了一个伴 +生的内核模块用于导出更多的信息和功能。不过，对于基本上或者完全在内核 +中运行的测试，KUnit可能是更佳工具。 + +kselftest也因此非常适合于全部功能的测试，因为这些功能会将接口暴露到 +用户空间，从而能够被测试，而不是展现实现细节。“system”测试和 +“end-to-end”测试亦是如此。 + +比如，一个新的系统调用应该伴随有新的kselftest测试。 + +代码覆盖率工具 +============== + +支持两种不同代码之间的覆盖率测量工具。它们可以用来验证一项测试执行的 +确切函数或代码行。这有助于决定内核被测试了多少，或用来查找合适的测试 +中没有覆盖到的极端情况。 + +Documentation/translations/zh_CN/dev-tools/gcov.rst 是GCC的覆盖率测试 +工具，能用于获取内核的全局或每个模块的覆盖率。与KCOV不同的是，这个工具 +不记录每个任务的覆盖率。覆盖率数据可以通过debugfs读取，并通过常规的 +gcov工具进行解释。 + +Documentation/dev-tools/kcov.rst 是能够构建在内核之中，用于在每个任务 +的层面捕捉覆盖率的一个功能。因此，它对于模糊测试和关于代码执行期间信 +息的其它情况非常有用，比如在一个单一系统调用里使用它就很有用。 + +动态分析工具 +============ + +内核也支持许多动态分析工具，用以检测正在运行的内核中出现的多种类型的 +问题。这些工具通常每个去寻找一类不同的缺陷，比如非法内存访问，数据竞 +争等并发问题，或整型溢出等其他未定义行为。 + +如下所示： + +* kmemleak检测可能的内存泄漏。参阅 + Documentation/dev-tools/kmemleak.rst +* KASAN检测非法内存访问，如数组越界和释放后重用（UAF）。参阅 + Documentation/dev-tools/kasan.rst +* UBSAN检测C标准中未定义的行为，如整型溢出。参阅 + Documentation/dev-tools/ubsan.rst +* KCSAN检测数据竞争。参阅 Documentation/dev-tools/kcsan.rst +* KFENCE是一个低开销的内存问题检测器，比KASAN更快且能被用于批量构建。 + 参阅 Documentation/dev-tools/kfence.rst +* lockdep是一个锁定正确性检测器。参阅 + Documentation/locking/lockdep-design.rst +* 除此以外，在内核中还有一些其它的调试工具，大多数能在 + lib/Kconfig.debug 中找到。 + +这些工具倾向于对内核进行整体测试，并且不像kselftest和KUnit一样“传递”。 +它们可以通过在启用这些工具时运行内核测试以与kselftest或KUnit结合起来： +之后你就能确保这些错误在测试过程中都不会发生了。 + +一些工具与KUnit和kselftest集成，并且在检测到问题时会自动打断测试。 diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index 1f953d3439a5..a34e58733ac8 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -5,6 +5,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon + \kerneldocBeginSC .. _linux_doc_zh: @@ -17,6 +18,11 @@ **翻译计划:** 内核中文文档欢迎任何翻译投稿，特别是关于内核用户和管理员指南部分。 +这是中文内核文档树的顶级目录。内核文档，就像内核本身一样，在很大程度上是一 +项正在进行的工作；当我们努力将许多分散的文件整合成一个连贯的整体时尤其如此。 +另外，随时欢迎您对内核文档进行改进；如果您想提供帮助，请加入vger.kernel.org +上的linux-doc邮件列表。 + 许可证文档 ---------- @@ -97,12 +103,14 @@ TODOList: iio/index sound/index filesystems/index + virt/index + infiniband/index + accounting/index TODOList: * driver-api/index * locking/index -* accounting/index * block/index * cdrom/index * ide/index @@ -111,7 +119,6 @@ TODOList: * hid/index * i2c/index * isdn/index -* infiniband/index * leds/index * netlabel/index * networking/index @@ -122,7 +129,6 @@ TODOList: * spi/index * w1/index * watchdog/index -* virt/index * input/index * hwmon/index * gpu/index @@ -184,3 +190,7 @@ TODOList: ---------- * :ref:`genindex` + +.. raw:: latex + + \kerneldocEndSC diff --git a/Documentation/translations/zh_CN/infiniband/core_locking.rst b/Documentation/translations/zh_CN/infiniband/core_locking.rst new file mode 100644 index 000000000000..42f08038d44b --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/core_locking.rst @@ -0,0 +1,115 @@ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/core_locking.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_core_locking: + +================== +infiniband中间层锁 +================== + + 本指南试图明确infiniband中间层的锁假设。它描述了对位于中间层以下的低 + 级驱动程序和使用中间层的上层协议的要求。 + +睡眠和中断环境 +============== + + 除了以下异常情况，ib_device结构体中所有方法的低级驱动实现都可以睡眠。 + 这些异常情况是列表中的任意的方法: + + - create_ah + - modify_ah + - query_ah + - destroy_ah + - post_send + - post_recv + - poll_cq + - req_notify_cq + + 他们可能不可以睡眠，而且必须可以从任何上下文中调用。 + + 向上层协议使用者输出的相应函数: + + - rdma_create_ah + - rdma_modify_ah + - rdma_query_ah + - rdma_destroy_ah + - ib_post_send + - ib_post_recv + - ib_req_notify_cq + + 因此，在任何情况下都可以安全调用（它们）。 + + 此外，该函数 + + - ib_dispatch_event + + 被底层驱动用来通过中间层调度异步事件的“A”，也可以从任何上下文中安全调 + 用。 + +可重入性 +-------- + + 由低级驱动程序导出的ib_device结构体中的所有方法必须是完全可重入的。 + 即使使用同一对象的多个函数调用被同时运行，低级驱动程序也需要执行所有 + 必要的同步以保持一致性。 + + IB中间层不执行任何函数调用的序列化。 + + 因为低级驱动程序是可重入的，所以不要求上层协议使用者任何顺序执行。然 + 而，为了得到合理的结果，可能需要一些顺序。例如，一个使用者可以在多个 + CPU上同时安全地调用ib_poll_cq()。然而，不同的ib_poll_cq()调用之间 + 的工作完成信息的顺序没有被定义。 + +回调 +---- + + 低级驱动程序不得直接从与ib_device方法调用相同的调用链中执行回调。例 + 如，低级驱动程序不允许从post_send方法直接调用使用者的完成事件处理程 + 序。相反，低级驱动程序应该推迟这个回调，例如，调度一个tasklet来执行 + 这个回调。 + + 低层驱动负责确保同一CQ的多个完成事件处理程序不被同时调用。驱动程序必 + 须保证一个给定的CQ的事件处理程序在同一时间只有一个在运行。换句话说， + 以下情况是不允许的:: + + CPU1 CPU2 + + low-level driver -> + consumer CQ event callback: + /* ... */ + ib_req_notify_cq(cq, ...); + low-level driver -> + /* ... */ consumer CQ event callback: + /* ... */ + return from CQ event handler + + 完成事件和异步事件回调的运行环境没有被定义。 根据低级别的驱动程序，它可能是 + 进程上下文、softirq上下文或中断上下文。上层协议使用者可能不会在回调中睡眠。 + +热插拔 +------ + + 当一个低级驱动程序调用ib_register_device()时，它宣布一个设备已经 + 准备好供使用者使用，所有的初始化必须在这个调用之前完成。设备必须保 + 持可用，直到驱动对ib_unregister_device()的调用返回。 + + 低级驱动程序必须从进程上下文调用ib_register_device()和 + ib_unregister_device()。如果使用者在这些调用中回调到驱动程序，它 + 不能持有任何可能导致死锁的semaphores。 + + 一旦其结构体ib_client的add方法被调用，上层协议使用者就可以开始使用 + 一个IB设备。使用者必须在从移除方法返回之前完成所有的清理工作并释放 + 与设备相关的所有资源。 + + 使用者被允许在其添加和删除方法中睡眠。 diff --git a/Documentation/translations/zh_CN/infiniband/index.rst b/Documentation/translations/zh_CN/infiniband/index.rst new file mode 100644 index 000000000000..5634cc48379f --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/index.rst @@ -0,0 +1,40 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_index: + +========== +infiniband +========== + +.. toctree:: + :maxdepth: 1 + + core_locking + ipoib + opa_vnic + sysfs + tag_matching + user_mad + user_verbs + + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/infiniband/ipoib.rst b/Documentation/translations/zh_CN/infiniband/ipoib.rst new file mode 100644 index 000000000000..56517ea5fe9d --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/ipoib.rst @@ -0,0 +1,111 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/ipoib.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_ipoib: + +========================= +infiniband上的IP（IPoIB） +========================= + + ib_ipoib驱动是IETF ipoib工作组发布的RFC 4391和4392所规定的 + infiniband上IP协议的一个实现。它是一个“本地”实现，即把接口类型设置为 + ARPHRD_INFINIBAND，硬件地址长度为20（早期的专有实现向内核伪装为以太网 + 接口）。 + +分区和P_Keys +============ + + 当IPoIB驱动被加载时，它会使用索引为0的P_Key给每个端口创建一个接口。要用 + 不同的P_Key创建一个接口，将所需的P_Key写入主接口的 + /sys/class/net/<intf name>/create_child文件里面。比如说:: + + echo 0x8001 > /sys/class/net/ib0/create_child + + 这将用P_Key 0x8001创建一个名为ib0.8001的接口。要删除一个子接口，使用 + ``delete_child`` 文件:: + + echo 0x8001 > /sys/class/net/ib0/delete_child + + 任何接口的P_Key都由“pkey”文件给出，而子接口的主接口在“parent”中。 + + 子接口的创建/删除也可以使用IPoIB的rtnl_link_ops来完成，使用两种 + 方式创建的子接口的行为是一样的。 + +数据报与连接模式 +================ + + IPoIB驱动支持两种操作模式：数据报和连接。模式是通过接口的 + /sys/class/net/<intf name>/mode文件设置和读取的。 + + 在数据报模式下，使用IB UD（不可靠数据报）传输，因此接口MTU等于IB L2 MTU + 减去IPoIB封装头（4字节）。例如，在一个典型的具有2K MTU的IB结构中，IPoIB + MTU将是2048 - 4 = 2044字节。 + + 在连接模式下，使用IB RC（可靠的连接）传输。连接模式利用IB传输的连接特性， + 允许MTU达到最大的IP包大小64K，这减少了处理大型UDP数据包、TCP段等所需的 + IP包数量，提高了大型信息的性能。 + + 在连接模式下，接口的UD QP仍被用于组播和与不支持连接模式的对等体的通信。 + 在这种情况下，ICMP PMTU数据包的RX仿真被用来使网络堆栈对这些邻居使用较 + 小的UD MTU。 + +无状态卸载 +========== + + 如果IB HW支持IPoIB无状态卸载，IPoIB会向网络堆栈广播TCP/IP校验和/或大量 + 传送（LSO）负载转移能力。 + + 大量传送（LSO）负载转移也已实现，可以使用ethtool调用打开/关闭。目前，LRO + 只支持具有校验和卸载能力的设备。 + + 无状态卸载只在数据报模式下支持。 + +中断管理 +======== + + 如果底层IB设备支持CQ事件管理，可以使用ethtool来设置中断缓解参数，从而减少 + 处理中断产生的开销。IPoIB的主要代码路径不使用TX完成信号的事件，所以只支持 + RX管理。 + +调试信息 +======== + + 通过将CONFIG_INFINIBAND_IPOIB_DEBUG设置为“y”来编译IPoIB驱动，跟踪信 + 息被编译到驱动中。通过将模块参数debug_level和mcast_debug_level设置为1来 + 打开它们。这些参数可以在运行时通过/sys/module/ib_ipoib/的文件来控制。 + + CONFIG_INFINIBAND_IPOIB_DEBUG也启用debugfs虚拟文件系统中的文件。通过挂 + 载这个文件系统，例如用:: + + mount -t debugfs none /sys/kernel/debug + + 可以从/sys/kernel/debug/ipoib/ib0_mcg等文件中获得关于多播组的统计数据。 + + 这个选项对性能的影响可以忽略不计，所以在正常运行时，在debug_level设置为 + 0的情况下启用这个选项是安全的。 + + CONFIG_INFINIBAND_IPOIB_DEBUG_DATA当data_debug_level设置为1时，可以 + 在数据路径中启用更多的调试输出。 然而，即使禁用输出，启用这个配置选项也 + 会影响性能，因为它在快速路径中增加了测试。 + +引用 +==== + + 在InfiniBand上传输IP（IPoIB）（RFC 4391）。 + http://ietf.org/rfc/rfc4391.txt + + infiniband上的IP:上的IP架构（RFC 4392）。 + http://ietf.org/rfc/rfc4392.txt + + infiniband上的IP: 连接模式 (RFC 4755) + http://ietf.org/rfc/rfc4755.txt diff --git a/Documentation/translations/zh_CN/infiniband/opa_vnic.rst b/Documentation/translations/zh_CN/infiniband/opa_vnic.rst new file mode 100644 index 000000000000..12b147fbf792 --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/opa_vnic.rst @@ -0,0 +1,156 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/opa_vnic.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_opa_vnic: + +============================================= +英特尔全路径（OPA）虚拟网络接口控制器（VNIC） +============================================= + +英特尔全路径（OPA）虚拟网络接口控制器（VNIC）功能通过封装HFI节点之间的以 +太网数据包，支持Omni-Path结构上的以太网功能。 + +体系结构 +======== + +Omni-Path封装的以太网数据包的交换模式涉及Omni-Path结构拓扑上覆盖的一个或 +多个虚拟以太网交换机。Omni-Path结构上的HFI节点的一个子集被允许在特定的虚 +拟以太网交换机上交换封装的以太网数据包。虚拟以太网交换机是通过配置结构上的 +HFI节点实现的逻辑抽象，用于生成和处理报头。在最简单的配置中，整个结构的所有 +HFI节点通过一个虚拟以太网交换机交换封装的以太网数据包。一个虚拟以太网交换机， +实际上是一个独立的以太网网络。该配置由以太网管理器（EM）执行，它是可信的结 +构管理器（FM）应用程序的一部分。HFI节点可以有多个VNIC，每个连接到不同的虚 +拟以太网交换机。下图介绍了两个虚拟以太网交换机与两个HFI节点的情况:: + + +-------------------+ + | 子网/ | + | 以太网 | + | 管理 | + +-------------------+ + / / + / / + / / + / / + +-----------------------------+ +------------------------------+ + | 虚拟以太网切换 | | 虚拟以太网切换 | + | +---------+ +---------+ | | +---------+ +---------+ | + | | VPORT | | VPORT | | | | VPORT | | VPORT | | + +--+---------+----+---------+-+ +-+---------+----+---------+---+ + | \ / | + | \ / | + | \/ | + | / \ | + | / \ | + +-----------+------------+ +-----------+------------+ + | VNIC | VNIC | | VNIC | VNIC | + +-----------+------------+ +-----------+------------+ + | HFI | | HFI | + +------------------------+ +------------------------+ + + +Omni-Path封装的以太网数据包格式如下所述。 + +==================== ================================ +位 域 +==================== ================================ +Quad Word 0: +0-19 SLID (低20位) +20-30 长度 (以四字为单位) +31 BECN 位 +32-51 DLID (低20位) +52-56 SC (服务级别) +57-59 RC (路由控制) +60 FECN 位 +61-62 L2 (=10, 16B 格式) +63 LT (=1, 链路传输头 Flit) + +Quad Word 1: +0-7 L4 type (=0x78 ETHERNET) +8-11 SLID[23:20] +12-15 DLID[23:20] +16-31 PKEY +32-47 熵 +48-63 保留 + +Quad Word 2: +0-15 保留 +16-31 L4 头 +32-63 以太网数据包 + +Quad Words 3 to N-1: +0-63 以太网数据包 (pad拓展) + +Quad Word N (last): +0-23 以太网数据包 (pad拓展) +24-55 ICRC +56-61 尾 +62-63 LT (=01, 链路传输尾 Flit) +==================== ================================ + +以太网数据包在传输端被填充，以确保VNIC OPA数据包是四字对齐的。“尾”字段 +包含填充的字节数。在接收端，“尾”字段被读取，在将数据包向上传递到网络堆 +栈之前，填充物被移除（与ICRC、尾和OPA头一起）。 + +L4头字段包含VNIC端口所属的虚拟以太网交换机ID。在接收端，该字段用于将收 +到的VNIC数据包去多路复用到不同的VNIC端口。 + +驱动设计 +======== + +英特尔OPA VNIC的软件设计如下图所示。OPA VNIC功能有一个依赖于硬件的部分 +和一个独立于硬件的部分。 + +对IB设备分配和释放RDMA netdev设备的支持已经被加入。RDMA netdev支持与 +网络堆栈的对接，从而创建标准的网络接口。OPA_VNIC是一个RDMA netdev设备 +类型。 + +依赖于HW的VNIC功能是HFI1驱动的一部分。它实现了分配和释放OPA_VNIC RDMA +netdev的动作。它涉及VNIC功能的HW资源分配/管理。它与网络堆栈接口并实现所 +需的net_device_ops功能。它在传输路径中期待Omni-Path封装的以太网数据包， +并提供对它们的HW访问。在将数据包向上传递到网络堆栈之前，它把Omni-Path头 +从接收的数据包中剥离。它还实现了RDMA netdev控制操作。 + +OPA VNIC模块实现了独立于硬件的VNIC功能。它由两部分组成。VNIC以太网管理 +代理（VEMA）作为一个IB客户端向IB核心注册，并与IB MAD栈接口。它与以太网 +管理器（EM）和VNIC netdev交换管理信息。VNIC netdev部分分配和释放OPA_VNIC +RDMA netdev设备。它在需要时覆盖由依赖HW的VNIC驱动设置的net_device_ops函数， +以适应任何控制操作。它还处理以太网数据包的封装，在传输路径中使用Omni-Path头。 +对于每个VNIC接口，封装所需的信息是由EM通过VEMA MAD接口配置的。它还通过调用 +RDMA netdev控制操作将任何控制信息传递给依赖于HW的驱动程序:: + + +-------------------+ +----------------------+ + | | | Linux | + | IB MAD | | 网络 | + | | | 栈 | + +-------------------+ +----------------------+ + | | | + | | | + +----------------------------+ | + | | | + | OPA VNIC 模块 | | + | (OPA VNIC RDMA Netdev | | + | & EMA 函数) | | + | | | + +----------------------------+ | + | | + | | + +------------------+ | + | IB 核心 | | + +------------------+ | + | | + | | + +--------------------------------------------+ + | | + | HFI1 驱动和 VNIC 支持 | + | | + +--------------------------------------------+ diff --git a/Documentation/translations/zh_CN/infiniband/sysfs.rst b/Documentation/translations/zh_CN/infiniband/sysfs.rst new file mode 100644 index 000000000000..e9a48b0b2ba6 --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/sysfs.rst @@ -0,0 +1,21 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/sysfs.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_sysfs: + +========= +Sysfs文件 +========= + +sysfs接口已移至 +Documentation/ABI/stable/sysfs-class-infiniband. diff --git a/Documentation/translations/zh_CN/infiniband/tag_matching.rst b/Documentation/translations/zh_CN/infiniband/tag_matching.rst new file mode 100644 index 000000000000..19b99587b862 --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/tag_matching.rst @@ -0,0 +1,63 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/tag_matching.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_tag_matching: + +============ +标签匹配逻辑 +============ + +MPI标准定义了一套规则，称为标签匹配，用于将源发送操作与目的接收匹配。以下参数必 +须与以下源和目的参数相匹配: + +* 沟通者 +* 用户标签--通配符(wild card)可由接收方指定 +* 来源等级--通配符可由接收方指定 +* 目的地等级 – wild + +排序规则要求，当一对以上的发送和接收消息信封可能匹配时，包括最早发布-发送和最早 +发布-接收的一对是必须用来满足匹配操作的一对。然而，这并不意味着标签是按照它们被 +创建的顺序消耗的，例如，如果早期的标签不能用来满足匹配规则，那么后来生成的标签 +可能被消耗。 + +当消息从发送方发送到接收方时，通信库可能试图在相应的匹配接收被发布之后或之前处 +理该操作。如果匹配的接收被发布，这就是一个预期的消息，否则就被称为一个意外的消 +息。实现时经常为这两种不同的匹配实例使用不同的匹配方案。 + +为了减少MPI库的内存占用，MPI实现通常使用两种不同的协议来实现这一目的: + +1. Eager协议--当发送方处理完发送时，完整的信息就会被发送。在send_cq中会收到 +一个完成发送的通知，通知缓冲区可以被重新使用。 + +2. Rendezvous协议--发送方在第一次通知接收方时发送标签匹配头，也许还有一部分 +数据。当相应的缓冲区被发布时，响应者将使用头中的信息，直接向匹配的缓冲区发起 +RDMA读取操作。为了使缓冲区得到重用，需要收到一个fin消息。 + +标签匹配的实现 +============== + +使用的匹配对象有两种类型，即发布的接收列表和意外消息列表。应用程序通过调用发布 +的接收列表中的MPI接收例程发布接收缓冲区，并使用MPI发送例程发布发送消息。发布的 +接收列表的头部可以由硬件来维护，而软件则要对这个列表进行跟踪。 + +当发送开始并到达接收端时，如果没有为这个到达的消息预先发布接收，它将被传递给软 +件并被放在意外（unexpect）消息列表中。否则，将对该匹配进行处理，包括交会处理， +如果合适的话，将数据传送到指定的接收缓冲区。这允许接收方MPI标签匹配与计算重叠。 + +当一个接收信息被发布时，通信库将首先检查软件的意外信息列表，以寻找一个匹配的接 +收信息。如果找到一个匹配的，数据就会被送到用户缓冲区，使用一个软件控制的协议。 +UCX的实现根据数据大小，使用急切或交会协议。如果没有找到匹配，整个预置的接收列 +表由硬件维护，并且有空间在这个列表中增加一个预置的接收，这个接收被传递给硬件。 +软件要对这个列表进行跟踪，以帮助处理MPI取消操作。此外，由于硬件和软件在标签匹 +配操作方面预计不会紧密同步，这个影子列表被用来检测预先发布的接收被传递到硬件的 +情况，因为匹配的意外消息正在从硬件传递到软件。 diff --git a/Documentation/translations/zh_CN/infiniband/user_mad.rst b/Documentation/translations/zh_CN/infiniband/user_mad.rst new file mode 100644 index 000000000000..d9ab2edfb559 --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/user_mad.rst @@ -0,0 +1,164 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/user_mad.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_user_mad: + +=============== +用户空间MAD访问 +=============== + +设备文件 +======== + + 每个InfiniBand设备的每个端口都有一个“umad”设备和一个“issm”设备连接。 + 例如，一个双端口的HCA将有两个umad设备和两个issm设备，而一个交换机将 + 有每个类型的一个设备（对于交换机端口0）。 + +创建MAD代理 +=========== + + 一个MAD代理可以通过填写一个结构体ib_user_mad_reg_req来创建，然后在 + 适当的设备文件的文件描述符上调用IB_USER_MAD_REGISTER_AGENT ioctl。 + 如果注册请求成功，结构体中会返回一个32位的ID。比如说:: + + struct ib_user_mad_reg_req req = { /* ... */ }; + ret = ioctl(fd, IB_USER_MAD_REGISTER_AGENT, (char *) &req); + if (!ret) + my_agent = req.id; + else + perror("agent register"); + + 代理可以通过IB_USER_MAD_UNREGISTER_AGENT ioctl取消注册。另外，所有 + 通过文件描述符注册的代理在描述符关闭时将被取消注册。 + + 2014 + 现在提供了一个新的注册IOctl，允许在注册时提供额外的字段。这个注册 + 调用的用户隐含了对pkey_index的使用（见下文）。现在提供了一个新的 + 注册IOctl，允许在注册时提供额外的字段。这个注册调用的用户隐含了对 + pkey_index的使用（见下文）。 + +接收MADs +======== + + 使用read()接收MAD。现在接收端支持RMPP。传给read()的缓冲区必须至少是 + 一个struct ib_user_mad + 256字节。比如说: + + 如果传递的缓冲区不足以容纳收到的MAD（RMPP），errno被设置为ENOSPC，需 + 要的缓冲区长度被设置在mad.length中。 + + 正常MAD(非RMPP)的读取示例:: + + struct ib_user_mad *mad; + mad = malloc(sizeof *mad + 256); + ret = read(fd, mad, sizeof *mad + 256); + if (ret != sizeof mad + 256) { + perror("read"); + free(mad); + } + + RMPP读取示例:: + + struct ib_user_mad *mad; + mad = malloc(sizeof *mad + 256); + ret = read(fd, mad, sizeof *mad + 256); + if (ret == -ENOSPC)) { + length = mad.length; + free(mad); + mad = malloc(sizeof *mad + length); + ret = read(fd, mad, sizeof *mad + length); + } + if (ret < 0) { + perror("read"); + free(mad); + } + + 除了实际的MAD内容外，其他结构体ib_user_mad字段将被填入收到的MAD的信 + 息。例如，远程LID将在mad.lid中。 + + 如果发送超时，将产生一个接收，mad.status设置为ETIMEDOUT。否则，当一个 + MAD被成功接收后，mad.status将是0。 + + poll()/select()可以用来等待一个MAD可以被读取。 + + poll()/select()可以用来等待，直到可以读取一个MAD。 + +发送MADs +======== + + MADs是用write()发送的。发送的代理ID应该填入MAD的id字段，目的地LID应该 + 填入lid字段，以此类推。发送端确实支持RMPP，所以可以发送任意长度的MAD。 + 比如说:: + + struct ib_user_mad *mad; + + mad = malloc(sizeof *mad + mad_length); + + /* fill in mad->data */ + + mad->hdr.id = my_agent; /* req.id from agent registration */ + mad->hdr.lid = my_dest; /* in network byte order... */ + /* etc. */ + + ret = write(fd, &mad, sizeof *mad + mad_length); + if (ret != sizeof *mad + mad_length) + perror("write"); + +交换IDs +======= + + umad设备的用户可以在发送的MAD中使用交换ID字段的低32位（也就是网络字节顺序中 + 最小有效的一半字段）来匹配请求/响应对。上面的32位是保留给内核使用的，在发送 + MAD之前会被改写。 + +P_Key索引处理 +============= + + 旧的ib_umad接口不允许为发送的MAD设置P_Key索引，也没有提供获取接收的MAD的 + P_Key索引的方法。一个带有pkey_index成员的struct ib_user_mad_hdr的新布局已 + 经被定义；然而，为了保持与旧的应用程序的二进制兼容性，除非在文件描述符被用于 + 其他用途之前调用IB_USER_MAD_ENABLE_PKEY或IB_USER_MAD_REGISTER_AGENT2 ioctl + 之一，否则不会使用这种新布局。 + + 在2008年9月，IB_USER_MAD_ABI_VERSION将被增加到6，默认使用新的ib_user_mad_hdr + 结构布局，并且IB_USER_MAD_ENABLE_PKEY ioctl将被删除。 + +设置IsSM功能位 +============== + + 要为一个端口设置IsSM功能位，只需打开相应的issm设备文件。如果IsSM位已经被设置，那 + 么打开调用将阻塞，直到该位被清除（或者如果O_NONBLOCK标志被传递给open()，则立即返 + 回，errno设置为EAGAIN）。当issm文件被关闭时，IsSM位将被清除。在issm文件上不能进 + 行任何读、写或其他操作。 + +/dev文件 +======== + +为了用 udev自动创建相应的字符设备文件，一个类似:: + + KERNEL=="umad*", NAME="infiniband/%k" + KERNEL=="issm*", NAME="infiniband/%k" + + 的规则可以被使用。它将创建节点的名字:: + + /dev/infiniband/umad0 + /dev/infiniband/issm0 + + 为第一个端口，以此类推。与这些设备相关的infiniband设备和端口可以从以下文件中确定:: + + /sys/class/infiniband_mad/umad0/ibdev + /sys/class/infiniband_mad/umad0/port + + 和:: + + /sys/class/infiniband_mad/issm0/ibdev + /sys/class/infiniband_mad/issm0/port diff --git a/Documentation/translations/zh_CN/infiniband/user_verbs.rst b/Documentation/translations/zh_CN/infiniband/user_verbs.rst new file mode 100644 index 000000000000..970bc1a4e396 --- /dev/null +++ b/Documentation/translations/zh_CN/infiniband/user_verbs.rst @@ -0,0 +1,72 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/infiniband/user_verbs.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 王普宇 Puyu Wang <realpuyuwang@gmail.com> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_infiniband_user_verbs: + +================= +用户空间verbs访问 +================= + + ib_uverbs模块，通过启用CONFIG_INFINIBAND_USER_VERBS构建，使用户空间 + 通过“verbs”直接访问IB硬件，如InfiniBand架构规范第11章所述。 + + 要使用verbs，需要libibverbs库，可从https://github.com/linux-rdma/rdma-core。 + libibverbs包含一个独立于设备的API，用于使用ib_uverbs接口。libibverbs + 还需要为你的InfiniBand硬件提供适当的独立于设备的内核和用户空间驱动。例如， + 要使用Mellanox HCA，你需要安装ib_mthca内核模块和libmthca用户空间驱动。 + +用户-内核通信 +============= + + 用户空间通过/dev/infiniband/uverbsN字符设备与内核进行慢速路径、资源管理 + 操作的通信。快速路径操作通常是通过直接写入硬件寄存器mmap()到用户空间来完成 + 的，没有系统调用或上下文切换到内核。 + + 命令是通过在这些设备文件上的write()s发送给内核的。ABI在 + drivers/infiniband/include/ib_user_verbs.h中定义。需要内核响应的命令的结 + 构包含一个64位字段，用来传递一个指向输出缓冲区的指针。状态作为write()系统调 + 用的返回值被返回到用户空间。 + +资源管理 +======== + + 由于所有IB资源的创建和销毁都是通过文件描述符传递的命令完成的，所以内核可以跟 + 踪那些被附加到给定用户空间上下文的资源。ib_uverbs模块维护着idr表，用来在 + 内核指针和不透明的用户空间句柄之间进行转换，这样内核指针就不会暴露给用户空间， + 而用户空间也无法欺骗内核去跟踪一个假的指针。 + + 这也允许内核在一个进程退出时进行清理，并防止一个进程触及另一个进程的资源。 + +内存固定 +======== + + 直接的用户空间I/O要求与作为潜在I/O目标的内存区域保持在同一物理地址上。ib_uverbs + 模块通过get_user_pages()和put_page()调用来管理内存区域的固定和解除固定。它还核 + 算进程的pinned_vm中被固定的内存量，并检查非特权进程是否超过其RLIMIT_MEMLOCK限制。 + + 被多次固定的页面在每次被固定时都会被计数，所以pinned_vm的值可能会高估一个进程所 + 固定的页面数量。 + +/dev文件 +======== + + 要想用udev自动创建适当的字符设备文件，可以采用如下规则:: + + KERNEL=="uverbs*", NAME="infiniband/%k" + + 可以使用。 这将创建设备节点，名为:: + + /dev/infiniband/uverbs0 + + 等等。由于InfiniBand的用户空间verbs对于非特权进程来说应该是安全的，因此在udev规 + 则中加入适当的MODE或GROUP可能是有用的。 diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index b8c484a84d10..638d714bec83 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -268,8 +268,7 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字 ``count_active_users()`` 或者类似的名字，你不应该叫它 ``cntuser()`` 。 在函数名中包含函数类型 (所谓的匈牙利命名法) 是脑子出了问题——编译器知道那些类 -型而且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题 -的程序。 +型而且能够检查那些类型，这样做只能把程序员弄糊涂了。 本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计 数器，它应该被称为 ``i`` 。叫它 ``loop_counter`` 并无益处，如果它没有被误解的 diff --git a/Documentation/translations/zh_CN/virt/acrn/cpuid.rst b/Documentation/translations/zh_CN/virt/acrn/cpuid.rst new file mode 100644 index 000000000000..6f7be545611b --- /dev/null +++ b/Documentation/translations/zh_CN/virt/acrn/cpuid.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/virt/acrn/cpuid.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_acrn_cpuid: + +============== +ACRN CPUID位域 +============== + +在ACRN超级管理器上运行的客户虚拟机可以使用CPUID检查其一些功能。 + +ACRN的cpuid函数是: + +函数: 0x40000000 + +返回:: + + eax = 0x40000010 + ebx = 0x4e524341 + ecx = 0x4e524341 + edx = 0x4e524341 + +注意，ebx，ecx和edx中的这个值对应于字符串“ACRNACRNACRN”。eax中的值对应于这个叶子 +中存在的最大cpuid函数，如果将来有更多的函数加入，将被更新。 + +函数: define ACRN_CPUID_FEATURES (0x40000001) + +返回:: + + ebx, ecx, edx + eax = an OR'ed group of (1 << flag) + +其中 ``flag`` 的定义如下: + +================================= =========== ================================ +标志 值 描述 +================================= =========== ================================ +ACRN_FEATURE_PRIVILEGED_VM 0 客户虚拟机是一个有特权的虚拟机 +================================= =========== ================================ + +函数: 0x40000010 + +返回:: + + ebx, ecx, edx + eax = (Virtual) TSC frequency in kHz. diff --git a/Documentation/translations/zh_CN/virt/acrn/index.rst b/Documentation/translations/zh_CN/virt/acrn/index.rst new file mode 100644 index 000000000000..34605d87f103 --- /dev/null +++ b/Documentation/translations/zh_CN/virt/acrn/index.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/virt/acrn/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_acrn_index: + +============== +ACRN超级管理器 +============== + +.. toctree:: + :maxdepth: 1 + + introduction + io-request + cpuid diff --git a/Documentation/translations/zh_CN/virt/acrn/introduction.rst b/Documentation/translations/zh_CN/virt/acrn/introduction.rst new file mode 100644 index 000000000000..7182415cb087 --- /dev/null +++ b/Documentation/translations/zh_CN/virt/acrn/introduction.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/virt/acrn/introduction.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_acrn_introduction: + +ACRN超级管理器介绍 +================== + +ACRN超级管理器是一个第一类超级管理器，直接在裸机硬件上运行。它有一个特权管理虚拟机，称为服 +务虚拟机，用于管理用户虚拟机和进行I/O仿真。 + +ACRN用户空间是一个运行在服务虚拟机中的应用程序，它根据命令行配置为用户虚拟机仿真设备。 +ACRN管理程序服务模块（HSM）是服务虚拟机中的一个内核模块，为ACRN用户空间提供管理程序服 +务。 + +下图展示了该架构。 + +:: + + 服务端VM 用户端VM + +----------------------------+ | +------------------+ + | +--------------+ | | | | + | |ACRN用户空间 | | | | | + | +--------------+ | | | | + |-----------------ioctl------| | | | ... + |内核空间 +----------+ | | | | + | | HSM | | | | 驱动 | + | +----------+ | | | | + +--------------------|-------+ | +------------------+ + +---------------------hypercall----------------------------------------+ + | ACRN超级管理器 | + +----------------------------------------------------------------------+ + | 硬件 | + +----------------------------------------------------------------------+ + +ACRN用户空间为用户虚拟机分配内存，配置和初始化用户虚拟机使用的设备，加载虚拟引导程序， +初始化虚拟CPU状态，处理来自用户虚拟机的I/O请求访问。它使用ioctls来与HSM通信。HSM通过 +与ACRN超级管理器的hypercalls进行交互来实现管理服务。HSM向用户空间输出一个char设备接口 +（/dev/acrn_hsm）。 + +ACRN超级管理器是开源的，任何人都可以贡献。源码库在 +https://github.com/projectacrn/acrn-hypervisor。 diff --git a/Documentation/translations/zh_CN/virt/acrn/io-request.rst b/Documentation/translations/zh_CN/virt/acrn/io-request.rst new file mode 100644 index 000000000000..4b4e7186d9a5 --- /dev/null +++ b/Documentation/translations/zh_CN/virt/acrn/io-request.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/virt/acrn/io-request.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_acrn_io-request: + +I/O请求处理 +=========== + +客户虚拟机的I/O请求由超级管理器构建，由ACRN超级管理器服务模块分发到与I/O请求的地址范 +围相对应的I/O客户端。I/O请求处理的细节将在以下章节描述。 + +1. I/O请求 +---------- + +对于每个客户虚拟机，有一个共享的4KB字节的内存区域，用于超级管理器和服务虚拟机之间的 +I/O请求通信。一个I/O请求是一个256字节的结构体缓冲区，它是 "acrn_io_request" 结构 +体，当客户虚拟机中发生被困的I/O访问时，由超级管理器的I/O处理器填充。服务虚拟机中的 +ACRN用户空间首先分配一个4KB字节的页面，并将缓冲区的GPA（客户物理地址）传递给管理平 +台。缓冲区被用作16个I/O请求槽的数组，每个I/O请求槽为256字节。这个数组是按vCPU ID +索引的。 + +2. I/O客户端 +------------ + +一个I/O客户端负责处理客户虚拟机的I/O请求，其访问的GPA在一定范围内。每个客户虚拟机 +可以关联多个I/O客户端。每个客户虚拟机都有一个特殊的客户端，称为默认客户端，负责处理 +所有不在其他客户端范围内的I/O请求。ACRN用户空间充当每个客户虚拟机的默认客户端。 + +下面的图示显示了I/O请求共享缓冲区、I/O请求和I/O客户端之间的关系。 + +:: + + +------------------------------------------------------+ + | 服务VM | + |+--------------------------------------------------+ | + || +----------------------------------------+ | | + || | 共享页 ACRN用户空间 | | | + || | +-----------------+ +------------+ | | | + || +----+->| acrn_io_request |<-+ 默认 | | | | + || | | | +-----------------+ | I/O客户端 | | | | + || | | | | ... | +------------+ | | | + || | | | +-----------------+ | | | + || | +-|--------------------------------------+ | | + ||---|----|-----------------------------------------| | + || | | 内核 | | + || | | +----------------------+ | | + || | | | +-------------+ HSM | | | + || | +--------------+ | | | | + || | | | I/O客户端 | | | | + || | | | | | | | + || | | +-------------+ | | | + || | +----------------------+ | | + |+---|----------------------------------------------+ | + +----|-------------------------------------------------+ + | + +----|-------------------------------------------------+ + | +-+-----------+ | + | | I/O处理 | ACRN超级管理器 | + | +-------------+ | + +------------------------------------------------------+ + +3. I/O请求状态转换 +------------------ + +一个ACRN I/O请求的状态转换如下。 + +:: + + FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ... + +- FREE: 这个I/O请求槽是空的 +- PENDING: 在这个槽位上有一个有效的I/O请求正在等待 +- PROCESSING: 正在处理I/O请求 +- COMPLETE: 该I/O请求已被处理 + +处于COMPLETE或FREE状态的I/O请求是由超级管理器拥有的。HSM和ACRN用户空间负责处理其 +他的。 + +4. I/O请求的处理流程 +-------------------- + +a. 当客户虚拟机中发生被陷入的I/O访问时，超级管理器的I/O处理程序将把I/O请求填充为 + PENDING状态。 +b. 超级管理器向服务虚拟机发出一个向上调用，这是一个通知中断。 +c. upcall处理程序会安排一个工作者来调度I/O请求。 +d. 工作者寻找PENDING I/O请求，根据I/O访问的地址将其分配给不同的注册客户，将其 + 状态更新为PROCESSING，并通知相应的客户进行处理。 +e. 被通知的客户端处理指定的I/O请求。 +f. HSM将I/O请求状态更新为COMPLETE，并通过hypercalls通知超级管理器完成。 diff --git a/Documentation/translations/zh_CN/virt/guest-halt-polling.rst b/Documentation/translations/zh_CN/virt/guest-halt-polling.rst new file mode 100644 index 000000000000..b798d1cf0b48 --- /dev/null +++ b/Documentation/translations/zh_CN/virt/guest-halt-polling.rst @@ -0,0 +1,87 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/virt/guest-halt-polling.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_guest-halt-polling: + +======================================== +客户机停机轮询机制（Guest halt polling） +======================================== + +cpuidle_haltpoll驱动，与haltpoll管理器一起，允许客户机vcpus在停机前轮询 +一定的时间。 + +这为物理机侧的轮询提供了以下好处: + + 1) 在执行轮询时，POLL标志被设置，这允许远程vCPU在执行唤醒时避免发送 + IPI（以及处理IPI的相关成本）。 + + 2) 可以避免虚拟机退出的成本。 + +客户机侧轮询的缺点是，即使在物理机中的其他可运行任务中也会进行轮询。 + +其基本逻辑如下。一个全局值，即guest_halt_poll_ns，是由用户配置的，表示允 +许轮询的最大时间量。这个值是固定的。 + +每个vcpu都有一个可调整的guest_halt_poll_ns（"per-cpu guest_halt_poll_ns"）， +它由算法响应事件进行调整（解释如下）。 + +模块参数 +======== + +haltpoll管理器有5个可调整的模块参数: + +1) guest_halt_poll_ns: + +轮询停机前执行的最大时间，以纳秒为单位。 + +默认值: 200000 + +2) guest_halt_poll_shrink: + +当唤醒事件发生在全局的guest_halt_poll_ns之后，用于缩减每个CPU的guest_halt_poll_ns +的划分系数。 + +默认值: 2 + +3) guest_halt_poll_grow: + +当事件发生在per-cpu guest_halt_poll_ns之后但在global guest_halt_poll_ns之前， +用于增长per-cpu guest_halt_poll_ns的乘法系数。 + +默认值: 2 + +4) guest_halt_poll_grow_start: + +在系统空闲的情况下，每个cpu guest_halt_poll_ns最终达到零。这个值设置了增长时的 +初始每cpu guest_halt_poll_ns。这个值可以从10000开始增加，以避免在最初的增长阶 +段出现失误。: + +10k, 20k, 40k, ... (例如，假设guest_halt_poll_grow=2). + +默认值: 50000 + +5) guest_halt_poll_allow_shrink: + +允许缩减的Bool参数。设置为N以避免它（一旦达到全局的guest_halt_poll_ns值，每CPU的 +guest_halt_poll_ns将保持高位）。 + +默认值: Y + +模块参数可以从Debugfs文件中设置，在:: + + /sys/module/haltpoll/parameters/ + +进一步说明 +========== + +- 在设置guest_halt_poll_ns参数时应该小心，因为一个大的值有可能使几乎是完全空闲机 + 器上的cpu使用率达到100%。 diff --git a/Documentation/translations/zh_CN/virt/index.rst b/Documentation/translations/zh_CN/virt/index.rst new file mode 100644 index 000000000000..f8dd13681341 --- /dev/null +++ b/Documentation/translations/zh_CN/virt/index.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/virt/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_index: + +=============== +Linux虚拟化支持 +=============== + +.. toctree:: + :maxdepth: 2 + + paravirt_ops + guest-halt-polling + ne_overview + acrn/index + +TODOLIST: + + kvm/index + uml/user_mode_linux_howto_v2 + +.. only:: html and subproject + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/virt/ne_overview.rst b/Documentation/translations/zh_CN/virt/ne_overview.rst new file mode 100644 index 000000000000..2455b371abea --- /dev/null +++ b/Documentation/translations/zh_CN/virt/ne_overview.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/virt/ne_overview.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_ne_overview: + +============== +Nitro Enclaves +============== + +概述 +==== + +Nitro Enclaves（NE）是亚马逊弹性计算云（EC2）的一项新功能，允许客户在EC2实 +例中划分出孤立的计算环境[1]。 + +例如，一个处理敏感数据并在虚拟机中运行的应用程序，可以与在同一虚拟机中运行的 +其他应用程序分开。然后，这个应用程序在一个独立于主虚拟机的虚拟机中运行，即 +enclave。 + +一个enclave与催生它的虚拟机一起运行。这种设置符合低延迟应用的需要。为enclave +分配的资源，如内存和CPU，是从主虚拟机中分割出来的。每个enclave都被映射到一 +个运行在主虚拟机中的进程，该进程通过一个ioctl接口与NE驱动进行通信。 + +在这个意义上，有两个组成部分。 + +1. 一个enclave抽象进程——一个运行在主虚拟机客体中的用户空间进程，它使用NE驱动 +提供的ioctl接口来生成一个enclave虚拟机（这就是下面的2）。 + +有一个NE模拟的PCI设备暴露给主虚拟机。这个新的PCI设备的驱动被包含在NE驱动中。 + +ioctl逻辑被映射到PCI设备命令，例如，NE_START_ENCLAVE ioctl映射到一个enclave +启动PCI命令。然后，PCI设备命令被翻译成在管理程序方面采取的行动；也就是在运 +行主虚拟机的主机上运行的Nitro管理程序。Nitro管理程序是基于KVM核心技术的。 + +2. enclave本身——一个运行在与催生它的主虚拟机相同的主机上的虚拟机。内存和CPU +从主虚拟机中分割出来，专门用于enclave虚拟机。enclave没有连接持久性存储。 + +从主虚拟机中分割出来并给enclave的内存区域需要对齐2 MiB/1 GiB物理连续的内存 +区域（或这个大小的倍数，如8 MiB）。该内存可以通过使用hugetlbfs从用户空间分 +配[2][3]。一个enclave的内存大小需要至少64 MiB。enclave内存和CPU需要来自同 +一个NUMA节点。 + +一个enclave在专用的核心上运行。CPU 0及其同级别的CPU需要保持对主虚拟机的可用 +性。CPU池必须由具有管理能力的用户为NE目的进行设置。关于CPU池的格式，请看内核 +文档[4]中的cpu list部分。 + +enclave通过本地通信通道与主虚拟机进行通信，使用virtio-vsock[5]。主虚拟机有 +virtio-pci vsock模拟设备，而飞地虚拟机有virtio-mmio vsock模拟设备。vsock +设备使用eventfd作为信令。enclave虚拟机看到通常的接口——本地APIC和IOAPIC——从 +virtio-vsock设备获得中断。virtio-mmio设备被放置在典型的4 GiB以下的内存中。 + +在enclave中运行的应用程序需要和将在enclave虚拟机中运行的操作系统（如内核、 +ramdisk、init）一起被打包到enclave镜像中。enclave虚拟机有自己的内核并遵循标 +准的Linux启动协议[6]。 + +内核bzImage、内核命令行、ramdisk（s）是enclave镜像格式（EIF）的一部分；另外 +还有一个EIF头，包括元数据，如magic number、eif版本、镜像大小和CRC。 + +哈希值是为整个enclave镜像（EIF）、内核和ramdisk（s）计算的。例如，这被用来检 +查在enclave虚拟机中加载的enclave镜像是否是打算运行的那个。 + +这些加密测量包括在由Nitro超级管理器成的签名证明文件中，并进一步用来证明enclave +的身份；KMS是NE集成的服务的一个例子，它检查证明文件。 + +enclave镜像（EIF）被加载到enclave内存中，偏移量为8 MiB。enclave中的初始进程 +连接到主虚拟机的vsock CID和一个预定义的端口--9000，以发送一个心跳值--0xb7。这 +个机制用于在主虚拟机中检查enclave是否已经启动。主虚拟机的CID是3。 + +如果enclave虚拟机崩溃或优雅地退出，NE驱动会收到一个中断事件。这个事件会通过轮询 +通知机制进一步发送到运行在主虚拟机中的用户空间enclave进程。然后，用户空间enclave +进程就可以退出了。 + +[1] https://aws.amazon.com/ec2/nitro/nitro-enclaves/ +[2] https://www.kernel.org/doc/html/latest/admin-guide/mm/hugetlbpage.html +[3] https://lwn.net/Articles/807108/ +[4] https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html +[5] https://man7.org/linux/man-pages/man7/vsock.7.html +[6] https://www.kernel.org/doc/html/latest/x86/boot.html diff --git a/Documentation/translations/zh_CN/virt/paravirt_ops.rst b/Documentation/translations/zh_CN/virt/paravirt_ops.rst new file mode 100644 index 000000000000..06b122bc915d --- /dev/null +++ b/Documentation/translations/zh_CN/virt/paravirt_ops.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/virt/paravirt_ops.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + 陈飞杨 Feiyang Chen <chenfeiyang@loongson.cn> + 时奎亮 Alex Shi <alexs@kernel.org> + +.. _cn_virt_paravirt_ops: + +============ +半虚拟化操作 +============ + +Linux提供了对不同管理程序虚拟化技术的支持。历史上，为了支持不同的虚拟机超级管理器 +（hypervisor，下文简称超级管理器），需要不同的二进制内核，这个限制已经被pv_ops移 +除了。Linux pv_ops是一个虚拟化API，它能够支持不同的管理程序。它允许每个管理程序 +优先于关键操作，并允许单一的内核二进制文件在所有支持的执行环境中运行，包括本机——没 +有任何管理程序。 + +pv_ops提供了一组函数指针，代表了与低级关键指令和各领域高级功能相对应的操作。 +pv-ops允许在运行时进行优化，在启动时对低级关键操作进行二进制修补。 + +pv_ops操作被分为三类: + +- 简单的间接调用 + 这些操作对应于高水平的函数，众所周知，间接调用的开销并不十分重要。 + +- 间接调用，允许用二进制补丁进行优化 + 通常情况下，这些操作对应于低级别的关键指令。它们被频繁地调用，并且是对性能关 + 键。开销是非常重要的。 + +- 一套用于手写汇编代码的宏程序 + 手写的汇编代码（.S文件）也需要半虚拟化，因为它们包括敏感指令或其中的一些代 + 码路径对性能非常关键。 |