Add a document with a brief explanation of numa emulation and how to use
the newly added "numa_emulation.adistance=" kernel cmdline parameter.

Signed-off-by: Akinobu Mita <akinobu.mita@gmail.com>
---
v2:
- added in v2

 Documentation/mm/index.rst          |  1 +
 Documentation/mm/numa_emulation.rst | 30 +++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 Documentation/mm/numa_emulation.rst

diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst
index 7aa2a8886908..7d628edd6a17 100644
--- a/Documentation/mm/index.rst
+++ b/Documentation/mm/index.rst
@@ -24,6 +24,7 @@ see the :doc:`admin guide <../admin-guide/mm/index>`.
    page_cache
    shmfs
    oom
+   numa_emulation
 
 Unsorted Documentation
 ======================
diff --git a/Documentation/mm/numa_emulation.rst b/Documentation/mm/numa_emulation.rst
new file mode 100644
index 000000000000..dce9f607c031
--- /dev/null
+++ b/Documentation/mm/numa_emulation.rst
@@ -0,0 +1,30 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============
+NUMA emulation
+==============
+
+If CONFIG_NUMA_EMU is enabled, you can create fake NUMA nodes with
+``numa=fake=`` kernel cmdline option.
+See Documentation/admin-guide/kernel-parameters.txt and
+Documentation/arch/x86/x86_64/fake-numa-for-cpusets.rst for more information.
+
+
+Multiple Memory Tiers Creation
+==============================
+
+The "numa_emulation.adistance=" kernel cmdline option allows you to set
+the abstract distance for each NUMA node.
+
+For example, you can create two fake nodes, each in a different memory
+tier by booting with "numa=fake=2 numa_emulation.adistance=576,704".
+Here, the abstract distances of node0 and node1 are set to 576 and 706,
+respectively.
+
+Each memory tier covers an abstract distance chunk size of 128. Thus,
+nodes with abstract distances between 512 and 639 are classified into the
+same memory tier, and nodes with abstract distances between 640 and 767
+are classified into the next slower memory tier.
+
+The abstract distance of fake nodes not specified in the parameter will
+be the default DRAM abstract distance of 576.
-- 
2.43.0

On Thu,  8 Jan 2026 19:15:34 +0900
Akinobu Mita <akinobu.mita@gmail.com> wrote:

> Add a document with a brief explanation of numa emulation and how to use
> the newly added "numa_emulation.adistance=" kernel cmdline parameter.
> 
> Signed-off-by: Akinobu Mita <akinobu.mita@gmail.com>
I'm not sure on the benefit of a NUMA emulation doc that only really covers
the new stuff in your series.  Feels like a more thorough doc with everything
in one place would be better.  Still, what you have here is good to have so
Reviewed-by: Jonathan Cameron <jonathan.cameron@huawei.com>

> ---
> v2:
> - added in v2
> 
>  Documentation/mm/index.rst          |  1 +
>  Documentation/mm/numa_emulation.rst | 30 +++++++++++++++++++++++++++++
>  2 files changed, 31 insertions(+)
>  create mode 100644 Documentation/mm/numa_emulation.rst
> 
> diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst
> index 7aa2a8886908..7d628edd6a17 100644
> --- a/Documentation/mm/index.rst
> +++ b/Documentation/mm/index.rst
> @@ -24,6 +24,7 @@ see the :doc:`admin guide <../admin-guide/mm/index>`.
>     page_cache
>     shmfs
>     oom
> +   numa_emulation
>  
>  Unsorted Documentation
>  ======================
> diff --git a/Documentation/mm/numa_emulation.rst b/Documentation/mm/numa_emulation.rst
> new file mode 100644
> index 000000000000..dce9f607c031
> --- /dev/null
> +++ b/Documentation/mm/numa_emulation.rst
> @@ -0,0 +1,30 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==============
> +NUMA emulation
> +==============
> +
> +If CONFIG_NUMA_EMU is enabled, you can create fake NUMA nodes with
> +``numa=fake=`` kernel cmdline option.
> +See Documentation/admin-guide/kernel-parameters.txt and
> +Documentation/arch/x86/x86_64/fake-numa-for-cpusets.rst for more information.
> +
> +
> +Multiple Memory Tiers Creation
> +==============================
> +
> +The "numa_emulation.adistance=" kernel cmdline option allows you to set
> +the abstract distance for each NUMA node.
> +
> +For example, you can create two fake nodes, each in a different memory
> +tier by booting with "numa=fake=2 numa_emulation.adistance=576,704".
> +Here, the abstract distances of node0 and node1 are set to 576 and 706,
> +respectively.
> +
> +Each memory tier covers an abstract distance chunk size of 128. Thus,
> +nodes with abstract distances between 512 and 639 are classified into the
> +same memory tier, and nodes with abstract distances between 640 and 767
> +are classified into the next slower memory tier.
> +
> +The abstract distance of fake nodes not specified in the parameter will
> +be the default DRAM abstract distance of 576.