Skip to contentSkip to conversation

docs/mm: start filling out new structure

PATCH In review Mike Rapoport 2 participants 5 messages Jan 25, 2023 – Jan 26, 2023

Subsystems (3)
lore
Share & tools
lore

Mike Rapoport

author reviewer
#0 lore raw

v5 cover docs/mm: start filling out new structure

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

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.

v5:
* fix node_states[] example (Vlastimil)

v4: https://lore.kernel.org/all/[email protected]
* 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 · 18 lines
2.35.1


*** BLURB HERE ***

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 | 347 +++++++++++++++++++++++++++
 3 files changed, 351 insertions(+)


base-commit: b7bfaa761d760e72a969d116517eaa12e404c262
-- 
2.35.1
author reviewer
#1 lore raw

PATCH v5 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 | 347 +++++++++++++++++++++++++++
 3 files changed, 351 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 +347 -0

350 lines not on this page · raw message

Signature · 1 line
2.35.1
maintainer
#2 lore raw

Re: [PATCH v5 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 8 lines

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

I've gone ahead and applied this, but I do have one little gripe...

Documentation/core-api/dma-api.rst line 2

Quoted 12 lines
 Documentation/core-api/dma-api.rst   |   2 +
 Documentation/mm/page_reclaim.rst    |   2 +
 Documentation/mm/physical_memory.rst | 347 +++++++++++++++++++++++++++
 3 files changed, 351 insertions(+)
Documentation/core-api/dma-api.rst +2 -0
index 829f20a193ca..c847a5b0a0d3 100644
@@ -1,3 +1,5 @@
+.. _dma_api:
+

Top-of-file labels like this one...

Documentation/mm/page_reclaim.rst line 3

Quoted 11 lines
Documentation/core-api/dma-api.rst +0 -0
 ============================================
 Dynamic DMA mapping using the generic device
 ============================================
Documentation/mm/page_reclaim.rst +1 -0
index 50a30b7f8ac3..3fccde066436 100644
@@ -1,5 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+.. _page_reclaim:

...and this one really just add noise without bringing any value. Something like:

Documentation/mm/page_reclaim.rst line 7

Quoted 4 lines
Documentation/mm/page_reclaim.rst +4 -0
+Reclaim control
+~~~~~~~~~~~~~~~
+
+See also :ref:`Page Reclaim <page_reclaim>`.

Can also just be "See also Documentation/mm/page_reclaim.rst". The right things will happen in the HTML output, readers of the plain-text will know immediately where to go, and we don't have to add the label clutter.

</gripe> :)

Thanks,

jon

author reviewer
#3 lore raw

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

Quoted 30 lines · Jonathan Corbet
Quoted 5 lines · Mike Rapoport

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

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

Quoted 8 lines

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

I've gone ahead and applied this, but I do have one little gripe...

Something like:

Documentation/mm/physical_memory.rst line 255

Quoted 4 lines
Documentation/mm/physical_memory.rst +4 -0
+Reclaim control
+~~~~~~~~~~~~~~~
+
+See also :ref:`Page Reclaim <page_reclaim>`.

Can also just be "See also Documentation/mm/page_reclaim.rst". The right things will happen in the HTML output, readers of the plain-text will know immediately where to go, and we don't have to add the label clutter.

Quoted 1 line

</gripe> :)

Do you want v6? ;-)

Quoted 3 lines

Thanks,

jon

Signature · 2 lines
Sincerely yours,
Mike.
maintainer
#4 lore raw

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

Quoted 1 line · Mike Rapoport

Do you want v6? ;-)

Naw, I didn't think it was worth holding up the work any longer, so it's applied. Feel free to send a fixup though :)

Thanks,

jon