docs/mm: start filling out new structure
Subsystems (3)
Mike Rapoport
reviewerv4 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
Mike Rapoport
reviewerPATCH 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
@@ -1,3 +1,5 @@ +.. _dma_api: + ============================================ Dynamic DMA mapping using the generic device ============================================
Documentation/mm/page_reclaim.rst +2 -0
@@ -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
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.Reviewed-by Bagas Sanjaya <[email protected]>Reviewed-by Lorenzo Stoakes <[email protected]>Acked-by Michal Hocko <[email protected]>Signed-off-by Mike Rapoport (IBM) <[email protected]>
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]?
Mike Rapoport
reviewerRe: [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.Reviewed-by Bagas Sanjaya <[email protected]>Reviewed-by Lorenzo Stoakes <[email protected]>Acked-by Michal Hocko <[email protected]>Signed-off-by Mike Rapoport (IBM) <[email protected]>Acked-by Vlastimil Babka <[email protected]>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?
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.Reviewed-by Bagas Sanjaya <[email protected]>Reviewed-by Lorenzo Stoakes <[email protected]>Acked-by Michal Hocko <[email protected]>Signed-off-by Mike Rapoport (IBM) <[email protected]>Acked-by Vlastimil Babka <[email protected]>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_MEMORYandN_HIGH_MEMORY?
No I meant due to "The node has regular or high memory." Or do I misunderstand?
Mike Rapoport
reviewerRe: [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.Reviewed-by Bagas Sanjaya <[email protected]>Reviewed-by Lorenzo Stoakes <[email protected]>Acked-by Michal Hocko <[email protected]>Signed-off-by Mike Rapoport (IBM) <[email protected]>Acked-by Vlastimil Babka <[email protected]>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_MEMORYandN_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.
Mike Rapoport
reviewerGentle 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 tagsv3: https://lore.kernel.org/all/[email protected]
* rephraseZONE_DMA(32)andZONE_MOVABLEdescription (Michal)
* add cross-reference to DMA APIv2: https://lore.kernel.org/all/[email protected]
* rephrase the paragraph inroducing zones (Lorenzo)
* update formatting (Bagas)
* add section stubs (Bagas)
* small fixes here and therev1: https://lore.kernel.org/all/[email protected]
Mike Rapoport (IBM) (1):
docs/mm: Physical Memory: add structure, introduction and nodes
descriptionDocumentation/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.
Jonathan Corbet
maintainerQuoted 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
Mike Rapoport
reviewerQuoted 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