[PATCH] Documentation/zh_CN: add latest kmap_local_page translation

[PATCH] Documentation/zh_CN: add latest kmap_local_page translation

[Zhao Liu]

From: Zhao Liu <zhao1.liu@intel.com>

Translate the lastest description of kmap_local_page into Chinese.

The translation is based on these commits:

commit 516ea046ec555 ("Documentation/mm: don't kmap*() pages which
can't come from HIGHMEM")

commit 6b3afe2eeec27 ("Documentation/mm: avoid invalid use of
addresses from kmap_local_page()")

commit 84b86f6054c42 ("Documentation/mm: rrefer kmap_local_page()
and avoid kmap()")

commit a9e9c93966afd ("Documentation/mm: add details about
kmap_local_page() and preemption")

Suggested-by: Ira Weiny <ira.weiny@intel.com>
Suggested-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
---
Suggested by credits.
        Ira: Referred to his task document.
        Fabio: Referred to his work on the original English document.

---
 .../translations/zh_CN/mm/highmem.rst         | 20 ++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/Documentation/translations/zh_CN/mm/highmem.rst b/Documentation/translations/zh_CN/mm/highmem.rst
index f74800a6d9a7..ac4c86ed74d8 100644
--- a/Documentation/translations/zh_CN/mm/highmem.rst
+++ b/Documentation/translations/zh_CN/mm/highmem.rst
@@ -58,14 +58,28 @@
   在可行的情况下，这个函数应该比其他所有的函数优先使用。
 
   这些映射是线程本地和CPU本地的，这意味着映射只能从这个线程中访问，并且当映射处于活动状
-  态时，该线程与CPU绑定。即使线程被抢占了（因为抢占永远不会被函数禁用），CPU也不能通过
-  CPU-hotplug从系统中拔出，直到映射被处理掉。
+  态时，该线程与CPU绑定。即使抢占永远不会被这个函数禁用，CPU也不能通过CPU-hotplug从系
+  统中拔出，直到映射被处理掉。
 
-  在本地的kmap区域中采取pagefaults是有效的，除非获取本地映射的上下文由于其他原因不允许
+  在本地的kmap区域中获取pagefaults是有效的，除非获取本地映射的上下文由于其他原因不允许
   这样做。
 
+  如前所述，pagefault和抢占永远不会被禁用。不需要禁用抢占，因为当上下文切换到不同的任务
+  时，传出任务的映射会被保存，而传入任务的映射会被恢复。
+
   kmap_local_page()总是返回一个有效的虚拟地址，并且假定kunmap_local()不会失败。
 
+  在CONFIG_HIGHMEM=n内核和低内存页面上，这将返回直接映射的虚拟地址。只有真正的高内存页
+  面会被临时映射。因此，用户可以为已知不是来自ZONE_HIGHMEM的页面调用普通的
+  page_address()，但是，使用kmap_local_page() / kunmap_local()总是安全的。
+
+  虽然它比kmap()快得多，但对于高内存情况，它带有指针有效性的限制。和kmap()映射相反，本地
+  映射仅在调用者的上下文中有效，并不能被交给其他的上下文。这意味着用户必须绝对确保返回的地址
+  仅在映射它的线程的本地使用。
+
+  大多数代码可以设计为使用线程本地映射。因此，用户应该尝试这样去设计他们的代码，在地址会被使
+  用的同一线程中映射页面来避免使用kmap()，并且更倾向于去使用kmap_local_page()。
+
   嵌套kmap_local_page()和kmap_atomic()映射在一定程度上是允许的（最多到KMAP_TYPE_NR），
   但是它们的调用必须严格排序，因为映射的实现是基于堆栈的。关于如何管理嵌套映射的细节，
   请参见kmap_local_page() kdocs（包含在 "函数 "部分）。
-- 
2.34.1

Re: [PATCH] Documentation/zh_CN: add latest kmap_local_page translation

[Alex Shi]

On Fri, Sep 2, 2022 at 4:08 PM Zhao Liu <zhao1.liu@linux.intel.com> wrote:
>
> From: Zhao Liu <zhao1.liu@intel.com>
>
> Translate the lastest description of kmap_local_page into Chinese.
>
> The translation is based on these commits:
>
> commit 516ea046ec555 ("Documentation/mm: don't kmap*() pages which
> can't come from HIGHMEM")
>
> commit 6b3afe2eeec27 ("Documentation/mm: avoid invalid use of
> addresses from kmap_local_page()")
>
> commit 84b86f6054c42 ("Documentation/mm: rrefer kmap_local_page()
> and avoid kmap()")
>
> commit a9e9c93966afd ("Documentation/mm: add details about
> kmap_local_page() and preemption")
>
> Suggested-by: Ira Weiny <ira.weiny@intel.com>
> Suggested-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
> Signed-off-by: Zhao Liu <zhao1.liu@intel.com>

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

> ---
> Suggested by credits.
>         Ira: Referred to his task document.
>         Fabio: Referred to his work on the original English document.
>
> ---
>  .../translations/zh_CN/mm/highmem.rst         | 20 ++++++++++++++++---
>  1 file changed, 17 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/translations/zh_CN/mm/highmem.rst b/Documentation/translations/zh_CN/mm/highmem.rst
> index f74800a6d9a7..ac4c86ed74d8 100644
> --- a/Documentation/translations/zh_CN/mm/highmem.rst
> +++ b/Documentation/translations/zh_CN/mm/highmem.rst
> @@ -58,14 +58,28 @@
>    在可行的情况下，这个函数应该比其他所有的函数优先使用。
>
>    这些映射是线程本地和CPU本地的，这意味着映射只能从这个线程中访问，并且当映射处于活动状
> -  态时，该线程与CPU绑定。即使线程被抢占了（因为抢占永远不会被函数禁用），CPU也不能通过
> -  CPU-hotplug从系统中拔出，直到映射被处理掉。
> +  态时，该线程与CPU绑定。即使抢占永远不会被这个函数禁用，CPU也不能通过CPU-hotplug从系
> +  统中拔出，直到映射被处理掉。
>
> -  在本地的kmap区域中采取pagefaults是有效的，除非获取本地映射的上下文由于其他原因不允许
> +  在本地的kmap区域中获取pagefaults是有效的，除非获取本地映射的上下文由于其他原因不允许
>    这样做。
>
> +  如前所述，pagefault和抢占永远不会被禁用。不需要禁用抢占，因为当上下文切换到不同的任务
> +  时，传出任务的映射会被保存，而传入任务的映射会被恢复。
> +
>    kmap_local_page()总是返回一个有效的虚拟地址，并且假定kunmap_local()不会失败。
>
> +  在CONFIG_HIGHMEM=n内核和低内存页面上，这将返回直接映射的虚拟地址。只有真正的高内存页
> +  面会被临时映射。因此，用户可以为已知不是来自ZONE_HIGHMEM的页面调用普通的
> +  page_address()，但是，使用kmap_local_page() / kunmap_local()总是安全的。
> +
> +  虽然它比kmap()快得多，但对于高内存情况，它带有指针有效性的限制。和kmap()映射相反，本地
> +  映射仅在调用者的上下文中有效，并不能被交给其他的上下文。这意味着用户必须绝对确保返回的地址
> +  仅在映射它的线程的本地使用。
> +
> +  大多数代码可以设计为使用线程本地映射。因此，用户应该尝试这样去设计他们的代码，在地址会被使
> +  用的同一线程中映射页面来避免使用kmap()，并且更倾向于去使用kmap_local_page()。
> +
>    嵌套kmap_local_page()和kmap_atomic()映射在一定程度上是允许的（最多到KMAP_TYPE_NR），
>    但是它们的调用必须严格排序，因为映射的实现是基于堆栈的。关于如何管理嵌套映射的细节，
>    请参见kmap_local_page() kdocs（包含在 "函数 "部分）。
> --
> 2.34.1
>

Re: [PATCH] Documentation/zh_CN: add latest kmap_local_page translation

[Wu XiangCheng]

[-- Attachment #1: Type: text/plain, Size: 1433 bytes --]

Hi Liu,

1. It is better to give this patch a more meaningful name, like:
	update something to 6.0-rc2
   "latest" is too ambiguous.

2022-09-02 (五) 16:13:04 +0800 Zhao Liu 曰：
> From: Zhao Liu <zhao1.liu@intel.com>
> 
> Translate the lastest description of kmap_local_page into Chinese.
> 
> The translation is based on these commits:
> 
> commit 516ea046ec555 ("Documentation/mm: don't kmap*() pages which
> can't come from HIGHMEM")
> 
> commit 6b3afe2eeec27 ("Documentation/mm: avoid invalid use of
> addresses from kmap_local_page()")
> 
> commit 84b86f6054c42 ("Documentation/mm: rrefer kmap_local_page()
> and avoid kmap()")
> 
> commit a9e9c93966afd ("Documentation/mm: add details about
> kmap_local_page() and preemption")
> 

2. Just list the latest commit, that's enough.

> Suggested-by: Ira Weiny <ira.weiny@intel.com>
> Suggested-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
> Signed-off-by: Zhao Liu <zhao1.liu@intel.com>

Please remember above two next time ;)

Anyway,

Reviewed-by: Wu XiangCheng <bobwxc@email.cn>

> ---
> Suggested by credits.
>         Ira: Referred to his task document.
>         Fabio: Referred to his work on the original English document.
> 
> ---
>  .../translations/zh_CN/mm/highmem.rst         | 20 ++++++++++++++++---
>  1 file changed, 17 insertions(+), 3 deletions(-)
> 

Thanks,

-- 
Wu XiangCheng	0x32684A40BCA7AEA7


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]

Re: [PATCH] Documentation/zh_CN: add latest kmap_local_page translation

[YanTeng Si]

在 2022/9/2 16:13, Zhao Liu 写道:
> From: Zhao Liu <zhao1.liu@intel.com>
>
> Translate the lastest description of kmap_local_page into Chinese.
>
> The translation is based on these commits:
>
> commit 516ea046ec555 ("Documentation/mm: don't kmap*() pages which
> can't come from HIGHMEM")
>
> commit 6b3afe2eeec27 ("Documentation/mm: avoid invalid use of
> addresses from kmap_local_page()")
>
> commit 84b86f6054c42 ("Documentation/mm: rrefer kmap_local_page()
> and avoid kmap()")
>
> commit a9e9c93966afd ("Documentation/mm: add details about
> kmap_local_page() and preemption")
>
> Suggested-by: Ira Weiny <ira.weiny@intel.com>
> Suggested-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
> Signed-off-by: Zhao Liu <zhao1.liu@intel.com>

Acked-by: Yanteng Si <siyanteng@loongson.cn>
> ---
> Suggested by credits.
>          Ira: Referred to his task document.
>          Fabio: Referred to his work on the original English document.
>
> ---
>   .../translations/zh_CN/mm/highmem.rst         | 20 ++++++++++++++++---
>   1 file changed, 17 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/translations/zh_CN/mm/highmem.rst b/Documentation/translations/zh_CN/mm/highmem.rst
> index f74800a6d9a7..ac4c86ed74d8 100644
> --- a/Documentation/translations/zh_CN/mm/highmem.rst
> +++ b/Documentation/translations/zh_CN/mm/highmem.rst
> @@ -58,14 +58,28 @@
>     在可行的情况下，这个函数应该比其他所有的函数优先使用。
>   
>     这些映射是线程本地和CPU本地的，这意味着映射只能从这个线程中访问，并且当映射处于活动状
> -  态时，该线程与CPU绑定。即使线程被抢占了（因为抢占永远不会被函数禁用），CPU也不能通过
> -  CPU-hotplug从系统中拔出，直到映射被处理掉。
> +  态时，该线程与CPU绑定。即使抢占永远不会被这个函数禁用，CPU也不能通过CPU-hotplug从系
> +  统中拔出，直到映射被处理掉。
>   
> -  在本地的kmap区域中采取pagefaults是有效的，除非获取本地映射的上下文由于其他原因不允许
> +  在本地的kmap区域中获取pagefaults是有效的，除非获取本地映射的上下文由于其他原因不允许
>     这样做。
>   
> +  如前所述，pagefault和抢占永远不会被禁用。不需要禁用抢占，因为当上下文切换到不同的任务
> +  时，传出任务的映射会被保存，而传入任务的映射会被恢复。
> +
>     kmap_local_page()总是返回一个有效的虚拟地址，并且假定kunmap_local()不会失败。
>   
> +  在CONFIG_HIGHMEM=n内核和低内存页面上，这将返回直接映射的虚拟地址。只有真正的高内存页
> +  面会被临时映射。因此，用户可以为已知不是来自ZONE_HIGHMEM的页面调用普通的
> +  page_address()，但是，使用kmap_local_page() / kunmap_local()总是安全的。
> +
> +  虽然它比kmap()快得多，但对于高内存情况，它带有指针有效性的限制。和kmap()映射相反，本地
> +  映射仅在调用者的上下文中有效，并不能被交给其他的上下文。这意味着用户必须绝对确保返回的地址
> +  仅在映射它的线程的本地使用。
> +
> +  大多数代码可以设计为使用线程本地映射。因此，用户应该尝试这样去设计他们的代码，在地址会被使
> +  用的同一线程中映射页面来避免使用kmap()，并且更倾向于去使用kmap_local_page()。
> +
>     嵌套kmap_local_page()和kmap_atomic()映射在一定程度上是允许的（最多到KMAP_TYPE_NR），
>     但是它们的调用必须严格排序，因为映射的实现是基于堆栈的。关于如何管理嵌套映射的细节，
>     请参见kmap_local_page() kdocs（包含在 "函数 "部分）。