Skip to contentSkip to conversation

docs/zh_CN: add core-api Memory management translation

PATCH Superseded Yanteng Si 3 participants 9 messages Sep 4, 2021 – Sep 15, 2021

Subsystems (2)

v5 of 6 Superseded Latest is v6 →

lore
Share & tools
lore

Yanteng Si

author
#0 lore raw

v5 cover docs/zh_CN: add core-api Memory management translation

v5:

* resent to linux-doc list.

v4:

* pick Alex's Reviewed-by tag.
* Modified some words under Alex's advices.

v3:

* Modified some words under Jiaxun's advices.[PATCH 5/6]

v2:

* Modified some words under Alex's advices;Many thanks to alex for his review, which kept him busy until the early hours of the morning.Thank you!

* add 校译者(proofreading) sign.If you don't want me to do this, please let me know.

Yanteng Si (6):
docs/zh_CN: add core-api memory-allocation translation docs/zh_CN: add core-api unaligned-memory-access translation docs/zh_CN: add core-api mm-api translation docs/zh_CN: add core-api genalloc translation docs/zh_CN: add core-api boot-time-mm translation docs/zh_CN: add core-api gfp_mask-from-fs-io translation

 .../zh_CN/core-api/boot-time-mm.rst           |  49 ++++
 .../translations/zh_CN/core-api/genalloc.rst  | 109 +++++++++
 .../zh_CN/core-api/gfp_mask-from-fs-io.rst    |  66 +++++
 .../translations/zh_CN/core-api/index.rst     |  14 +-
 .../zh_CN/core-api/memory-allocation.rst      | 138 +++++++++++
 .../translations/zh_CN/core-api/mm-api.rst    | 110 +++++++++
 .../core-api/unaligned-memory-access.rst      | 229 ++++++++++++++++++
 7 files changed, 710 insertions(+), 5 deletions(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/boot-time-mm.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/genalloc.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/gfp_mask-from-fs-io.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/memory-allocation.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/mm-api.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/unaligned-memory-access.rst
Signature · 1 line
2.27.0
author
#1 lore raw

PATCH v5 1/6 docs/zh_CN: add core-api memory-allocation translation

Translate Documentation/core-api/memory-allocation.rst into Chinese.

---
 .../translations/zh_CN/core-api/index.rst     |   6 +-
 .../zh_CN/core-api/memory-allocation.rst      | 138 ++++++++++++++++++
 2 files changed, 143 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/memory-allocation.rst
Documentation/translations/zh_CN/core-api/index.rst +5 -1
index d5e947d8b6f1..e011484941d2 100644
@@ -99,9 +99,13 @@ Todolist:
 如何在内核中分配和使用内存。请注意,在
 :doc:`/vm/index` 中有更多的内存管理文档。
 
-Todolist:
+.. toctree::
+   :maxdepth: 1
 
    memory-allocation
+
+Todolist:
+
    unaligned-memory-access
    dma-api
    dma-api-howto
Documentation/translations/zh_CN/core-api/memory-allocation.rst new file +138 -0

138 lines not on this page · raw message

Signature · 1 line
2.27.0
author
#2 lore raw

PATCH v5 2/6 docs/zh_CN: add core-api unaligned-memory-access translation

In reply to Yanteng Si

Translate Documentation/core-api/unaligned-memory-access.rst into Chinese.

---
 .../translations/zh_CN/core-api/index.rst     |   2 +-
 .../core-api/unaligned-memory-access.rst      | 229 ++++++++++++++++++
 2 files changed, 230 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/unaligned-memory-access.rst
Documentation/translations/zh_CN/core-api/index.rst +1 -1
index e011484941d2..0e74e27773ea 100644
@@ -103,10 +103,10 @@ Todolist:
    :maxdepth: 1
 
    memory-allocation
+   unaligned-memory-access
 
 Todolist:
 
-   unaligned-memory-access
    dma-api
    dma-api-howto
    dma-attributes
Documentation/translations/zh_CN/core-api/unaligned-memory-access.rst new file +229 -0

229 lines not on this page · raw message

Signature · 1 line
2.27.0
author
#3 lore raw

PATCH v5 3/6 docs/zh_CN: add core-api mm-api translation

In reply to Yanteng Si

Translate Documentation/core-api/mm-api.rst into Chinese.

---
 .../translations/zh_CN/core-api/index.rst     |   2 +-
 .../translations/zh_CN/core-api/mm-api.rst    | 110 ++++++++++++++++++
 2 files changed, 111 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/mm-api.rst
Documentation/translations/zh_CN/core-api/index.rst +1 -1
index 0e74e27773ea..87603d301b7a 100644
@@ -104,6 +104,7 @@ Todolist:
 
    memory-allocation
    unaligned-memory-access
+   mm-api
 
 Todolist:
 
@@ -111,7 +112,6 @@ Todolist:
    dma-api-howto
    dma-attributes
    dma-isa-lpc
-   mm-api
    genalloc
    pin_user_pages
    boot-time-mm
Documentation/translations/zh_CN/core-api/mm-api.rst new file +110 -0

110 lines not on this page · raw message

Signature · 1 line
2.27.0
author
#4 lore raw

PATCH v5 4/6 docs/zh_CN: add core-api genalloc translation

In reply to Yanteng Si

Translate Documentation/core-api/genalloc.rst into Chinese.

---
 .../translations/zh_CN/core-api/genalloc.rst  | 109 ++++++++++++++++++
 .../translations/zh_CN/core-api/index.rst     |   2 +-
 2 files changed, 110 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/genalloc.rst
Documentation/translations/zh_CN/core-api/genalloc.rst new file +109 -0
new file mode 100644
index 000000000000..3c78452aaa7c
@@ -0,0 +1,109 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/genalloc.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <[email protected]>
+
+:校译:
+
+ 时奎亮 <[email protected]>
+
+.. _cn_core-api_genalloc:
+
+genalloc/genpool子系统
+======================
+
+内核中有许多内存分配子系统,每一个都是针对特定的需求。然而,有时候,内核开发者需
+要为特定范围的特殊用途的内存实现一个新的分配器;通常这个内存位于某个设备上。该设
+备的驱动程序的作者当然可以写一个小的分配器来完成工作,但这是让内核充满几十个测试
+差劲的分配器的方法。早在2005年,Jes Sorensen从sym53c8xx_2驱动中提取了其中的一
+个分配器,并将其作为一个通用模块发布,用于创建特设的内存分配器。这段代码在2.6.13
+版本中被合并;此后它被大大地修改了。
+
+.. _posted: https://lwn.net/Articles/125842/
+
+使用这个分配器的代码应该包括<linux/genalloc.h>。这个动作从创建一个池开始,使用
+一个:
+
+该API在以下内核代码中:
+
+lib/genalloc.c
+
+对gen_pool_create()的调用将创建一个内存池。分配的粒度由min_alloc_order设置;它
+是一个log-base-2(以2为底的对数)的数字,就像页面分配器使用的数字一样,但它指的是
+字节而不是页面。因此,如果min_alloc_order被传递为3,那么所有的分配将是8字节的倍数。
+增加min_alloc_order可以减少跟踪池中内存所需的内存。nid参数指定哪一个NUMA节点应该被
+用于分配管家结构体;如果调用者不关心,它可以是-1。
+
+“管理的”接口devm_gen_pool_create()将内存池与一个特定的设备联系起来。在其他方面,
+当给定的设备被销毁时,它将自动清理内存池。
+
+一个内存池池被关闭的方法是:
+
+该API在以下内核代码中:
+
+lib/genalloc.c
+
+值得注意的是,如果在给定的内存池中仍有未完成的分配,这个函数将采取相当极端的步骤,调用
+BUG(),使整个系统崩溃。你已经被警告了。
+
+一个新创建的内存池没有内存可以分配。在这种状态下,它是相当无用的,所以首要任务之一通常
+是向内存池里添加内存。这可以通过以下方式完成:
+
+该API在以下内核代码中:
+
+include/linux/genalloc.h
+
+lib/genalloc.c
+
+对gen_pool_add()的调用将把从地址(在内核的虚拟地址空间)开始的内存的大小字节放入
+给定的池中,再次使用nid作为节点ID进行辅助内存分配。gen_pool_add_virt()变体将显式
+物理地址与内存联系起来;只有在内存池被用于DMA分配时,这才是必要的。
+
+从内存池中分配内存(并将其放回)的函数是:
+
+该API在以下内核代码中:
+
+include/linux/genalloc.h
+
+lib/genalloc.c
+
+正如人们所期望的,gen_pool_alloc()将从给定的池中分配size<字节。gen_pool_dma_alloc()
+变量分配内存用于DMA操作,返回dma所指向的空间中的相关物理地址。这只有在内存是用
+gen_pool_add_virt()添加的情况下才会起作用。请注意,这个函数偏离了genpool通常使用
+无符号长值来表示内核地址的模式;它返回一个void * 来代替。
+
+这一切看起来都比较简单;事实上,一些开发者显然认为这太简单了。毕竟,上面的接口没有提
+供对分配函数如何选择返回哪块特定内存的控制。如果需要这样的控制,下面的函数将是有意义
+的:
+
+该API在以下内核代码中:
+
+lib/genalloc.c
+
+使用gen_pool_alloc_algo()进行的分配指定了一种用于选择要分配的内存的算法;默认算法可
+以用gen_pool_set_algo()来设置。数据值被传递给算法;大多数算法会忽略它,但偶尔也会需
+要它。当然,人们可以写一个特殊用途的算法,但是已经有一套公平的算法可用了:
+
+- gen_pool_first_fit是一个简单的初配分配器;如果没有指定其他算法,这是默认算法。
+
+- gen_pool_first_fit_align强迫分配有一个特定的对齐方式(通过genpool_data_align结
+  构中的数据传递)。
+
+- gen_pool_first_fit_order_align 按照大小的顺序排列分配。例如,一个60字节的分配将
+  以64字节对齐。
+
+- gen_pool_best_fit,正如人们所期望的,是一个简单的最佳匹配分配器。
+
+- gen_pool_fixed_alloc在池中的一个特定偏移量(通过数据参数在genpool_data_fixed结
+  构中传递)进行分配。如果指定的内存不可用,则分配失败。
+
+还有一些其他的函数,主要是为了查询内存池中的可用空间或迭代内存块等目的。然而,大多数
+用户应该不需要以上描述的功能。如果幸运的话,对这个模块的广泛认识将有助于防止在未来编
+写特殊用途的内存分配器。
+
+该API在以下内核代码中:
+
+lib/genalloc.c
Documentation/translations/zh_CN/core-api/index.rst +1 -1
index 87603d301b7a..88f11c3945a0 100644
@@ -105,6 +105,7 @@ Todolist:
    memory-allocation
    unaligned-memory-access
    mm-api
+   genalloc
 
 Todolist:
 
@@ -112,7 +113,6 @@ Todolist:
    dma-api-howto
    dma-attributes
    dma-isa-lpc
-   genalloc
    pin_user_pages
    boot-time-mm
    gfp_mask-from-fs-io
Signature · 1 line
2.27.0
author
#5 lore raw

PATCH v5 5/6 docs/zh_CN: add core-api boot-time-mm translation

In reply to Yanteng Si

Translate Documentation/core-api/boot-time-mm.rst into Chinese.

---
 .../zh_CN/core-api/boot-time-mm.rst           | 49 +++++++++++++++++++
 .../translations/zh_CN/core-api/index.rst     |  2 +-
 2 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/boot-time-mm.rst
Documentation/translations/zh_CN/core-api/boot-time-mm.rst new file +49 -0
new file mode 100644
index 000000000000..9e81dbec71f8
@@ -0,0 +1,49 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/boot-time-mm.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <[email protected]>
+
+:校译:
+
+ 时奎亮 <[email protected]>
+
+.. _cn_core-api_boot-time-mm:
+
+================
+启动时的内存管理
+================
+
+系统初始化早期“正常”的内存管理由于没有设置完毕无法使用。但是内核仍然需要
+为各种数据结构分配内存,例如物理页分配器。
+
+一个叫做 ``memblock`` 的专用分配器执行启动时的内存管理。特定架构的初始化
+必须在setup_arch()中设置它,并在mem_init()函数中移除它。
+
+一旦早期的内存管理可用,它就为内存分配提供了各种函数和宏。分配请求可以指向
+第一个(也可能是唯一的)节点或NUMA系统中的某个特定节点。有一些API变体在分
+配失败时panic,也有一些不会panic的。
+
+Memblock还提供了各种控制其自身行为的API。
+
+Memblock概述
+============
+
+该API在以下内核代码中:
+
+mm/memblock.c
+
+
+函数和结构体
+============
+
+下面是关于memblock数据结构、函数和宏的描述。其中一些实际上是内部的,但由于
+它们被记录下来,漏掉它们是很愚蠢的。此外,阅读内部函数的注释可以帮助理解引
+擎盖下真正发生的事情。
+
+该API在以下内核代码中:
+
+include/linux/memblock.h
+mm/memblock.c
Documentation/translations/zh_CN/core-api/index.rst +1 -1
index 88f11c3945a0..3f8a86716ac1 100644
@@ -106,6 +106,7 @@ Todolist:
    unaligned-memory-access
    mm-api
    genalloc
+   boot-time-mm
 
 Todolist:
 
@@ -114,7 +115,6 @@ Todolist:
    dma-attributes
    dma-isa-lpc
    pin_user_pages
-   boot-time-mm
    gfp_mask-from-fs-io
 
 内核调试的接口
Signature · 1 line
2.27.0
author
#6 lore raw

PATCH v5 6/6 docs/zh_CN: add core-api gfp_mask-from-fs-io translation

In reply to Yanteng Si

Translate Documentation/core-api/gfp_mask-from-fs-io.rst into Chinese.

---
 .../zh_CN/core-api/gfp_mask-from-fs-io.rst    | 66 +++++++++++++++++++
 .../translations/zh_CN/core-api/index.rst     |  2 +-
 2 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/gfp_mask-from-fs-io.rst
Documentation/translations/zh_CN/core-api/gfp_mask-from-fs-io.rst new file +66 -0
new file mode 100644
index 000000000000..75d2997e9bc3
@@ -0,0 +1,66 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/gfp_mask-from-fs-io.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <[email protected]>
+
+:校译:
+
+ 时奎亮 <[email protected]>
+
+.. _cn_core-api_gfp_mask-from-fs-io:
+
+============================
+从FS/IO上下文中使用的GFP掩码
+============================
+
+:日期: 2018年5月
+:作者: Michal Hocko <[email protected]>
+
+简介
+====
+
+文件系统和IO栈中的代码路径在分配内存时必须小心,以防止因直接调用FS或IO路径的内
+存回收和阻塞已经持有的资源(例如锁--最常见的是用于事务上下文的锁)而造成递归死
+锁。
+
+避免这种死锁问题的传统方法是在调用分配器时,在gfp掩码中清除__GFP_FS和__GFP_IO
+(注意后者意味着也要清除第一个)。GFP_NOFS和GFP_NOIO可以作为快捷方式使用。但事
+实证明,上述方法导致了滥用,当限制性的gfp掩码被用于“万一”时,没有更深入的考虑,
+这导致了问题,因为过度使用GFP_NOFS/GFP_NOIO会导致内存过度回收或其他内存回收的问
+题。
+
+新API
+=====
+
+从4.12开始,我们为NOFS和NOIO上下文提供了一个通用的作用域API,分别是
+``memalloc_nofs_save`` , ``memalloc_nofs_restore`` 和 ``memalloc_noio_save`` ,
+``memalloc_noio_restore`` ,允许从文件系统或I/O的角度将一个作用域标记为一个
+关键部分。从该作用域的任何分配都将从给定的掩码中删除__GFP_FS和__GFP_IO,所以
+没有内存分配可以追溯到FS/IO中。
+
+
+该API在以下内核代码中:
+
+include/linux/sched/mm.h
+
+然后,FS/IO代码在任何与回收有关的关键部分开始之前简单地调用适当的保存函数
+——例如,与回收上下文共享的锁或当事务上下文嵌套可能通过回收进行时。恢复函数
+应该在关键部分结束时被调用。所有这一切最好都伴随着解释什么是回收上下文,以
+方便维护。
+
+请注意,保存/恢复函数的正确配对允许嵌套,所以从现有的NOIO或NOFS范围分别调
+用 ``memalloc_noio_save`` 或 ``memalloc_noio_restore`` 是安全的。
+
+那么__vmalloc(GFP_NOFS)呢?
+===========================
+
+vmalloc不支持GFP_NOFS语义,因为在分配器的深处有硬编码的GFP_KERNEL分配,要修
+复这些分配是相当不容易的。这意味着用GFP_NOFS/GFP_NOIO调用 ``vmalloc`` 几乎
+总是一个错误。好消息是,NOFS/NOIO语义可以通过范围API实现。
+
+在理想的世界中,上层应该已经标记了危险的上下文,因此不需要特别的照顾, ``vmalloc``
+的调用应该没有任何问题。有时,如果上下文不是很清楚,或者有叠加的违规行为,那么
+推荐的方法是用范围API包装vmalloc,并加上注释来解释问题。
Documentation/translations/zh_CN/core-api/index.rst +1 -1
index 3f8a86716ac1..52bda404f9e4 100644
@@ -107,6 +107,7 @@ Todolist:
    mm-api
    genalloc
    boot-time-mm
+   gfp_mask-from-fs-io
 
 Todolist:
 
@@ -115,7 +116,6 @@ Todolist:
    dma-attributes
    dma-isa-lpc
    pin_user_pages
-   gfp_mask-from-fs-io
 
 内核调试的接口
 ==============
Signature · 1 line
2.27.0
maintainer
#7 lore raw
In reply to Yanteng Si
Quoted 28 lines · Yanteng Si

v5:

* resent to linux-doc list.

v4:

* pick Alex's Reviewed-by tag.
* Modified some words under Alex's advices.

v3:

* Modified some words under Jiaxun's advices.[PATCH 5/6]

v2:

* Modified some words under Alex's advices;Many thanks to alex for his review, which kept him busy until the early hours of the morning.Thank you!

* add 校译者(proofreading) sign.If you don't want me to do this, please let me know.

Yanteng Si (6):
docs/zh_CN: add core-api memory-allocation translation docs/zh_CN: add core-api unaligned-memory-access translation docs/zh_CN: add core-api mm-api translation docs/zh_CN: add core-api genalloc translation docs/zh_CN: add core-api boot-time-mm translation docs/zh_CN: add core-api gfp_mask-from-fs-io translation

Quoted 14 lines
 .../zh_CN/core-api/boot-time-mm.rst           |  49 ++++
 .../translations/zh_CN/core-api/genalloc.rst  | 109 +++++++++
 .../zh_CN/core-api/gfp_mask-from-fs-io.rst    |  66 +++++
 .../translations/zh_CN/core-api/index.rst     |  14 +-
 .../zh_CN/core-api/memory-allocation.rst      | 138 +++++++++++
 .../translations/zh_CN/core-api/mm-api.rst    | 110 +++++++++
 .../core-api/unaligned-memory-access.rst      | 229 ++++++++++++++++++
 7 files changed, 710 insertions(+), 5 deletions(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/boot-time-mm.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/genalloc.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/gfp_mask-from-fs-io.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/memory-allocation.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/mm-api.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/unaligned-memory-access.rst

This set adds a new warning:

Documentation/translations/zh_CN/core-api/mm-api.rst:35: WARNING: duplicate label mm-api-gfp-flags, other instance in /stuff/k/git/kernel/Documentation/core-api/mm-api.rst

Please fix this and resubmit (and please always test the docs build before submitting patches!)

Thanks,

jon

#8 lore raw
Quoted 46 lines · Jonathan Corbet <[email protected]> 于2021年9月15日周三 上午4:58写道:
Quoted 28 lines · Yanteng Si

v5:

* resent to linux-doc list.

v4:

* pick Alex's Reviewed-by tag.
* Modified some words under Alex's advices.

v3:

* Modified some words under Jiaxun's advices.[PATCH 5/6]

v2:

* Modified some words under Alex's advices;Many thanks to alex for his review, which kept him busy until the early hours of the morning.Thank you!

* add 校译者(proofreading) sign.If you don't want me to do this, please let me know.

Yanteng Si (6):
docs/zh_CN: add core-api memory-allocation translation docs/zh_CN: add core-api unaligned-memory-access translation docs/zh_CN: add core-api mm-api translation docs/zh_CN: add core-api genalloc translation docs/zh_CN: add core-api boot-time-mm translation docs/zh_CN: add core-api gfp_mask-from-fs-io translation

Quoted 14 lines
 .../zh_CN/core-api/boot-time-mm.rst           |  49 ++++
 .../translations/zh_CN/core-api/genalloc.rst  | 109 +++++++++
 .../zh_CN/core-api/gfp_mask-from-fs-io.rst    |  66 +++++
 .../translations/zh_CN/core-api/index.rst     |  14 +-
 .../zh_CN/core-api/memory-allocation.rst      | 138 +++++++++++
 .../translations/zh_CN/core-api/mm-api.rst    | 110 +++++++++
 .../core-api/unaligned-memory-access.rst      | 229 ++++++++++++++++++
 7 files changed, 710 insertions(+), 5 deletions(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/boot-time-mm.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/genalloc.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/gfp_mask-from-fs-io.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/memory-allocation.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/mm-api.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/unaligned-memory-access.rst
Quoted 6 lines

This set adds a new warning:

Documentation/translations/zh_CN/core-api/mm-api.rst:35: WARNING: duplicate label mm-api-gfp-flags, other instance in /stuff/k/git/kernel/Documentation/core-api/mm-api.rst

Please fix this and resubmit (and please always test the docs build before submitting patches!)

Dear jon

Sorry, this is my fault。
I test it every time, and strangely enough I don't get this warning, but the tag is obviously unreasonable because the same tag already exists in the original document.
I will fix it.

Thanks,

Yanteng