[PATCH 0/2] docs/zh_CN: add free_page_reporting and highmem translation

[PATCH 0/2] docs/zh_CN: add free_page_reporting and highmem translation

[Yanteng Si]

Translate .../vm/free_page_reporting.rst .../vm/highmem.rst into Chinese.

Yanteng Si (2):
  docs/zh_CN: add free_page_reporting translation
  docs/zh_CN: add highmem translation

 .../zh_CN/vm/free_page_reporting.rst          |  38 ++++++
 .../translations/zh_CN/vm/highmem.rst         | 128 ++++++++++++++++++
 Documentation/translations/zh_CN/vm/index.rst |   7 +-
 3 files changed, 170 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/translations/zh_CN/vm/free_page_reporting.rst
 create mode 100644 Documentation/translations/zh_CN/vm/highmem.rst

-- 
2.27.0

[PATCH 1/2] docs/zh_CN: add free_page_reporting translation

[Yanteng Si]

Translate .../vm/free_page_reporting.rst into Chinese.

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 .../zh_CN/vm/free_page_reporting.rst          | 38 +++++++++++++++++++
 Documentation/translations/zh_CN/vm/index.rst |  5 ++-
 2 files changed, 41 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/translations/zh_CN/vm/free_page_reporting.rst

diff --git a/Documentation/translations/zh_CN/vm/free_page_reporting.rst b/Documentation/translations/zh_CN/vm/free_page_reporting.rst
new file mode 100644
index 000000000000..6894e26ce079
--- /dev/null
+++ b/Documentation/translations/zh_CN/vm/free_page_reporting.rst
@@ -0,0 +1,38 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/vm/_free_page_reporting.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+==========
+空闲页报告
+==========
+
+空闲页报告是一个API，设备可以通过它来注册接收系统当前未使用的页面列表。这在虚拟
+化的情况下是很有用的，客户机能够使用这些数据来通知管理器它不再使用内存中的某些页
+面。
+
+对于驱动，通常是气球驱动要使用这个功能，它将分配和初始化一个page_reporting_dev_info
+结构体。它要填充的结构体中的字段是用于处理散点列表的 "report" 函数指针。它还必
+须保证每次调用该函数时能处理至少相当于PAGE_REPORTING_CAPACITY的散点列表条目。
+假设没有其他页面报告设备已经注册， 对page_reporting_register的调用将向报告框
+架注册页面报告接口。
+
+一旦注册，页面报告API将开始向驱动报告成批的页面。API将在接口被注册后2秒开始报告
+页面，并在任何足够高的页面被释放之后2秒继续报告。
+
+报告的页面将被存储在传递给报告函数的散列表中，最后一个条目的结束位被设置在条目
+nent-1中。 当页面被报告函数处理时，分配器将无法访问它们。一旦报告函数完成，这些
+页将被返回到它们所获得的自由区域。
+
+在移除使用空闲页报告的驱动之前，有必要调用page_reporting_unregister，以移除
+目前被空闲页报告使用的page_reporting_dev_info结构体。这样做将阻止进一步的报
+告通过该接口发出。如果另一个驱动或同一驱动被注册，它就有可能恢复前一个驱动在报告
+空闲页方面的工作。
+
+
+Alexander Duyck, 2019年12月04日
diff --git a/Documentation/translations/zh_CN/vm/index.rst b/Documentation/translations/zh_CN/vm/index.rst
index fc39f0d60318..9cdfde0364f0 100644
--- a/Documentation/translations/zh_CN/vm/index.rst
+++ b/Documentation/translations/zh_CN/vm/index.rst
@@ -23,17 +23,18 @@ TODO:待引用文档集被翻译完毕后请及时修改此处）
 
    active_mm
    balance
+   damon/index
+   free_page_reporting
+   ksm
 
 TODOLIST:
 * arch_pgtable_helpers
-* damon/index
 * free_page_reporting
 * frontswap
 * highmem
 * hmm
 * hwpoison
 * hugetlbfs_reserv
-* ksm
 * memory-model
 * mmu_notifier
 * numa
-- 
2.27.0

[PATCH 2/2] docs/zh_CN: add highmem translation

[Yanteng Si]

Translate .../vm/highmem.rst into Chenese.

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 .../translations/zh_CN/vm/highmem.rst         | 128 ++++++++++++++++++
 Documentation/translations/zh_CN/vm/index.rst |   2 +-
 2 files changed, 129 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/vm/highmem.rst

diff --git a/Documentation/translations/zh_CN/vm/highmem.rst b/Documentation/translations/zh_CN/vm/highmem.rst
new file mode 100644
index 000000000000..d3021e21780b
--- /dev/null
+++ b/Documentation/translations/zh_CN/vm/highmem.rst
@@ -0,0 +1,128 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/vm/highmem.rst
+
+:翻译:
+
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+==========
+高内存处理
+==========
+
+作者: Peter Zijlstra <a.p.zijlstra@chello.nl>
+
+.. contents:: :local:
+
+高内存是什么？
+==============
+
+当物理内存的大小接近或超过虚拟内存的最大大小时，就会使用高内存（highmem）。在这一点上，内
+核不可能在任何时候都保持所有可用的物理内存的映射。这意味着内核需要开始使用它想访问的物理内
+存的临时映射。
+
+没有被永久映射覆盖的那部分（物理）内存就是我们所说的 "高内存"。对于这个边界的确切位置，有
+各种架构上的限制。
+
+例如，在i386架构中，我们选择将内核映射到每个进程的虚拟空间，这样我们就不必为内核的进入/退
+出付出全部的TLB作废代价。这意味着可用的虚拟内存空间（i386上为4GiB）必须在用户和内核空间之
+间进行划分。
+
+使用这种方法的架构的传统分配方式是3:1，3GiB用于用户空间，顶部的1GiB用于内核空间。::
+
+		+--------+ 0xffffffff
+		| Kernel |
+		+--------+ 0xc0000000
+		|        |
+		| User   |
+		|        |
+		+--------+ 0x00000000
+
+这意味着内核在任何时候最多可以映射1GiB的物理内存，但是由于我们需要虚拟地址空间来做其他事
+情--包括访问其余物理内存的临时映射--实际的直接映射通常会更少（通常在~896MiB左右）。
+
+其他有mm上下文标签的TLB的架构可以有独立的内核和用户映射。然而，一些硬件（如一些ARM）在使
+用mm上下文标签时，其虚拟空间有限。
+
+
+临时虚拟映射
+============
+
+内核包含几种创建临时映射的方法。:
+
+* vmap().  这可以用来将多个物理页长期映射到一个连续的虚拟空间。它需要synchronization
+  来解除映射。
+
+* kmap().  这允许对单个页面进行短期映射。它需要synchronization，但在一定程度上被摊销。
+  当以嵌套方式使用时，它也很容易出现死锁，因此不建议在新代码中使用它。
+
+* kmap_atomic().  这允许对单个页面进行非常短的时间映射。由于映射被限制在发布它的CPU上，
+  它表现得很好，但发布任务因此被要求留在该CPU上直到它完成，以免其他任务取代它的映射。
+
+  kmap_atomic() 也可以由中断上下文使用，因为它不睡眠，而且调用者可能在调用kunmap_atomic()
+  之后才睡眠。
+
+  可以假设k[un]map_atomic()不会失败。
+
+
+使用kmap_atomic
+===============
+
+何时何地使用 kmap_atomic() 是很直接的。当代码想要访问一个可能从高内存（见__GFP_HIGHMEM）
+分配的页面的内容时，例如在页缓存中的页面，就会使用它。该API有两个函数，它们的使用方式与
+下面类似::
+
+	/* 找到感兴趣的页面。 */
+	struct page *page = find_get_page(mapping, offset);
+
+	/* 获得对该页内容的访问权。 */
+	void *vaddr = kmap_atomic(page);
+
+	/* 对该页的内容做一些处理。 */
+	memset(vaddr, 0, PAGE_SIZE);
+
+	/* 解除该页面的映射。 */
+	kunmap_atomic(vaddr);
+
+注意，kunmap_atomic()调用的是kmap_atomic()调用的结果而不是参数。
+
+如果你需要映射两个页面，因为你想从一个页面复制到另一个页面，你需要保持kmap_atomic调用严
+格嵌套，如::
+
+	vaddr1 = kmap_atomic(page1);
+	vaddr2 = kmap_atomic(page2);
+
+	memcpy(vaddr1, vaddr2, PAGE_SIZE);
+
+	kunmap_atomic(vaddr2);
+	kunmap_atomic(vaddr1);
+
+
+临时映射的成本
+==============
+
+创建临时映射的代价可能相当高。体系架构必须操作内核的页表、数据TLB和/或MMU的寄存器。
+
+如果CONFIG_HIGHMEM没有被设置，那么内核会尝试用一点计算来创建映射，将页面结构地址转换成
+指向页面内容的指针，而不是去捣鼓映射。在这种情况下，解映射操作可能是一个空操作。
+
+如果CONFIG_MMU没有被设置，那么就不可能有临时映射和高内存。在这种情况下，也将使用计算方法。
+
+
+i386 PAE
+========
+
+在某些情况下，i386 架构将允许你在 32 位机器上安装多达 64GiB 的内存。但这有一些后果:
+
+* Linux需要为系统中的每个页面建立一个页帧结构，而且页帧需要驻在永久映射中，这意味着：
+
+* 你最多可以有896M/sizeof(struct page)页帧；由于页结构体是32字节的，所以最终会有
+  112G的页；然而，内核需要在内存中存储更多的页帧......
+
+* PAE使你的页表变大--这使系统变慢，因为更多的数据需要在TLB填充等方面被访问。一个好处
+  是，PAE有更多的PTE位，可以提供像NX和PAT这样的高级功能。
+
+一般的建议是，你不要在32位机器上使用超过8GiB的空间--尽管更多的空间可能对你和你的工作
+量有用，但你几乎是靠你自己--不要指望内核开发者真的会很关心事情的进展情况。
diff --git a/Documentation/translations/zh_CN/vm/index.rst b/Documentation/translations/zh_CN/vm/index.rst
index 9cdfde0364f0..a1d2f0356cc1 100644
--- a/Documentation/translations/zh_CN/vm/index.rst
+++ b/Documentation/translations/zh_CN/vm/index.rst
@@ -25,13 +25,13 @@ TODO:待引用文档集被翻译完毕后请及时修改此处）
    balance
    damon/index
    free_page_reporting
+   highmem
    ksm
 
 TODOLIST:
 * arch_pgtable_helpers
 * free_page_reporting
 * frontswap
-* highmem
 * hmm
 * hwpoison
 * hugetlbfs_reserv
-- 
2.27.0

Re: [PATCH 1/2] docs/zh_CN: add free_page_reporting translation

[Alex Shi]

On Thu, Jan 27, 2022 at 9:50 AM Yanteng Si <siyanteng01@gmail.com> wrote:
>
> Translate .../vm/free_page_reporting.rst into Chinese.
>
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>

Reviewed-by: Alex Shi <alexs@kernel.org>

> ---
>  .../zh_CN/vm/free_page_reporting.rst          | 38 +++++++++++++++++++
>  Documentation/translations/zh_CN/vm/index.rst |  5 ++-
>  2 files changed, 41 insertions(+), 2 deletions(-)
>  create mode 100644 Documentation/translations/zh_CN/vm/free_page_reporting.rst
>
> diff --git a/Documentation/translations/zh_CN/vm/free_page_reporting.rst b/Documentation/translations/zh_CN/vm/free_page_reporting.rst
> new file mode 100644
> index 000000000000..6894e26ce079
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/vm/free_page_reporting.rst
> @@ -0,0 +1,38 @@
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/vm/_free_page_reporting.rst
> +
> +:翻译:
> +
> + 司延腾 Yanteng Si <siyanteng@loongson.cn>
> +
> +:校译:
> +
> +==========
> +空闲页报告
> +==========
> +
> +空闲页报告是一个API，设备可以通过它来注册接收系统当前未使用的页面列表。这在虚拟
> +化的情况下是很有用的，客户机能够使用这些数据来通知管理器它不再使用内存中的某些页
> +面。
> +
> +对于驱动，通常是气球驱动要使用这个功能，它将分配和初始化一个page_reporting_dev_info
> +结构体。它要填充的结构体中的字段是用于处理散点列表的 "report" 函数指针。它还必
> +须保证每次调用该函数时能处理至少相当于PAGE_REPORTING_CAPACITY的散点列表条目。
> +假设没有其他页面报告设备已经注册， 对page_reporting_register的调用将向报告框
> +架注册页面报告接口。
> +
> +一旦注册，页面报告API将开始向驱动报告成批的页面。API将在接口被注册后2秒开始报告
> +页面，并在任何足够高的页面被释放之后2秒继续报告。
> +
> +报告的页面将被存储在传递给报告函数的散列表中，最后一个条目的结束位被设置在条目
> +nent-1中。 当页面被报告函数处理时，分配器将无法访问它们。一旦报告函数完成，这些
> +页将被返回到它们所获得的自由区域。
> +
> +在移除使用空闲页报告的驱动之前，有必要调用page_reporting_unregister，以移除
> +目前被空闲页报告使用的page_reporting_dev_info结构体。这样做将阻止进一步的报
> +告通过该接口发出。如果另一个驱动或同一驱动被注册，它就有可能恢复前一个驱动在报告
> +空闲页方面的工作。
> +
> +
> +Alexander Duyck, 2019年12月04日
> diff --git a/Documentation/translations/zh_CN/vm/index.rst b/Documentation/translations/zh_CN/vm/index.rst
> index fc39f0d60318..9cdfde0364f0 100644
> --- a/Documentation/translations/zh_CN/vm/index.rst
> +++ b/Documentation/translations/zh_CN/vm/index.rst
> @@ -23,17 +23,18 @@ TODO:待引用文档集被翻译完毕后请及时修改此处）
>
>     active_mm
>     balance
> +   damon/index
> +   free_page_reporting
> +   ksm
>
>  TODOLIST:
>  * arch_pgtable_helpers
> -* damon/index
>  * free_page_reporting
>  * frontswap
>  * highmem
>  * hmm
>  * hwpoison
>  * hugetlbfs_reserv
> -* ksm
>  * memory-model
>  * mmu_notifier
>  * numa
> --
> 2.27.0
>

Re: [PATCH 2/2] docs/zh_CN: add highmem translation

[Alex Shi]

On Thu, Jan 27, 2022 at 9:50 AM Yanteng Si <siyanteng01@gmail.com> wrote:
>
> Translate .../vm/highmem.rst into Chenese.
>
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>

Reviewed-by: Alex Shi <alexs@kernel.org>

> ---
>  .../translations/zh_CN/vm/highmem.rst         | 128 ++++++++++++++++++
>  Documentation/translations/zh_CN/vm/index.rst |   2 +-
>  2 files changed, 129 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/translations/zh_CN/vm/highmem.rst
>
> diff --git a/Documentation/translations/zh_CN/vm/highmem.rst b/Documentation/translations/zh_CN/vm/highmem.rst
> new file mode 100644
> index 000000000000..d3021e21780b
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/vm/highmem.rst
> @@ -0,0 +1,128 @@
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/vm/highmem.rst
> +
> +:翻译:
> +
> + 司延腾 Yanteng Si <siyanteng@loongson.cn>
> +
> +:校译:
> +
> +==========
> +高内存处理
> +==========
> +
> +作者: Peter Zijlstra <a.p.zijlstra@chello.nl>
> +
> +.. contents:: :local:
> +
> +高内存是什么？
> +==============
> +
> +当物理内存的大小接近或超过虚拟内存的最大大小时，就会使用高内存（highmem）。在这一点上，内
> +核不可能在任何时候都保持所有可用的物理内存的映射。这意味着内核需要开始使用它想访问的物理内
> +存的临时映射。
> +
> +没有被永久映射覆盖的那部分（物理）内存就是我们所说的 "高内存"。对于这个边界的确切位置，有
> +各种架构上的限制。
> +
> +例如，在i386架构中，我们选择将内核映射到每个进程的虚拟空间，这样我们就不必为内核的进入/退
> +出付出全部的TLB作废代价。这意味着可用的虚拟内存空间（i386上为4GiB）必须在用户和内核空间之
> +间进行划分。
> +
> +使用这种方法的架构的传统分配方式是3:1，3GiB用于用户空间，顶部的1GiB用于内核空间。::
> +
> +               +--------+ 0xffffffff
> +               | Kernel |
> +               +--------+ 0xc0000000
> +               |        |
> +               | User   |
> +               |        |
> +               +--------+ 0x00000000
> +
> +这意味着内核在任何时候最多可以映射1GiB的物理内存，但是由于我们需要虚拟地址空间来做其他事
> +情--包括访问其余物理内存的临时映射--实际的直接映射通常会更少（通常在~896MiB左右）。
> +
> +其他有mm上下文标签的TLB的架构可以有独立的内核和用户映射。然而，一些硬件（如一些ARM）在使
> +用mm上下文标签时，其虚拟空间有限。
> +
> +
> +临时虚拟映射
> +============
> +
> +内核包含几种创建临时映射的方法。:
> +
> +* vmap().  这可以用来将多个物理页长期映射到一个连续的虚拟空间。它需要synchronization
> +  来解除映射。
> +
> +* kmap().  这允许对单个页面进行短期映射。它需要synchronization，但在一定程度上被摊销。
> +  当以嵌套方式使用时，它也很容易出现死锁，因此不建议在新代码中使用它。
> +
> +* kmap_atomic().  这允许对单个页面进行非常短的时间映射。由于映射被限制在发布它的CPU上，
> +  它表现得很好，但发布任务因此被要求留在该CPU上直到它完成，以免其他任务取代它的映射。
> +
> +  kmap_atomic() 也可以由中断上下文使用，因为它不睡眠，而且调用者可能在调用kunmap_atomic()
> +  之后才睡眠。
> +
> +  可以假设k[un]map_atomic()不会失败。
> +
> +
> +使用kmap_atomic
> +===============
> +
> +何时何地使用 kmap_atomic() 是很直接的。当代码想要访问一个可能从高内存（见__GFP_HIGHMEM）
> +分配的页面的内容时，例如在页缓存中的页面，就会使用它。该API有两个函数，它们的使用方式与
> +下面类似::
> +
> +       /* 找到感兴趣的页面。 */
> +       struct page *page = find_get_page(mapping, offset);
> +
> +       /* 获得对该页内容的访问权。 */
> +       void *vaddr = kmap_atomic(page);
> +
> +       /* 对该页的内容做一些处理。 */
> +       memset(vaddr, 0, PAGE_SIZE);
> +
> +       /* 解除该页面的映射。 */
> +       kunmap_atomic(vaddr);
> +
> +注意，kunmap_atomic()调用的是kmap_atomic()调用的结果而不是参数。
> +
> +如果你需要映射两个页面，因为你想从一个页面复制到另一个页面，你需要保持kmap_atomic调用严
> +格嵌套，如::
> +
> +       vaddr1 = kmap_atomic(page1);
> +       vaddr2 = kmap_atomic(page2);
> +
> +       memcpy(vaddr1, vaddr2, PAGE_SIZE);
> +
> +       kunmap_atomic(vaddr2);
> +       kunmap_atomic(vaddr1);
> +
> +
> +临时映射的成本
> +==============
> +
> +创建临时映射的代价可能相当高。体系架构必须操作内核的页表、数据TLB和/或MMU的寄存器。
> +
> +如果CONFIG_HIGHMEM没有被设置，那么内核会尝试用一点计算来创建映射，将页面结构地址转换成
> +指向页面内容的指针，而不是去捣鼓映射。在这种情况下，解映射操作可能是一个空操作。
> +
> +如果CONFIG_MMU没有被设置，那么就不可能有临时映射和高内存。在这种情况下，也将使用计算方法。
> +
> +
> +i386 PAE
> +========
> +
> +在某些情况下，i386 架构将允许你在 32 位机器上安装多达 64GiB 的内存。但这有一些后果:
> +
> +* Linux需要为系统中的每个页面建立一个页帧结构，而且页帧需要驻在永久映射中，这意味着：
> +
> +* 你最多可以有896M/sizeof(struct page)页帧；由于页结构体是32字节的，所以最终会有
> +  112G的页；然而，内核需要在内存中存储更多的页帧......
> +
> +* PAE使你的页表变大--这使系统变慢，因为更多的数据需要在TLB填充等方面被访问。一个好处
> +  是，PAE有更多的PTE位，可以提供像NX和PAT这样的高级功能。
> +
> +一般的建议是，你不要在32位机器上使用超过8GiB的空间--尽管更多的空间可能对你和你的工作
> +量有用，但你几乎是靠你自己--不要指望内核开发者真的会很关心事情的进展情况。
> diff --git a/Documentation/translations/zh_CN/vm/index.rst b/Documentation/translations/zh_CN/vm/index.rst
> index 9cdfde0364f0..a1d2f0356cc1 100644
> --- a/Documentation/translations/zh_CN/vm/index.rst
> +++ b/Documentation/translations/zh_CN/vm/index.rst
> @@ -25,13 +25,13 @@ TODO:待引用文档集被翻译完毕后请及时修改此处）
>     balance
>     damon/index
>     free_page_reporting
> +   highmem
>     ksm
>
>  TODOLIST:
>  * arch_pgtable_helpers
>  * free_page_reporting
>  * frontswap
> -* highmem
>  * hmm
>  * hwpoison
>  * hugetlbfs_reserv
> --
> 2.27.0
>

Re: [PATCH 0/2] docs/zh_CN: add free_page_reporting and highmem translation

[Jonathan Corbet]

Yanteng Si <siyanteng01@gmail.com> writes:

> Translate .../vm/free_page_reporting.rst .../vm/highmem.rst into Chinese.
>
> Yanteng Si (2):
>   docs/zh_CN: add free_page_reporting translation
>   docs/zh_CN: add highmem translation
>
>  .../zh_CN/vm/free_page_reporting.rst          |  38 ++++++
>  .../translations/zh_CN/vm/highmem.rst         | 128 ++++++++++++++++++
>  Documentation/translations/zh_CN/vm/index.rst |   7 +-
>  3 files changed, 170 insertions(+), 3 deletions(-)
>  create mode 100644 Documentation/translations/zh_CN/vm/free_page_reporting.rst
>  create mode 100644 Documentation/translations/zh_CN/vm/highmem.rst

Set applied, thanks.

jon