Skip to contentSkip to conversation

docs/mm: start filling out new structure

PATCH Superseded Mike Rapoport 3 participants 9 messages Jan 15, 2023 – Jan 25, 2023

Subsystems (3)

v4 of 5 Superseded Latest is v5 →

lore
Share & tools
lore

Mike Rapoport

author reviewer
#0 lore raw

v4 cover docs/mm: start filling out new structure

Hi,

Last year at LSF/MM Matthew promptly created the new structure for MM documentation, but there still was no patches with content.

I've started to work on it a while ago and I wanted to send it out in a more complete form, but I've got distracted and didn't have time to work on this.

With fast changes around struct page and the threat of Lorenzo's book, I've decided to send out what I have till now with a hope that we can really make this a collaborative effort with people filling paragraph here and there.

If somebody does not feel like sending formal patches, just send me the "raw" text my way and I'll deal with the rest.

The text is relatively heavily formatted because I believe the target audience will prefer html version.

v4:
* squash commits into one (Bagas)
* fix references formatting (kbuild)
* add Reviewed-by and Acked-by tags

v3: https://lore.kernel.org/all/[email protected]
* rephrase ZONE_DMA(32) and ZONE_MOVABLE description (Michal)
* add cross-reference to DMA API

v2: https://lore.kernel.org/all/[email protected]
* rephrase the paragraph inroducing zones (Lorenzo)
* update formatting (Bagas)
* add section stubs (Bagas)
* small fixes here and there

v1: https://lore.kernel.org/all/[email protected]

Mike Rapoport (IBM) (1):
docs/mm: Physical Memory: add structure, introduction and nodes
description

 Documentation/core-api/dma-api.rst   |   2 +
 Documentation/mm/page_reclaim.rst    |   2 +
 Documentation/mm/physical_memory.rst | 346 +++++++++++++++++++++++++++
 3 files changed, 350 insertions(+)
Signature · 1 line
2.35.1
author reviewer
#1 lore raw

PATCH v4 1/1 docs/mm: Physical Memory: add structure, introduction and nodes description

From: "Mike Rapoport (IBM)" <[email protected]>

Add structure, introduction and Nodes section to Physical Memory chapter.

As the new documentation references core-api/dma-api and mm/page_reclaim, add page labels to those documents.

---
 Documentation/core-api/dma-api.rst   |   2 +
 Documentation/mm/page_reclaim.rst    |   2 +
 Documentation/mm/physical_memory.rst | 346 +++++++++++++++++++++++++++
 3 files changed, 350 insertions(+)
Documentation/core-api/dma-api.rst +2 -0
index 829f20a193ca..c847a5b0a0d3 100644
@@ -1,3 +1,5 @@
+.. _dma_api:
+
 ============================================
 Dynamic DMA mapping using the generic device
 ============================================
Documentation/mm/page_reclaim.rst +2 -0
index 50a30b7f8ac3..3fccde066436 100644
@@ -1,5 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+.. _page_reclaim:
+
 ============
 Page Reclaim
 ============
Documentation/mm/physical_memory.rst +346 -0

349 lines not on this page · raw message

Signature · 1 line
2.35.1
Acked-by on v4 1/1
#2 lore raw

Re: [PATCH v4 1/1] docs/mm: Physical Memory: add structure, introduction and nodes description

Quoted 5 lines · Mike Rapoport

From: "Mike Rapoport (IBM)" <[email protected]>

Add structure, introduction and Nodes section to Physical Memory chapter.

Quoted 7 lines

As the new documentation references core-api/dma-api and mm/page_reclaim, add page labels to those documents.

A small bug to fix below?

<snip>

Quoted 4 lines
Documentation/mm/physical_memory.rst +4 -0
+
+Along with the node structures, kernel maintains an array of ``nodemask_t``
+bitmasks called ``node_states``. Each bitmask in this array represents a set of
+nodes with particular properties as defined by ``enum node_states``:

Documentation/mm/physical_memory.rst line 150

Quoted 10 lines
Documentation/mm/physical_memory.rst +10 -0
+
+``N_POSSIBLE``
+  The node could become online at some point.
+``N_ONLINE``
+  The node is online.
+``N_NORMAL_MEMORY``
+  The node has regular memory.
+``N_HIGH_MEMORY``
+  The node has regular or high memory. When ``CONFIG_HIGHMEM`` is disabled
+  aliased to ``N_NORMAL_MEMORY``.

Noted.

Quoted 5 lines

+``N_MEMORY``

Documentation/mm/physical_memory.rst +4 -0
+  The node has memory(regular, high, movable)
+``N_CPU``
+  The node has one or more CPUs
+

Documentation/mm/physical_memory.rst line 165

Quoted 10 lines
Documentation/mm/physical_memory.rst +10 -0
+For each node that has a property described above, the bit corresponding to the
+node ID in the ``node_states[<property>]`` bitmask is set.
+
+For example, for node 2 with normal memory and CPUs, bit 2 will be set in ::
+
+  node_states[N_POSSIBLE]
+  node_states[N_ONLINE]
+  node_states[N_NORMAL_MEMORY]
+  node_states[N_MEMORY]
+  node_states[N_CPU]

Should it be set also in node_states[N_HIGH_MEMORY]?

author reviewer
#3 lore raw

Re: [PATCH v4 1/1] docs/mm: Physical Memory: add structure, introduction and nodes description

Quoted 46 lines · Vlastimil Babka
Quoted 5 lines · Mike Rapoport

From: "Mike Rapoport (IBM)" <[email protected]>

Add structure, introduction and Nodes section to Physical Memory chapter.

Quoted 7 lines

As the new documentation references core-api/dma-api and mm/page_reclaim, add page labels to those documents.

A small bug to fix below?

<snip>

Quoted 4 lines
Documentation/mm/physical_memory.rst +4 -0
+
+Along with the node structures, kernel maintains an array of ``nodemask_t``
+bitmasks called ``node_states``. Each bitmask in this array represents a set of
+nodes with particular properties as defined by ``enum node_states``:

Documentation/mm/physical_memory.rst line 150

Quoted 10 lines
Documentation/mm/physical_memory.rst +10 -0
+
+``N_POSSIBLE``
+  The node could become online at some point.
+``N_ONLINE``
+  The node is online.
+``N_NORMAL_MEMORY``
+  The node has regular memory.
+``N_HIGH_MEMORY``
+  The node has regular or high memory. When ``CONFIG_HIGHMEM`` is disabled
+  aliased to ``N_NORMAL_MEMORY``.

Noted.

Quoted 9 lines

+``N_MEMORY``

Documentation/mm/physical_memory.rst +8 -0
+  The node has memory(regular, high, movable)
+``N_CPU``
+  The node has one or more CPUs
+
+For each node that has a property described above, the bit corresponding to the
+node ID in the ``node_states[<property>]`` bitmask is set.
+
+For example, for node 2 with normal memory and CPUs, bit 2 will be set in ::
Quoted 8 lines

Documentation/mm/physical_memory.rst line 165

Quoted 6 lines
Documentation/mm/physical_memory.rst +6 -0
+
+  node_states[N_POSSIBLE]
+  node_states[N_ONLINE]
+  node_states[N_NORMAL_MEMORY]
+  node_states[N_MEMORY]
+  node_states[N_CPU]

Should it be set also in node_states[N_HIGH_MEMORY]?

You mean because of the aliasing of N_NORMAL_MEMORY and N_HIGH_MEMORY?

#4 lore raw

Re: [PATCH v4 1/1] docs/mm: Physical Memory: add structure, introduction and nodes description

Quoted 56 lines · Mike Rapoport
Quoted 46 lines · Vlastimil Babka
Quoted 5 lines · Mike Rapoport

From: "Mike Rapoport (IBM)" <[email protected]>

Add structure, introduction and Nodes section to Physical Memory chapter.

Quoted 7 lines

As the new documentation references core-api/dma-api and mm/page_reclaim, add page labels to those documents.

A small bug to fix below?

<snip>

Quoted 4 lines
Documentation/mm/physical_memory.rst +4 -0
+
+Along with the node structures, kernel maintains an array of ``nodemask_t``
+bitmasks called ``node_states``. Each bitmask in this array represents a set of
+nodes with particular properties as defined by ``enum node_states``:

Documentation/mm/physical_memory.rst line 150

Quoted 10 lines
Documentation/mm/physical_memory.rst +10 -0
+
+``N_POSSIBLE``
+  The node could become online at some point.
+``N_ONLINE``
+  The node is online.
+``N_NORMAL_MEMORY``
+  The node has regular memory.
+``N_HIGH_MEMORY``
+  The node has regular or high memory. When ``CONFIG_HIGHMEM`` is disabled
+  aliased to ``N_NORMAL_MEMORY``.

Noted.

Quoted 9 lines

+``N_MEMORY``

Documentation/mm/physical_memory.rst +8 -0
+  The node has memory(regular, high, movable)
+``N_CPU``
+  The node has one or more CPUs
+
+For each node that has a property described above, the bit corresponding to the
+node ID in the ``node_states[<property>]`` bitmask is set.
+
+For example, for node 2 with normal memory and CPUs, bit 2 will be set in ::
Quoted 8 lines

Documentation/mm/physical_memory.rst line 165

Quoted 6 lines
Documentation/mm/physical_memory.rst +6 -0
+
+  node_states[N_POSSIBLE]
+  node_states[N_ONLINE]
+  node_states[N_NORMAL_MEMORY]
+  node_states[N_MEMORY]
+  node_states[N_CPU]

Should it be set also in node_states[N_HIGH_MEMORY]?

Quoted 1 line

You mean because of the aliasing of N_NORMAL_MEMORY and N_HIGH_MEMORY?

No I meant due to "The node has regular or high memory." Or do I misunderstand?

author reviewer
#5 lore raw

Re: [PATCH v4 1/1] docs/mm: Physical Memory: add structure, introduction and nodes description

Quoted 59 lines · Vlastimil Babka
Quoted 56 lines · Mike Rapoport
Quoted 54 lines · Vlastimil Babka
Quoted 5 lines · Mike Rapoport

From: "Mike Rapoport (IBM)" <[email protected]>

Add structure, introduction and Nodes section to Physical Memory chapter.

Quoted 7 lines

As the new documentation references core-api/dma-api and mm/page_reclaim, add page labels to those documents.

A small bug to fix below?

<snip>

Quoted 4 lines
Documentation/mm/physical_memory.rst +4 -0
+
+Along with the node structures, kernel maintains an array of ``nodemask_t``
+bitmasks called ``node_states``. Each bitmask in this array represents a set of
+nodes with particular properties as defined by ``enum node_states``:

Documentation/mm/physical_memory.rst line 150

Quoted 10 lines
Documentation/mm/physical_memory.rst +10 -0
+
+``N_POSSIBLE``
+  The node could become online at some point.
+``N_ONLINE``
+  The node is online.
+``N_NORMAL_MEMORY``
+  The node has regular memory.
+``N_HIGH_MEMORY``
+  The node has regular or high memory. When ``CONFIG_HIGHMEM`` is disabled
+  aliased to ``N_NORMAL_MEMORY``.

Noted.

Quoted 5 lines

+``N_MEMORY``

Documentation/mm/physical_memory.rst +4 -0
+  The node has memory(regular, high, movable)
+``N_CPU``
+  The node has one or more CPUs
+

Documentation/mm/physical_memory.rst line 165

Quoted 10 lines
Documentation/mm/physical_memory.rst +10 -0
+For each node that has a property described above, the bit corresponding to the
+node ID in the ``node_states[<property>]`` bitmask is set.
+
+For example, for node 2 with normal memory and CPUs, bit 2 will be set in ::
+
+  node_states[N_POSSIBLE]
+  node_states[N_ONLINE]
+  node_states[N_NORMAL_MEMORY]
+  node_states[N_MEMORY]
+  node_states[N_CPU]

Should it be set also in node_states[N_HIGH_MEMORY]?

Quoted 3 lines
Quoted 1 line

You mean because of the aliasing of N_NORMAL_MEMORY and N_HIGH_MEMORY?

No I meant due to "The node has regular or high memory." Or do I misunderstand?

I checked the code, node_states[N_HIGH_MEMORY] will be set indeed. Will send v5 soon.

author reviewer
#6 lore raw
In reply to Mike Rapoport

Gentle ping.

Quoted 49 lines · Mike Rapoport

Hi,

Last year at LSF/MM Matthew promptly created the new structure for MM documentation, but there still was no patches with content.

I've started to work on it a while ago and I wanted to send it out in a more complete form, but I've got distracted and didn't have time to work on this.

With fast changes around struct page and the threat of Lorenzo's book, I've decided to send out what I have till now with a hope that we can really make this a collaborative effort with people filling paragraph here and there.

If somebody does not feel like sending formal patches, just send me the "raw" text my way and I'll deal with the rest.

The text is relatively heavily formatted because I believe the target audience will prefer html version.

v4:
* squash commits into one (Bagas)
* fix references formatting (kbuild)
* add Reviewed-by and Acked-by tags

v3: https://lore.kernel.org/all/[email protected]
* rephrase ZONE_DMA(32) and ZONE_MOVABLE description (Michal)
* add cross-reference to DMA API

v2: https://lore.kernel.org/all/[email protected]
* rephrase the paragraph inroducing zones (Lorenzo)
* update formatting (Bagas)
* add section stubs (Bagas)
* small fixes here and there

v1: https://lore.kernel.org/all/[email protected]

Mike Rapoport (IBM) (1):
docs/mm: Physical Memory: add structure, introduction and nodes
description

 Documentation/core-api/dma-api.rst   |   2 +
 Documentation/mm/page_reclaim.rst    |   2 +
 Documentation/mm/physical_memory.rst | 346 +++++++++++++++++++++++++++
 3 files changed, 350 insertions(+)
Signature · 1 line
2.35.1
Signature · 2 lines
Sincerely yours,
Mike.
maintainer
#7 lore raw
Quoted 1 line · Mike Rapoport

Gentle ping.

Is that your way of saying that you think it's perhaps ready to be applied? I've been watching the discussion but wasn't sure if things have settled or not.

Thanks,

jon

author reviewer
#8 lore raw
Quoted 7 lines · Jonathan Corbet
Quoted 1 line · Mike Rapoport

Gentle ping.

Is that your way of saying that you think it's perhaps ready to be applied? I've been watching the discussion but wasn't sure if things have settled or not.

Well, everybody who participated in the discussion acked the patch, so yeah, I think it's ready ;-)

Quoted 3 lines

Thanks,

jon