From e790a4ce529041bb21ec0b69a38c1b92f29df2cf Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 3 May 2023 16:47:22 -0600 Subject: arm: docs: Move Arm documentation to Documentation/arch/ Architecture-specific documentation is being moved into Documentation/arch/ as a way of cleaning up the top-level documentation directory and making the docs hierarchy more closely match the source hierarchy. Move Documentation/arm into arch/ (along with the Chinese equvalent translations). Cc: Maxime Coquelin Cc: Chen-Yu Tsai Cc: Jernej Skrabec Cc: Samuel Holland Cc: Krzysztof Kozlowski Cc: Alim Akhtar Cc: Alex Shi Cc: linux-doc@vger.kernel.org Cc: linux-arm-kernel@lists.infradead.org Cc: linux-arch@vger.kernel.org Acked-by: Alexandre TORGUE Reviewed-by: Yanteng Si Signed-off-by: Jonathan Corbet --- Documentation/translations/zh_CN/arch/arm/Booting | 175 +++++++++++++ .../zh_CN/arch/arm/kernel_user_helpers.txt | 284 +++++++++++++++++++++ Documentation/translations/zh_CN/arm/Booting | 175 ------------- .../translations/zh_CN/arm/kernel_user_helpers.txt | 284 --------------------- 4 files changed, 459 insertions(+), 459 deletions(-) create mode 100644 Documentation/translations/zh_CN/arch/arm/Booting create mode 100644 Documentation/translations/zh_CN/arch/arm/kernel_user_helpers.txt delete mode 100644 Documentation/translations/zh_CN/arm/Booting delete mode 100644 Documentation/translations/zh_CN/arm/kernel_user_helpers.txt (limited to 'Documentation/translations/zh_CN') diff --git a/Documentation/translations/zh_CN/arch/arm/Booting b/Documentation/translations/zh_CN/arch/arm/Booting new file mode 100644 index 000000000000..f18585156b67 --- /dev/null +++ b/Documentation/translations/zh_CN/arch/arm/Booting @@ -0,0 +1,175 @@ +Chinese translated version of Documentation/arch/arm/booting.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Russell King +Chinese maintainer: Fu Wei +--------------------------------------------------------------------- +Documentation/arch/arm/booting.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Russell King +中文版维护者： 傅炜 Fu Wei +中文版翻译者： 傅炜 Fu Wei +中文版校译者： 傅炜 Fu Wei + +以下为正文 +--------------------------------------------------------------------- + + 启动 ARM Linux + ============== + +作者：Russell King +日期：2002年5月18日 + +以下文档适用于 2.4.18-rmk6 及以上版本。 + +为了启动 ARM Linux，你需要一个引导装载程序（boot loader）， +它是一个在主内核启动前运行的一个小程序。引导装载程序需要初始化各种 +设备，并最终调用 Linux 内核，将信息传递给内核。 + +从本质上讲，引导装载程序应提供（至少）以下功能： + +1、设置和初始化 RAM。 +2、初始化一个串口。 +3、检测机器的类型（machine type）。 +4、设置内核标签列表（tagged list）。 +5、调用内核映像。 + + +1、设置和初始化 RAM +------------------- + +现有的引导加载程序: 强制 +新开发的引导加载程序: 强制 + +引导装载程序应该找到并初始化系统中所有内核用于保持系统变量数据的 RAM。 +这个操作的执行是设备依赖的。（它可能使用内部算法来自动定位和计算所有 +RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何引导装载程序 +设计者想到的匹配方法。） + + +2、初始化一个串口 +----------------------------- + +现有的引导加载程序: 可选、建议 +新开发的引导加载程序: 可选、建议 + +引导加载程序应该初始化并使能一个目标板上的串口。这允许内核串口驱动 +自动检测哪个串口用于内核控制台。(一般用于调试或与目标板通信。) + +作为替代方案，引导加载程序也可以通过标签列表传递相关的'console=' +选项给内核以指定某个串口，而串口数据格式的选项在以下文档中描述： + + Documentation/admin-guide/kernel-parameters.rst。 + + +3、检测机器类型 +-------------------------- + +现有的引导加载程序: 可选 +新开发的引导加载程序: 强制 + +引导加载程序应该通过某些方式检测自身所处的机器类型。这是一个硬件 +代码或通过查看所连接的硬件用某些算法得到，这些超出了本文档的范围。 +引导加载程序最终必须能提供一个 MACH_TYPE_xxx 值给内核。 +(详见 linux/arch/arm/tools/mach-types )。 + +4、设置启动数据 +------------------ + +现有的引导加载程序: 可选、强烈建议 +新开发的引导加载程序: 强制 + +引导加载程序必须提供标签列表或者 dtb 映像以传递配置数据给内核。启动 +数据的物理地址通过寄存器 r2 传递给内核。 + +4a、设置内核标签列表 +-------------------------------- + +bootloader 必须创建和初始化内核标签列表。一个有效的标签列表以 +ATAG_CORE 标签开始，并以 ATAG_NONE 标签结束。ATAG_CORE 标签可以是 +空的，也可以是非空。一个空 ATAG_CORE 标签其 size 域设置为 +‘2’(0x00000002)。ATAG_NONE 标签的 size 域必须设置为零。 + +在列表中可以保存任意数量的标签。对于一个重复的标签是追加到之前标签 +所携带的信息之后，还是会覆盖原来的信息，是未定义的。某些标签的行为 +是前者，其他是后者。 + +bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。 +因此，最小的标签列表如下所示： + + +-----------+ +基地址 -> | ATAG_CORE | | + +-----------+ | + | ATAG_MEM | | 地址增长方向 + +-----------+ | + | ATAG_NONE | | + +-----------+ v + +标签列表应该保存在系统的 RAM 中。 + +标签列表必须置于内核自解压和 initrd'bootp' 程序都不会覆盖的内存区。 +建议放在 RAM 的头 16KiB 中。 + +4b、设置设备树 +------------------------- + +bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统 +RAM 中，并用启动数据初始化它。dtb 格式在文档 +https://www.devicetree.org/specifications/ 中。内核将会在 +dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替 +标签列表被传递进来。 + +bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。 +dtb 必须置于内核自解压不会覆盖的内存区。建议将其放置于 RAM 的头 16KiB +中。但是不可将其放置于“0”物理地址处，因为内核认为：r2 中为 0，意味着 +没有标签列表和 dtb 传递过来。 + +5、调用内核映像 +--------------------------- + +现有的引导加载程序: 强制 +新开发的引导加载程序: 强制 + +调用内核映像 zImage 有两个选择。如果 zImge 保存在 flash 中，且是为了 +在 flash 中直接运行而被正确链接的。这样引导加载程序就可以在 flash 中 +直接调用 zImage。 + +zImage 也可以被放在系统 RAM（任意位置）中被调用。注意：内核使用映像 +基地址的前 16KB RAM 空间来保存页表。建议将映像置于 RAM 的 32KB 处。 + +对于以上任意一种情况，都必须符合以下启动状态： + +- 停止所有 DMA 设备，这样内存数据就不会因为虚假网络包或磁盘数据而被破坏。 + 这可能可以节省你许多的调试时间。 + +- CPU 寄存器配置 + r0 = 0， + r1 = （在上面 3 中获取的）机器类型码。 + r2 = 标签列表在系统 RAM 中的物理地址，或 + 设备树块(dtb)在系统 RAM 中的物理地址 + +- CPU 模式 + 所有形式的中断必须被禁止 (IRQs 和 FIQs) + CPU 必须处于 SVC 模式。(对于 Angel 调试有特例存在) + +- 缓存，MMUs + MMU 必须关闭。 + 指令缓存开启或关闭都可以。 + 数据缓存必须关闭。 + +- 引导加载程序应该通过直接跳转到内核映像的第一条指令来调用内核映像。 + + 对于支持 ARM 指令集的 CPU，跳入内核入口时必须处在 ARM 状态，即使 + 对于 Thumb-2 内核也是如此。 + + 对于仅支持 Thumb 指令集的 CPU，比如 Cortex-M 系列的 CPU，跳入 + 内核入口时必须处于 Thumb 状态。 diff --git a/Documentation/translations/zh_CN/arch/arm/kernel_user_helpers.txt b/Documentation/translations/zh_CN/arch/arm/kernel_user_helpers.txt new file mode 100644 index 000000000000..018eb7d54233 --- /dev/null +++ b/Documentation/translations/zh_CN/arch/arm/kernel_user_helpers.txt @@ -0,0 +1,284 @@ +Chinese translated version of Documentation/arch/arm/kernel_user_helpers.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Nicolas Pitre + Dave Martin +Chinese maintainer: Fu Wei +--------------------------------------------------------------------- +Documentation/arch/arm/kernel_user_helpers.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Nicolas Pitre + Dave Martin +中文版维护者： 傅炜 Fu Wei +中文版翻译者： 傅炜 Fu Wei +中文版校译者： 宋冬生 Dongsheng Song + 傅炜 Fu Wei + + +以下为正文 +--------------------------------------------------------------------- +内核提供的用户空间辅助代码 +========================= + +在内核内存空间的固定地址处，有一个由内核提供并可从用户空间访问的代码 +段。它用于向用户空间提供因在许多 ARM CPU 中未实现的特性和/或指令而需 +内核提供帮助的某些操作。这些代码直接在用户模式下执行的想法是为了获得 +最佳效率，但那些与内核计数器联系过于紧密的部分，则被留给了用户库实现。 +事实上，此代码甚至可能因不同的 CPU 而异，这取决于其可用的指令集或它 +是否为 SMP 系统。换句话说，内核保留在不作出警告的情况下根据需要更改 +这些代码的权利。只有本文档描述的入口及其结果是保证稳定的。 + +这与完全成熟的 VDSO 实现不同（但两者并不冲突），尽管如此，VDSO 可阻止 +某些通过常量高效跳转到那些代码段的汇编技巧。且由于那些代码段在返回用户 +代码前仅使用少量的代码周期，则一个 VDSO 间接远程调用将会在这些简单的 +操作上增加一个可测量的开销。 + +在对那些拥有原生支持的新型处理器进行代码优化时，仅在已为其他操作使用 +了类似的新增指令，而导致二进制结果已与早期 ARM 处理器不兼容的情况下， +用户空间才应绕过这些辅助代码，并在内联函数中实现这些操作（无论是通过 +编译器在代码中直接放置，还是作为库函数调用实现的一部分）。也就是说， +如果你编译的代码不会为了其他目的使用新指令，则不要仅为了避免使用这些 +内核辅助代码，导致二进制程序无法在早期处理器上运行。 + +新的辅助代码可能随着时间的推移而增加，所以新内核中的某些辅助代码在旧 +内核中可能不存在。因此，程序必须在对任何辅助代码调用假设是安全之前， +检测 __kuser_helper_version 的值（见下文）。理想情况下，这种检测应该 +只在进程启动时执行一次；如果内核版本不支持所需辅助代码，则该进程可尽早 +中止执行。 + +kuser_helper_version +-------------------- + +位置: 0xffff0ffc + +参考声明: + + extern int32_t __kuser_helper_version; + +定义: + + 这个区域包含了当前运行内核实现的辅助代码版本号。用户空间可以通过读 + 取此版本号以确定特定的辅助代码是否存在。 + +使用范例: + +#define __kuser_helper_version (*(int32_t *)0xffff0ffc) + +void check_kuser_version(void) +{ + if (__kuser_helper_version < 2) { + fprintf(stderr, "can't do atomic operations, kernel too old\n"); + abort(); + } +} + +注意: + + 用户空间可以假设这个域的值不会在任何单个进程的生存期内改变。也就 + 是说，这个域可以仅在库的初始化阶段或进程启动阶段读取一次。 + +kuser_get_tls +------------- + +位置: 0xffff0fe0 + +参考原型: + + void * __kuser_get_tls(void); + +输入: + + lr = 返回地址 + +输出: + + r0 = TLS 值 + +被篡改的寄存器: + + 无 + +定义: + + 获取之前通过 __ARM_NR_set_tls 系统调用设置的 TLS 值。 + +使用范例: + +typedef void * (__kuser_get_tls_t)(void); +#define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0) + +void foo() +{ + void *tls = __kuser_get_tls(); + printf("TLS = %p\n", tls); +} + +注意: + + - 仅在 __kuser_helper_version >= 1 时，此辅助代码存在 + （从内核版本 2.6.12 开始）。 + +kuser_cmpxchg +------------- + +位置: 0xffff0fc0 + +参考原型: + + int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr); + +输入: + + r0 = oldval + r1 = newval + r2 = ptr + lr = 返回地址 + +输出: + + r0 = 成功代码 (零或非零) + C flag = 如果 r0 == 0 则置 1，如果 r0 != 0 则清零。 + +被篡改的寄存器: + + r3, ip, flags + +定义: + + 仅在 *ptr 为 oldval 时原子保存 newval 于 *ptr 中。 + 如果 *ptr 被改变，则返回值为零，否则为非零值。 + 如果 *ptr 被改变，则 C flag 也会被置 1，以实现调用代码中的汇编 + 优化。 + +使用范例: + +typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr); +#define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0) + +int atomic_add(volatile int *ptr, int val) +{ + int old, new; + + do { + old = *ptr; + new = old + val; + } while(__kuser_cmpxchg(old, new, ptr)); + + return new; +} + +注意: + + - 这个例程已根据需要包含了内存屏障。 + + - 仅在 __kuser_helper_version >= 2 时，此辅助代码存在 + （从内核版本 2.6.12 开始）。 + +kuser_memory_barrier +-------------------- + +位置: 0xffff0fa0 + +参考原型: + + void __kuser_memory_barrier(void); + +输入: + + lr = 返回地址 + +输出: + + 无 + +被篡改的寄存器: + + 无 + +定义: + + 应用于任何需要内存屏障以防止手动数据修改带来的一致性问题，以及 + __kuser_cmpxchg 中。 + +使用范例: + +typedef void (__kuser_dmb_t)(void); +#define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) + +注意: + + - 仅在 __kuser_helper_version >= 3 时，此辅助代码存在 + （从内核版本 2.6.15 开始）。 + +kuser_cmpxchg64 +--------------- + +位置: 0xffff0f60 + +参考原型: + + int __kuser_cmpxchg64(const int64_t *oldval, + const int64_t *newval, + volatile int64_t *ptr); + +输入: + + r0 = 指向 oldval + r1 = 指向 newval + r2 = 指向目标值 + lr = 返回地址 + +输出: + + r0 = 成功代码 (零或非零) + C flag = 如果 r0 == 0 则置 1，如果 r0 != 0 则清零。 + +被篡改的寄存器: + + r3, lr, flags + +定义: + + 仅在 *ptr 等于 *oldval 指向的 64 位值时，原子保存 *newval + 指向的 64 位值于 *ptr 中。如果 *ptr 被改变，则返回值为零， + 否则为非零值。 + + 如果 *ptr 被改变，则 C flag 也会被置 1，以实现调用代码中的汇编 + 优化。 + +使用范例: + +typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval, + const int64_t *newval, + volatile int64_t *ptr); +#define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60) + +int64_t atomic_add64(volatile int64_t *ptr, int64_t val) +{ + int64_t old, new; + + do { + old = *ptr; + new = old + val; + } while(__kuser_cmpxchg64(&old, &new, ptr)); + + return new; +} + +注意: + + - 这个例程已根据需要包含了内存屏障。 + + - 由于这个过程的代码长度（此辅助代码跨越 2 个常规的 kuser “槽”）， + 因此 0xffff0f80 不被作为有效的入口点。 + + - 仅在 __kuser_helper_version >= 5 时，此辅助代码存在 + （从内核版本 3.1 开始）。 diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting deleted file mode 100644 index 5ecea0767893..000000000000 --- a/Documentation/translations/zh_CN/arm/Booting +++ /dev/null @@ -1,175 +0,0 @@ -Chinese translated version of Documentation/arm/booting.rst - -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. - -Maintainer: Russell King -Chinese maintainer: Fu Wei ---------------------------------------------------------------------- -Documentation/arm/booting.rst 的中文翻译 - -如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 -交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 -译存在问题，请联系中文版维护者。 - -英文版维护者： Russell King -中文版维护者： 傅炜 Fu Wei -中文版翻译者： 傅炜 Fu Wei -中文版校译者： 傅炜 Fu Wei - -以下为正文 ---------------------------------------------------------------------- - - 启动 ARM Linux - ============== - -作者：Russell King -日期：2002年5月18日 - -以下文档适用于 2.4.18-rmk6 及以上版本。 - -为了启动 ARM Linux，你需要一个引导装载程序（boot loader）， -它是一个在主内核启动前运行的一个小程序。引导装载程序需要初始化各种 -设备，并最终调用 Linux 内核，将信息传递给内核。 - -从本质上讲，引导装载程序应提供（至少）以下功能： - -1、设置和初始化 RAM。 -2、初始化一个串口。 -3、检测机器的类型（machine type）。 -4、设置内核标签列表（tagged list）。 -5、调用内核映像。 - - -1、设置和初始化 RAM -------------------- - -现有的引导加载程序: 强制 -新开发的引导加载程序: 强制 - -引导装载程序应该找到并初始化系统中所有内核用于保持系统变量数据的 RAM。 -这个操作的执行是设备依赖的。（它可能使用内部算法来自动定位和计算所有 -RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何引导装载程序 -设计者想到的匹配方法。） - - -2、初始化一个串口 ------------------------------ - -现有的引导加载程序: 可选、建议 -新开发的引导加载程序: 可选、建议 - -引导加载程序应该初始化并使能一个目标板上的串口。这允许内核串口驱动 -自动检测哪个串口用于内核控制台。(一般用于调试或与目标板通信。) - -作为替代方案，引导加载程序也可以通过标签列表传递相关的'console=' -选项给内核以指定某个串口，而串口数据格式的选项在以下文档中描述： - - Documentation/admin-guide/kernel-parameters.rst。 - - -3、检测机器类型 --------------------------- - -现有的引导加载程序: 可选 -新开发的引导加载程序: 强制 - -引导加载程序应该通过某些方式检测自身所处的机器类型。这是一个硬件 -代码或通过查看所连接的硬件用某些算法得到，这些超出了本文档的范围。 -引导加载程序最终必须能提供一个 MACH_TYPE_xxx 值给内核。 -(详见 linux/arch/arm/tools/mach-types )。 - -4、设置启动数据 ------------------- - -现有的引导加载程序: 可选、强烈建议 -新开发的引导加载程序: 强制 - -引导加载程序必须提供标签列表或者 dtb 映像以传递配置数据给内核。启动 -数据的物理地址通过寄存器 r2 传递给内核。 - -4a、设置内核标签列表 --------------------------------- - -bootloader 必须创建和初始化内核标签列表。一个有效的标签列表以 -ATAG_CORE 标签开始，并以 ATAG_NONE 标签结束。ATAG_CORE 标签可以是 -空的，也可以是非空。一个空 ATAG_CORE 标签其 size 域设置为 -‘2’(0x00000002)。ATAG_NONE 标签的 size 域必须设置为零。 - -在列表中可以保存任意数量的标签。对于一个重复的标签是追加到之前标签 -所携带的信息之后，还是会覆盖原来的信息，是未定义的。某些标签的行为 -是前者，其他是后者。 - -bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。 -因此，最小的标签列表如下所示： - - +-----------+ -基地址 -> | ATAG_CORE | | - +-----------+ | - | ATAG_MEM | | 地址增长方向 - +-----------+ | - | ATAG_NONE | | - +-----------+ v - -标签列表应该保存在系统的 RAM 中。 - -标签列表必须置于内核自解压和 initrd'bootp' 程序都不会覆盖的内存区。 -建议放在 RAM 的头 16KiB 中。 - -4b、设置设备树 -------------------------- - -bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统 -RAM 中，并用启动数据初始化它。dtb 格式在文档 -https://www.devicetree.org/specifications/ 中。内核将会在 -dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替 -标签列表被传递进来。 - -bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。 -dtb 必须置于内核自解压不会覆盖的内存区。建议将其放置于 RAM 的头 16KiB -中。但是不可将其放置于“0”物理地址处，因为内核认为：r2 中为 0，意味着 -没有标签列表和 dtb 传递过来。 - -5、调用内核映像 ---------------------------- - -现有的引导加载程序: 强制 -新开发的引导加载程序: 强制 - -调用内核映像 zImage 有两个选择。如果 zImge 保存在 flash 中，且是为了 -在 flash 中直接运行而被正确链接的。这样引导加载程序就可以在 flash 中 -直接调用 zImage。 - -zImage 也可以被放在系统 RAM（任意位置）中被调用。注意：内核使用映像 -基地址的前 16KB RAM 空间来保存页表。建议将映像置于 RAM 的 32KB 处。 - -对于以上任意一种情况，都必须符合以下启动状态： - -- 停止所有 DMA 设备，这样内存数据就不会因为虚假网络包或磁盘数据而被破坏。 - 这可能可以节省你许多的调试时间。 - -- CPU 寄存器配置 - r0 = 0， - r1 = （在上面 3 中获取的）机器类型码。 - r2 = 标签列表在系统 RAM 中的物理地址，或 - 设备树块(dtb)在系统 RAM 中的物理地址 - -- CPU 模式 - 所有形式的中断必须被禁止 (IRQs 和 FIQs) - CPU 必须处于 SVC 模式。(对于 Angel 调试有特例存在) - -- 缓存，MMUs - MMU 必须关闭。 - 指令缓存开启或关闭都可以。 - 数据缓存必须关闭。 - -- 引导加载程序应该通过直接跳转到内核映像的第一条指令来调用内核映像。 - - 对于支持 ARM 指令集的 CPU，跳入内核入口时必须处在 ARM 状态，即使 - 对于 Thumb-2 内核也是如此。 - - 对于仅支持 Thumb 指令集的 CPU，比如 Cortex-M 系列的 CPU，跳入 - 内核入口时必须处于 Thumb 状态。 diff --git a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt deleted file mode 100644 index 99af4363984d..000000000000 --- a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt +++ /dev/null @@ -1,284 +0,0 @@ -Chinese translated version of Documentation/arm/kernel_user_helpers.rst - -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. - -Maintainer: Nicolas Pitre - Dave Martin -Chinese maintainer: Fu Wei ---------------------------------------------------------------------- -Documentation/arm/kernel_user_helpers.rst 的中文翻译 - -如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 -交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 -译存在问题，请联系中文版维护者。 -英文版维护者： Nicolas Pitre - Dave Martin -中文版维护者： 傅炜 Fu Wei -中文版翻译者： 傅炜 Fu Wei -中文版校译者： 宋冬生 Dongsheng Song - 傅炜 Fu Wei - - -以下为正文 ---------------------------------------------------------------------- -内核提供的用户空间辅助代码 -========================= - -在内核内存空间的固定地址处，有一个由内核提供并可从用户空间访问的代码 -段。它用于向用户空间提供因在许多 ARM CPU 中未实现的特性和/或指令而需 -内核提供帮助的某些操作。这些代码直接在用户模式下执行的想法是为了获得 -最佳效率，但那些与内核计数器联系过于紧密的部分，则被留给了用户库实现。 -事实上，此代码甚至可能因不同的 CPU 而异，这取决于其可用的指令集或它 -是否为 SMP 系统。换句话说，内核保留在不作出警告的情况下根据需要更改 -这些代码的权利。只有本文档描述的入口及其结果是保证稳定的。 - -这与完全成熟的 VDSO 实现不同（但两者并不冲突），尽管如此，VDSO 可阻止 -某些通过常量高效跳转到那些代码段的汇编技巧。且由于那些代码段在返回用户 -代码前仅使用少量的代码周期，则一个 VDSO 间接远程调用将会在这些简单的 -操作上增加一个可测量的开销。 - -在对那些拥有原生支持的新型处理器进行代码优化时，仅在已为其他操作使用 -了类似的新增指令，而导致二进制结果已与早期 ARM 处理器不兼容的情况下， -用户空间才应绕过这些辅助代码，并在内联函数中实现这些操作（无论是通过 -编译器在代码中直接放置，还是作为库函数调用实现的一部分）。也就是说， -如果你编译的代码不会为了其他目的使用新指令，则不要仅为了避免使用这些 -内核辅助代码，导致二进制程序无法在早期处理器上运行。 - -新的辅助代码可能随着时间的推移而增加，所以新内核中的某些辅助代码在旧 -内核中可能不存在。因此，程序必须在对任何辅助代码调用假设是安全之前， -检测 __kuser_helper_version 的值（见下文）。理想情况下，这种检测应该 -只在进程启动时执行一次；如果内核版本不支持所需辅助代码，则该进程可尽早 -中止执行。 - -kuser_helper_version --------------------- - -位置: 0xffff0ffc - -参考声明: - - extern int32_t __kuser_helper_version; - -定义: - - 这个区域包含了当前运行内核实现的辅助代码版本号。用户空间可以通过读 - 取此版本号以确定特定的辅助代码是否存在。 - -使用范例: - -#define __kuser_helper_version (*(int32_t *)0xffff0ffc) - -void check_kuser_version(void) -{ - if (__kuser_helper_version < 2) { - fprintf(stderr, "can't do atomic operations, kernel too old\n"); - abort(); - } -} - -注意: - - 用户空间可以假设这个域的值不会在任何单个进程的生存期内改变。也就 - 是说，这个域可以仅在库的初始化阶段或进程启动阶段读取一次。 - -kuser_get_tls -------------- - -位置: 0xffff0fe0 - -参考原型: - - void * __kuser_get_tls(void); - -输入: - - lr = 返回地址 - -输出: - - r0 = TLS 值 - -被篡改的寄存器: - - 无 - -定义: - - 获取之前通过 __ARM_NR_set_tls 系统调用设置的 TLS 值。 - -使用范例: - -typedef void * (__kuser_get_tls_t)(void); -#define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0) - -void foo() -{ - void *tls = __kuser_get_tls(); - printf("TLS = %p\n", tls); -} - -注意: - - - 仅在 __kuser_helper_version >= 1 时，此辅助代码存在 - （从内核版本 2.6.12 开始）。 - -kuser_cmpxchg -------------- - -位置: 0xffff0fc0 - -参考原型: - - int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr); - -输入: - - r0 = oldval - r1 = newval - r2 = ptr - lr = 返回地址 - -输出: - - r0 = 成功代码 (零或非零) - C flag = 如果 r0 == 0 则置 1，如果 r0 != 0 则清零。 - -被篡改的寄存器: - - r3, ip, flags - -定义: - - 仅在 *ptr 为 oldval 时原子保存 newval 于 *ptr 中。 - 如果 *ptr 被改变，则返回值为零，否则为非零值。 - 如果 *ptr 被改变，则 C flag 也会被置 1，以实现调用代码中的汇编 - 优化。 - -使用范例: - -typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr); -#define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0) - -int atomic_add(volatile int *ptr, int val) -{ - int old, new; - - do { - old = *ptr; - new = old + val; - } while(__kuser_cmpxchg(old, new, ptr)); - - return new; -} - -注意: - - - 这个例程已根据需要包含了内存屏障。 - - - 仅在 __kuser_helper_version >= 2 时，此辅助代码存在 - （从内核版本 2.6.12 开始）。 - -kuser_memory_barrier --------------------- - -位置: 0xffff0fa0 - -参考原型: - - void __kuser_memory_barrier(void); - -输入: - - lr = 返回地址 - -输出: - - 无 - -被篡改的寄存器: - - 无 - -定义: - - 应用于任何需要内存屏障以防止手动数据修改带来的一致性问题，以及 - __kuser_cmpxchg 中。 - -使用范例: - -typedef void (__kuser_dmb_t)(void); -#define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) - -注意: - - - 仅在 __kuser_helper_version >= 3 时，此辅助代码存在 - （从内核版本 2.6.15 开始）。 - -kuser_cmpxchg64 ---------------- - -位置: 0xffff0f60 - -参考原型: - - int __kuser_cmpxchg64(const int64_t *oldval, - const int64_t *newval, - volatile int64_t *ptr); - -输入: - - r0 = 指向 oldval - r1 = 指向 newval - r2 = 指向目标值 - lr = 返回地址 - -输出: - - r0 = 成功代码 (零或非零) - C flag = 如果 r0 == 0 则置 1，如果 r0 != 0 则清零。 - -被篡改的寄存器: - - r3, lr, flags - -定义: - - 仅在 *ptr 等于 *oldval 指向的 64 位值时，原子保存 *newval - 指向的 64 位值于 *ptr 中。如果 *ptr 被改变，则返回值为零， - 否则为非零值。 - - 如果 *ptr 被改变，则 C flag 也会被置 1，以实现调用代码中的汇编 - 优化。 - -使用范例: - -typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval, - const int64_t *newval, - volatile int64_t *ptr); -#define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60) - -int64_t atomic_add64(volatile int64_t *ptr, int64_t val) -{ - int64_t old, new; - - do { - old = *ptr; - new = old + val; - } while(__kuser_cmpxchg64(&old, &new, ptr)); - - return new; -} - -注意: - - - 这个例程已根据需要包含了内存屏障。 - - - 由于这个过程的代码长度（此辅助代码跨越 2 个常规的 kuser “槽”）， - 因此 0xffff0f80 不被作为有效的入口点。 - - - 仅在 __kuser_helper_version >= 5 时，此辅助代码存在 - （从内核版本 3.1 开始）。 -- cgit