* [PATCH v6 1/6] docs/zh_CN: add core-api memory-allocation translation
2021-09-17 6:33 [PATCH v6 0/6] docs/zh_CN: add core-api Memory management translation Yanteng Si
@ 2021-09-17 6:33 ` Yanteng Si
2021-09-17 6:33 ` [PATCH v6 2/6] docs/zh_CN: add core-api unaligned-memory-access translation Yanteng Si
` (5 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Yanteng Si @ 2021-09-17 6:33 UTC (permalink / raw)
To: corbet, alexs, seakeel
Cc: Yanteng Si, chenhuacai, jiaxun.yang, linux-doc, realpuyuwang,
siyanteng01
Translate Documentation/core-api/memory-allocation.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
---
.../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
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index 72f0a36daa1c..f07bd9cc1e4b 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -101,9 +101,13 @@ Todolist:
如何在内核中分配和使用内存。请注意，在
:doc:`/vm/index` 中有更多的内存管理文档。
-Todolist:
+.. toctree::
+ :maxdepth: 1
memory-allocation
+
+Todolist:
+
unaligned-memory-access
dma-api
dma-api-howto
diff --git a/Documentation/translations/zh_CN/core-api/memory-allocation.rst b/Documentation/translations/zh_CN/core-api/memory-allocation.rst
new file mode 100644
index 000000000000..e17b87dfd1c8
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/memory-allocation.rst
@@ -0,0 +1,138 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/memory-allocation.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+ 时奎亮 <alexs@kernel.org>
+
+.. _cn_core-api_memory-allocation:
+
+============
+内存分配指南
+============
+
+Linux为内存分配提供了多种API。你可以使用 `kmalloc` 或 `kmem_cache_alloc`
+系列分配小块内存，使用 `vmalloc` 及其派生产品分配大的几乎连续的区域，或者
+你可以用 alloc_pages 直接向页面分配器请求页面。也可以使用更专业的分配器，
+例如 `cma_alloc` 或 `zs_malloc` 。
+
+大多数的内存分配API使用GFP标志来表达该内存应该如何分配。GFP的缩写代表
+“(get free pages)获取空闲页”，是底层的内存分配功能。
+
+（内存）分配API的多样性与众多的GFP标志相结合，使得“我应该如何分配内存？”这个问
+题不那么容易回答，尽管很可能你应该使用
+
+::
+
+ kzalloc(<size>, GFP_KERNEL);
+
+当然，有些情况下必须使用其他分配API和不同的GFP标志。
+
+获取空闲页标志
+==============
+GFP标志控制分配器的行为。它们告诉我们哪些内存区域可以被使用，分配器应该多努力寻
+找空闲的内存，这些内存是否可以被用户空间访问等等。内存管理API为GFP标志和它们的
+组合提供了参考文件，这里我们简要介绍一下它们的推荐用法:
+
+ * 大多数时候， ``GFP_KERNEL`` 是你需要的。内核数据结构的内存，DMA可用内存，inode
+ 缓存，所有这些和其他许多分配类型都可以使用 ``GFP_KERNEL`` 。注意，使用 ``GFP_KERNEL``
+ 意味着 ``GFP_RECLAIM`` ，这意味着在有内存压力的情况下可能会触发直接回收；调用上
+ 下文必须允许睡眠。
+
+ * 如果分配是从一个原子上下文中进行的，例如中断处理程序，使用 ``GFP_NOWAIT`` 。这个
+ 标志可以防止直接回收和IO或文件系统操作。因此，在内存压力下， ``GFP_NOWAIT`` 分配
+ 可能会失败。有合理退路的分配应该使用 ``GFP_NOWARN`` 。
+
+ * 如果你认为访问保留内存区是合理的，并且除非分配成功，否则内核会有压力，你可以使用 ``GFP_ATOMIC`` 。
+
+ * 从用户空间触发的不可信任的分配应该是kmem核算的对象，必须设置 ``__GFP_ACCOUNT`` 位。
+ 有一个方便的用于 ``GFP_KERNEL`` 分配的 ``GFP_KERNEL_ACCOUNT`` 快捷键，其应该被核
+ 算。
+
+ * 用户空间的分配应该使用 ``GFP_USER`` 、 ``GFP_HIGHUSER`` 或 ``GFP_HIGHUSER_MOVABLE``
+ 中的一个标志。标志名称越长，限制性越小。
+
+ ``GFP_HIGHUSER_MOVABLE`` 不要求分配的内存将被内核直接访问，并意味着数据是可迁移的。
+
+ ``GFP_HIGHUSER`` 意味着所分配的内存是不可迁移的，但也不要求它能被内核直接访问。举个
+ 例子就是一个硬件分配内存，这些数据直接映射到用户空间，但没有寻址限制。
+
+ ``GFP_USER`` 意味着分配的内存是不可迁移的，它必须被内核直接访问。
+
+你可能会注意到，在现有的代码中，有相当多的分配指定了 ``GFP_NOIO`` 或 ``GFP_NOFS`` 。
+从历史上看，它们被用来防止递归死锁，这种死锁是由直接内存回收调用到FS或IO路径以及对已
+经持有的资源进行阻塞引起的。从4.12开始，解决这个问题的首选方法是使用新的范围API，即
+:ref:`Documentation/core-api/gfp_mask-from-fs-io.rst <gfp_mask_from_fs_io>`.
+
+其他传统的GFP标志是 ``GFP_DMA`` 和 ``GFP_DMA32`` 。它们用于确保分配的内存可以被寻
+址能力有限的硬件访问。因此，除非你正在为一个有这种限制的设备编写驱动程序，否则要避免
+使用这些标志。而且，即使是有限制的硬件，也最好使用dma_alloc* APIs。
+
+GFP标志和回收行为
+-----------------
+内存分配可能会触发直接或后台回收，了解页面分配器将如何努力满足该请求或其他请求是非常
+有用的。
+
+ * ``GFP_KERNEL & ~__GFP_RECLAIM`` - 乐观分配，完全不尝试释放内存。最轻量级的模
+ 式，甚至不启动后台回收。应该小心使用，因为它可能会耗尽内存，而下一个用户可能会启
+ 动更积极的回收。
+
+ * ``GFP_KERNEL & ~__GFP_DIRECT_RECLAIM`` (or ``GFP_NOWAIT`` ) - 乐观分配，不
+ 试图从当前上下文中释放内存，但如果该区域低于低水位，可以唤醒kswapd来回收内存。可
+ 以从原子上下文中使用，或者当请求是一个性能优化，并且有另一个慢速路径的回退。
+
+ * ``(GFP_KERNEL|__GFP_HIGH) & ~__GFP_DIRECT_RECLAIM`` (aka ``GFP_ATOMIC`` ) - 非
+ 睡眠分配，有一个昂贵的回退，所以它可以访问某些部分的内存储备。通常从中断/底层上下
+ 文中使用，有一个昂贵的慢速路径回退。
+
+ * ``GFP_KERNEL`` - 允许后台和直接回收，并使用默认的页面分配器行为。这意味着廉价
+ 的分配请求基本上是不会失败的，但不能保证这种行为，所以失败必须由调用者适当检查（例
+ 如，目前允许OOM杀手失败）。
+
+ * ``GFP_KERNEL | __GFP_NORETRY`` - 覆盖默认的分配器行为，所有的分配请求都会提前
+ 失败，而不是导致破坏性的回收（在这个实现中是一轮的回收）。OOM杀手不被调用。
+
+ * ``GFP_KERNEL | __GFP_RETRY_MAYFAIL`` - 覆盖 **默认** 的分配器行为，所有分配请求都非
+ 常努力。如果回收不能取得任何进展，该请求将失败。OOM杀手不会被触发。
+
+ * ``GFP_KERNEL | __GFP_NOFAIL`` - 覆盖默认的分配器行为，所有分配请求将无休止地循
+ 环，直到成功。这可能真的很危险，特别是对于较大的需求。
+
+选择内存分配器
+==============
+
+分配内存的最直接的方法是使用kmalloc()系列的函数。而且，为了安全起见，最好使用将内存
+设置为零的例程，如kzalloc()。如果你需要为一个数组分配内存，有kmalloc_array()和kcalloc()
+辅助程序。辅助程序struct_size()、array_size()和array3_size()可以用来安全地计算对
+象的大小而不会溢出。
+
+可以用 `kmalloc` 分配的块的最大尺寸是有限的。实际的限制取决于硬件和内核配置，但是对于
+小于页面大小的对象，使用 `kmalloc` 是一个好的做法。
+
+用 `kmalloc` 分配的块的地址至少要对齐到ARCH_KMALLOC_MINALIGN字节。对于2的幂的大小，
+对齐方式也被保证为至少是各自的大小。
+
+用kmalloc()分配的块可以用krealloc()调整大小。与kmalloc_array()类似：以krealloc_array()
+的形式提供了一个用于调整数组大小的辅助工具。
+
+对于大量的分配，你可以使用vmalloc()和vzalloc()，或者直接向页面分配器请求页面。由vmalloc
+和相关函数分配的内存在物理上是不连续的。
+
+如果你不确定分配的大小对 `kmalloc` 来说是否太大，可以使用kvmalloc()及其派生函数。它将尝
+试用kmalloc分配内存，如果分配失败，将用 `vmalloc` 重新尝试。对于哪些GFP标志可以与 `kvmalloc`
+一起使用是有限制的；请看kvmalloc_node()参考文档。注意， `kvmalloc` 可能会返回物理上不连
+续的内存。
+
+如果你需要分配许多相同的对象，你可以使用slab缓存分配器。在使用缓存之前，应该用
+kmem_cache_create()或kmem_cache_create_usercopy()来设置缓存。如果缓存的一部分可能被复
+制到用户空间，应该使用第二个函数。在缓存被创建后，kmem_cache_alloc()和它的封装可以从该缓
+存中分配内存。
+
+当分配的内存不再需要时，它必须被释放。你可以使用kvfree()来处理用 `kmalloc` 、 `vmalloc`
+和 `kvmalloc` 分配的内存。slab缓存应该用kmem_cache_free()来释放。不要忘记用
+kmem_cache_destroy()来销毁缓存。
--
2.27.0
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v6 2/6] docs/zh_CN: add core-api unaligned-memory-access translation
2021-09-17 6:33 [PATCH v6 0/6] docs/zh_CN: add core-api Memory management translation Yanteng Si
2021-09-17 6:33 ` [PATCH v6 1/6] docs/zh_CN: add core-api memory-allocation translation Yanteng Si
@ 2021-09-17 6:33 ` Yanteng Si
2021-09-17 6:33 ` [PATCH v6 3/6] docs/zh_CN: add core-api mm-api translation Yanteng Si
` (4 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Yanteng Si @ 2021-09-17 6:33 UTC (permalink / raw)
To: corbet, alexs, seakeel
Cc: Yanteng Si, chenhuacai, jiaxun.yang, linux-doc, realpuyuwang,
siyanteng01
Translate Documentation/core-api/unaligned-memory-access.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
---
.../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
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index f07bd9cc1e4b..efc2fdd608ef 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -105,10 +105,10 @@ Todolist:
:maxdepth: 1
memory-allocation
+ unaligned-memory-access
Todolist:
- unaligned-memory-access
dma-api
dma-api-howto
dma-attributes
diff --git a/Documentation/translations/zh_CN/core-api/unaligned-memory-access.rst b/Documentation/translations/zh_CN/core-api/unaligned-memory-access.rst
new file mode 100644
index 000000000000..29c33e7e0855
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/unaligned-memory-access.rst
@@ -0,0 +1,229 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/unaligned-memory-access.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+ 时奎亮 <alexs@kernel.org>
+
+.. _cn_core-api_unaligned-memory-access:
+
+==============
+非对齐内存访问
+==============
+
+:作者: Daniel Drake <dsd@gentoo.org>,
+:作者: Johannes Berg <johannes@sipsolutions.net>
+
+:感谢他们的帮助: Alan Cox, Avuton Olrich, Heikki Orsila, Jan Engelhardt,
+ Kyle McMartin, Kyle Moffett, Randy Dunlap, Robert Hancock, Uli Kunitz,
+ Vadim Lobanov
+
+
+Linux运行在各种各样的架构上，这些架构在内存访问方面有不同的表现。本文介绍了一些
+关于不对齐访问的细节，为什么你需要编写不引起不对齐访问的代码，以及如何编写这样的
+代码
+
+
+非对齐访问的定义
+================
+
+当你试图从一个不被N偶数整除的地址（即addr % N != 0）开始读取N字节的数据时，就
+会发生无对齐内存访问。例如，从地址0x10004读取4个字节的数据是可以的，但从地址
+0x10005读取4个字节的数据将是一个不对齐的内存访问。
+
+上述内容可能看起来有点模糊，因为内存访问可以以不同的方式发生。这里的背景是在机器
+码层面上：某些指令在内存中读取或写入一些字节（例如x86汇编中的movb、movw、movl）。
+正如将变得清晰的那样，相对容易发现那些将编译为多字节内存访问指令的C语句，即在处理
+u16、u32和u64等类型时。
+
+
+自然对齐
+========
+
+上面提到的规则构成了我们所说的自然对齐。当访问N个字节的内存时，基础内存地址必须被
+N平均分割，即addr % N == 0。
+
+在编写代码时，假设目标架构有自然对齐的要求。
+
+在现实中，只有少数架构在所有大小的内存访问上都要求自然对齐。然而，我们必须考虑所
+有支持的架构；编写满足自然对齐要求的代码是实现完全可移植性的最简单方法。
+
+
+为什么非对齐访问时坏事
+======================
+
+执行非对齐内存访问的效果因架构不同而不同。在这里写一整篇关于这些差异的文档是很容
+易的；下面是对常见情况的总结:
+
+ - 一些架构能够透明地执行非对齐内存访问，但通常会有很大的性能代价。
+ - 当不对齐的访问发生时，一些架构会引发处理器异常。异常处理程序能够纠正不对齐的
+ 访问，但要付出很大的性能代价。
+ - 一些架构在发生不对齐访问时，会引发处理器异常，但异常中并没有包含足够的信息来
+ 纠正不对齐访问。
+ - 有些架构不能进行无对齐内存访问，但会默默地执行与请求不同的内存访问，从而导致
+ 难以发现的微妙的代码错误!
+
+从上文可以看出，如果你的代码导致不对齐的内存访问发生，那么你的代码在某些平台上将无
+法正常工作，在其他平台上将导致性能问题。
+
+不会导致非对齐访问的代码
+========================
+
+起初，上面的概念似乎有点难以与实际编码实践联系起来。毕竟，你对某些变量的内存地址没
+有很大的控制权，等等。
+
+幸运的是事情并不复杂，因为在大多数情况下，编译器会确保代码工作正常。例如，以下面的
+结构体为例::
+
+ struct foo {
+ u16 field1;
+ u32 field2;
+ u8 field3;
+ };
+
+让我们假设上述结构体的一个实例驻留在从地址0x10000开始的内存中。根据基本的理解，访问
+field2会导致非对齐访问，这并不是不合理的。你会期望field2位于该结构体的2个字节的偏移
+量，即地址0x10002，但该地址不能被4平均整除（注意，我们在这里读一个4字节的值）。
+
+幸运的是，编译器理解对齐约束，所以在上述情况下，它会在field1和field2之间插入2个字节
+的填充。因此，对于标准的结构体类型，你总是可以依靠编译器来填充结构体，以便对字段的访
+问可以适当地对齐（假设你没有将字段定义不同长度的类型）。
+
+同样，你也可以依靠编译器根据变量类型的大小，将变量和函数参数对齐到一个自然对齐的方案。
+
+在这一点上，应该很清楚，访问单个字节（u8或char）永远不会导致无对齐访问，因为所有的内
+存地址都可以被1均匀地整除。
+
+在一个相关的话题上，考虑到上述因素，你可以观察到，你可以对结构体中的字段进行重新排序，
+以便将字段放在不重排就会插入填充物的地方，从而减少结构体实例的整体常驻内存大小。上述
+例子的最佳布局是::
+
+ struct foo {
+ u32 field2;
+ u16 field1;
+ u8 field3;
+ };
+
+对于一个自然对齐方案，编译器只需要在结构的末尾添加一个字节的填充。添加这种填充是为了满
+足这些结构的数组的对齐约束。
+
+另一点值得一提的是在结构体类型上使用__attribute__((packed))。这个GCC特有的属性告诉编
+译器永远不要在结构体中插入任何填充，当你想用C结构体来表示一些“off the wire”的固定排列
+的数据时，这个属性很有用。
+
+你可能会倾向于认为，在访问不满足架构对齐要求的字段时，使用这个属性很容易导致不对齐的访
+问。然而，编译器也意识到了对齐的限制，并且会产生额外的指令来执行内存访问，以避免造成不
+对齐的访问。当然，与non-packed的情况相比，额外的指令显然会造成性能上的损失，所以packed
+属性应该只在避免结构填充很重要的时候使用。
+
+
+导致非对齐访问的代码
+====================
+
+考虑到上述情况，让我们来看看一个现实生活中可能导致非对齐内存访问的函数的例子。下面这个
+函数取自include/linux/etherdevice.h，是一个优化的例程，用于比较两个以太网MAC地址是否
+相等::
+
+ bool ether_addr_equal(const u8 *addr1, const u8 *addr2)
+ {
+ #ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS
+ u32 fold = ((*(const u32 *)addr1) ^ (*(const u32 *)addr2)) |
+ ((*(const u16 *)(addr1 + 4)) ^ (*(const u16 *)(addr2 + 4)));
+
+ return fold == 0;
+ #else
+ const u16 *a = (const u16 *)addr1;
+ const u16 *b = (const u16 *)addr2;
+ return ((a[0] ^ b[0]) | (a[1] ^ b[1]) | (a[2] ^ b[2])) == 0;
+ #endif
+ }
+
+在上述函数中，当硬件具有高效的非对齐访问能力时，这段代码没有问题。但是当硬件不能在任意
+边界上访问内存时，对a[0]的引用导致从地址addr1开始的2个字节（16位）被读取。
+
+想一想，如果addr1是一个奇怪的地址，如0x10003，会发生什么？(提示：这将是一个非对齐访
+问。)
+
+尽管上述函数存在潜在的非对齐访问问题，但它还是被包含在内核中，但被理解为只在16位对齐
+的地址上正常工作。调用者应该确保这种对齐方式或者根本不使用这个函数。这个不对齐的函数
+仍然是有用的，因为它是在你能确保对齐的情况下的一个很好的优化，这在以太网网络环境中几
+乎是一直如此。
+
+
+下面是另一个可能导致非对齐访问的代码的例子::
+
+ void myfunc(u8 *data, u32 value)
+ {
+ [...]
+ *((u32 *) data) = cpu_to_le32(value);
+ [...]
+ }
+
+每当数据参数指向的地址不被4均匀整除时，这段代码就会导致非对齐访问。
+
+综上所述，你可能遇到非对齐访问问题的两种主要情况包括:
+
+ 1. 将变量定义不同长度的类型
+ 2. 指针运算后访问至少2个字节的数据
+
+
+避免非对齐访问
+==============
+
+避免非对齐访问的最简单方法是使用<asm/unaligned.h>头文件提供的get_unaligned()和
+put_unaligned()宏。
+
+回到前面的一个可能导致非对齐访问的代码例子::
+
+ void myfunc(u8 *data, u32 value)
+ {
+ [...]
+ *((u32 *) data) = cpu_to_le32(value);
+ [...]
+ }
+
+为了避免非对齐的内存访问，你可以将其改写如下::
+
+ void myfunc(u8 *data, u32 value)
+ {
+ [...]
+ value = cpu_to_le32(value);
+ put_unaligned(value, (u32 *) data);
+ [...]
+ }
+
+get_unaligned()宏的工作原理与此类似。假设'data'是一个指向内存的指针，并且你希望避免
+非对齐访问，其用法如下::
+
+ u32 value = get_unaligned((u32 *) data);
+
+这些宏适用于任何长度的内存访问（不仅仅是上面例子中的32位）。请注意，与标准的对齐内存
+访问相比，使用这些宏来访问非对齐内存可能会在性能上付出代价。
+
+如果使用这些宏不方便，另一个选择是使用memcpy()，其中源或目标（或两者）的类型为u8*或
+非对齐char*。由于这种操作的字节性质，避免了非对齐访问。
+
+
+对齐 vs. 网络
+=============
+
+在需要对齐负载的架构上，网络要求IP头在四字节边界上对齐，以优化IP栈。对于普通的以太网
+硬件，常数NET_IP_ALIGN被使用。在大多数架构上，这个常数的值是2，因为正常的以太网头是
+14个字节，所以为了获得适当的对齐，需要DMA到一个可以表示为4*n+2的地址。一个值得注意的
+例外是powerpc，它将NET_IP_ALIGN定义为0，因为DMA到未对齐的地址可能非常昂贵，与未对齐
+的负载的成本相比相形见绌。
+
+对于一些不能DMA到未对齐地址的以太网硬件，如4*n+2或非以太网硬件，这可能是一个问题，这
+时需要将传入的帧复制到一个对齐的缓冲区。因为这在可以进行非对齐访问的架构上是不必要的，
+所以可以使代码依赖于CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS，像这样::
+
+ #ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS
+ skb = original skb
+ #else
+ skb = copy skb
+ #endif
--
2.27.0
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v6 3/6] docs/zh_CN: add core-api mm-api translation
2021-09-17 6:33 [PATCH v6 0/6] docs/zh_CN: add core-api Memory management translation Yanteng Si
2021-09-17 6:33 ` [PATCH v6 1/6] docs/zh_CN: add core-api memory-allocation translation Yanteng Si
2021-09-17 6:33 ` [PATCH v6 2/6] docs/zh_CN: add core-api unaligned-memory-access translation Yanteng Si
@ 2021-09-17 6:33 ` Yanteng Si
2021-09-17 6:33 ` [PATCH v6 4/6] docs/zh_CN: add core-api genalloc translation Yanteng Si
` (3 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Yanteng Si @ 2021-09-17 6:33 UTC (permalink / raw)
To: corbet, alexs, seakeel
Cc: Yanteng Si, chenhuacai, jiaxun.yang, linux-doc, realpuyuwang,
siyanteng01
Translate Documentation/core-api/mm-api.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Reviewed-by: Jiaxun Yang <jiaxun.yang@flygoat.com>
---
.../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
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index efc2fdd608ef..2adf1978f112 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -106,6 +106,7 @@ Todolist:
memory-allocation
unaligned-memory-access
+ mm-api
Todolist:
@@ -113,7 +114,6 @@ Todolist:
dma-api-howto
dma-attributes
dma-isa-lpc
- mm-api
genalloc
pin_user_pages
boot-time-mm
diff --git a/Documentation/translations/zh_CN/core-api/mm-api.rst b/Documentation/translations/zh_CN/core-api/mm-api.rst
new file mode 100644
index 000000000000..0ea43dc67953
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/mm-api.rst
@@ -0,0 +1,110 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/mm-api.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+ 时奎亮<alexs@kernel.org>
+
+.. _cn_core-api_mm-api:
+
+============
+内存管理APIs
+============
+
+API（Application Programming Interface，应用程序接口）
+
+用户空间内存访问
+================
+
+该API在以下内核代码中:
+
+arch/x86/include/asm/uaccess.h
+
+arch/x86/lib/usercopy_32.c
+
+mm/gup.c
+
+.. _cn_mm-api-gfp-flags:
+
+内存分配控制
+============
+
+该API在以下内核代码中:
+
+include/linux/gfp.h
+
+Slab缓存
+========
+
+此缓存非cpu片上缓存，请读者自行查阅资料。
+
+该API在以下内核代码中:
+
+include/linux/slab.h
+
+mm/slab.c
+
+mm/slab_common.c
+
+mm/util.c
+
+虚拟连续（内存页）映射
+======================
+
+该API在以下内核代码中:
+
+mm/vmalloc.c
+
+
+文件映射和页面缓存
+==================
+
+该API在以下内核代码中:
+
+mm/readahead.c
+
+mm/filemap.c
+
+mm/page-writeback.c
+
+mm/truncate.c
+
+include/linux/pagemap.h
+
+内存池
+======
+
+该API在以下内核代码中:
+
+mm/mempool.c
+
+DMA池
+=====
+
+DMA(Direct Memory Access，直接存储器访问)
+
+该API在以下内核代码中:
+
+mm/dmapool.c
+
+更多的内存管理函数
+==================
+
+该API在以下内核代码中:
+
+mm/memory.c
+
+mm/page_alloc.c
+
+mm/mempolicy.c
+
+include/linux/mm_types.h
+
+include/linux/mm.h
+
+include/linux/mmzone.h
--
2.27.0
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v6 4/6] docs/zh_CN: add core-api genalloc translation
2021-09-17 6:33 [PATCH v6 0/6] docs/zh_CN: add core-api Memory management translation Yanteng Si
` (2 preceding siblings ...)
2021-09-17 6:33 ` [PATCH v6 3/6] docs/zh_CN: add core-api mm-api translation Yanteng Si
@ 2021-09-17 6:33 ` Yanteng Si
2021-09-17 6:33 ` [PATCH v6 5/6] docs/zh_CN: add core-api boot-time-mm translation Yanteng Si
` (2 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Yanteng Si @ 2021-09-17 6:33 UTC (permalink / raw)
To: corbet, alexs, seakeel
Cc: Yanteng Si, chenhuacai, jiaxun.yang, linux-doc, realpuyuwang,
siyanteng01
Translate Documentation/core-api/genalloc.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
---
.../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
diff --git a/Documentation/translations/zh_CN/core-api/genalloc.rst b/Documentation/translations/zh_CN/core-api/genalloc.rst
new file mode 100644
index 000000000000..3c78452aaa7c
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/genalloc.rst
@@ -0,0 +1,109 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/genalloc.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+ 时奎亮 <alexs@kernel.org>
+
+.. _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
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index 2adf1978f112..03d1fa23ca24 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -107,6 +107,7 @@ Todolist:
memory-allocation
unaligned-memory-access
mm-api
+ genalloc
Todolist:
@@ -114,7 +115,6 @@ Todolist:
dma-api-howto
dma-attributes
dma-isa-lpc
- genalloc
pin_user_pages
boot-time-mm
gfp_mask-from-fs-io
--
2.27.0
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v6 5/6] docs/zh_CN: add core-api boot-time-mm translation
2021-09-17 6:33 [PATCH v6 0/6] docs/zh_CN: add core-api Memory management translation Yanteng Si
` (3 preceding siblings ...)
2021-09-17 6:33 ` [PATCH v6 4/6] docs/zh_CN: add core-api genalloc translation Yanteng Si
@ 2021-09-17 6:33 ` Yanteng Si
2021-09-17 6:33 ` [PATCH v6 6/6] docs/zh_CN: add core-api gfp_mask-from-fs-io translation Yanteng Si
2021-09-27 17:30 ` [PATCH v6 0/6] docs/zh_CN: add core-api Memory management translation Jonathan Corbet
6 siblings, 0 replies; 8+ messages in thread
From: Yanteng Si @ 2021-09-17 6:33 UTC (permalink / raw)
To: corbet, alexs, seakeel
Cc: Yanteng Si, chenhuacai, jiaxun.yang, linux-doc, realpuyuwang,
siyanteng01
Translate Documentation/core-api/boot-time-mm.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Reviewed-by: Jiaxun Yang <jiaxun.yang@flygoat.com>
---
.../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
diff --git a/Documentation/translations/zh_CN/core-api/boot-time-mm.rst b/Documentation/translations/zh_CN/core-api/boot-time-mm.rst
new file mode 100644
index 000000000000..9e81dbec71f8
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/boot-time-mm.rst
@@ -0,0 +1,49 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/boot-time-mm.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+ 时奎亮 <alexs@kernel.org>
+
+.. _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
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index 03d1fa23ca24..fe624abf1817 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -108,6 +108,7 @@ Todolist:
unaligned-memory-access
mm-api
genalloc
+ boot-time-mm
Todolist:
@@ -116,7 +117,6 @@ Todolist:
dma-attributes
dma-isa-lpc
pin_user_pages
- boot-time-mm
gfp_mask-from-fs-io
内核调试的接口
--
2.27.0
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v6 6/6] docs/zh_CN: add core-api gfp_mask-from-fs-io translation
2021-09-17 6:33 [PATCH v6 0/6] docs/zh_CN: add core-api Memory management translation Yanteng Si
` (4 preceding siblings ...)
2021-09-17 6:33 ` [PATCH v6 5/6] docs/zh_CN: add core-api boot-time-mm translation Yanteng Si
@ 2021-09-17 6:33 ` Yanteng Si
2021-09-27 17:30 ` [PATCH v6 0/6] docs/zh_CN: add core-api Memory management translation Jonathan Corbet
6 siblings, 0 replies; 8+ messages in thread
From: Yanteng Si @ 2021-09-17 6:33 UTC (permalink / raw)
To: corbet, alexs, seakeel
Cc: Yanteng Si, chenhuacai, jiaxun.yang, linux-doc, realpuyuwang,
siyanteng01
Translate Documentation/core-api/gfp_mask-from-fs-io.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
---
.../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
diff --git a/Documentation/translations/zh_CN/core-api/gfp_mask-from-fs-io.rst b/Documentation/translations/zh_CN/core-api/gfp_mask-from-fs-io.rst
new file mode 100644
index 000000000000..75d2997e9bc3
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/gfp_mask-from-fs-io.rst
@@ -0,0 +1,66 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/gfp_mask-from-fs-io.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+ 时奎亮 <alexs@kernel.org>
+
+.. _cn_core-api_gfp_mask-from-fs-io:
+
+============================
+从FS/IO上下文中使用的GFP掩码
+============================
+
+:日期: 2018年5月
+:作者: Michal Hocko <mhocko@kernel.org>
+
+简介
+====
+
+文件系统和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，并加上注释来解释问题。
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index fe624abf1817..ce064df5ca8d 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -109,6 +109,7 @@ Todolist:
mm-api
genalloc
boot-time-mm
+ gfp_mask-from-fs-io
Todolist:
@@ -117,7 +118,6 @@ Todolist:
dma-attributes
dma-isa-lpc
pin_user_pages
- gfp_mask-from-fs-io
内核调试的接口
==============
--
2.27.0
^ permalink raw reply related [flat|nested] 8+ messages in thread* Re: [PATCH v6 0/6] docs/zh_CN: add core-api Memory management translation
2021-09-17 6:33 [PATCH v6 0/6] docs/zh_CN: add core-api Memory management translation Yanteng Si
` (5 preceding siblings ...)
2021-09-17 6:33 ` [PATCH v6 6/6] docs/zh_CN: add core-api gfp_mask-from-fs-io translation Yanteng Si
@ 2021-09-27 17:30 ` Jonathan Corbet
6 siblings, 0 replies; 8+ messages in thread
From: Jonathan Corbet @ 2021-09-27 17:30 UTC (permalink / raw)
To: Yanteng Si, alexs, seakeel
Cc: Yanteng Si, chenhuacai, jiaxun.yang, linux-doc, realpuyuwang,
siyanteng01
Yanteng Si <siyanteng01@gmail.com> writes:
> v6:
>
> warning fix:
> 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
>
> It looks like two identical tags are causing that warning, but I
> tested it in sphinx-2.4.4 and sphinx-4.1.2 and got no warning.
>
> I have modified the tags in the Chinese documentation:
>
> diff --git a/Documentation/translations/zh_CN/core-api/mm-api.rst b/Documentation/translations/zh_CN/core-api/mm-api.rst
>
> -.. _mm-api-gfp-flags:
> +.. _cn_mm-api-gfp-flags:
>
> 内存分配控制
> ============
>
> 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!
>
> 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
Set applied, thanks.
jon
^ permalink raw reply [flat|nested] 8+ messages in thread