Skip to contentSkip to conversation

Documentation: riscv: tableize memory layout

PATCH In review Bagas Sanjaya 4 participants 5 messages Nov 6, 2022 – Nov 7, 2022

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Documentation: riscv: tableize memory layout

The memory layout is written as table but it is inside literal code block, which renders as preformatted text. Write the layout in reST grid table instead.

---
 Documentation/riscv/vm-layout.rst | 120 +++++++++++++++---------------
 1 file changed, 58 insertions(+), 62 deletions(-)
Documentation/riscv/vm-layout.rst +58 -62
index 5b36e45fef60bd..139320e35de81f 100644
@@ -30,70 +30,66 @@ the RISC-V Linux Kernel resides.
 RISC-V Linux Kernel SV39
 ------------------------
 
-::
-
-  ========================================================================================================================
-      Start addr    |   Offset   |     End addr     |  Size   | VM area description
-  ========================================================================================================================
-                    |            |                  |         |
-   0000000000000000 |    0       | 0000003fffffffff |  256 GB | user-space virtual memory, different per mm
-  __________________|____________|__________________|_________|___________________________________________________________
-                    |            |                  |         |
-   0000004000000000 | +256    GB | ffffffbfffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical
-                    |            |                  |         |     virtual memory addresses up to the -256 GB
-                    |            |                  |         |     starting offset of kernel mappings.
-  __________________|____________|__________________|_________|___________________________________________________________
-                                                              |
-                                                              | Kernel-space virtual memory, shared between all processes:
-  ____________________________________________________________|___________________________________________________________
-                    |            |                  |         |
-   ffffffc6fee00000 | -228    GB | ffffffc6feffffff |    2 MB | fixmap
-   ffffffc6ff000000 | -228    GB | ffffffc6ffffffff |   16 MB | PCI io
-   ffffffc700000000 | -228    GB | ffffffc7ffffffff |    4 GB | vmemmap
-   ffffffc800000000 | -224    GB | ffffffd7ffffffff |   64 GB | vmalloc/ioremap space
-   ffffffd800000000 | -160    GB | fffffff6ffffffff |  124 GB | direct mapping of all physical memory
-   fffffff700000000 |  -36    GB | fffffffeffffffff |   32 GB | kasan
-  __________________|____________|__________________|_________|____________________________________________________________
-                                                              |
-                                                              |
-  ____________________________________________________________|____________________________________________________________
-                    |            |                  |         |
-   ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | modules, BPF
-   ffffffff80000000 |   -2    GB | ffffffffffffffff |    2 GB | kernel
-  __________________|____________|__________________|_________|____________________________________________________________
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   |    Start addr    | Offset  |     End addr     |  Size   | VM area description                                      |
+   +==================+=========+==================+=========+==========================================================+
+   | 0000000000000000 |    0    | 0000003fffffffff | 256 GB  | user-space virtual memory, different per mm              |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | 0000004000000000 | +256 GB | ffffffbfffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical      |
+   |                  |         |                  |         | virtual memory addresses up to the -256 GB               |
+   |                  |         |                  |         | starting offset of kernel mappings.                      |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   |                             Kernel-space virtual memory, shared between all processes:                             |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffc6fee00000 | -228 GB | ffffffc6feffffff | 2 MB    | fixmap                                                   |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffc6ff000000 | -228 GB | ffffffc6ffffffff | 16 MB   | PCI io                                                   |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffc700000000 | -228 GB | ffffffc7ffffffff | 4 GB    | vmemmap                                                  |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffc800000000 | -224 GB | ffffffd7ffffffff | 64 GB   | vmalloc/ioremap space                                    |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffd800000000 | -160 GB | fffffff6ffffffff | 124 GB  | direct mapping of all physical memory                    |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | fffffff700000000 | -36 GB  | fffffffeffffffff | 32 GB   | kasan                                                    |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   |                                  Identical layout to the 39-bit one from here on:                                  |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffff00000000 | -4 GB   | ffffffff7fffffff | 2 GB    | modules, BPF                                             |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffff80000000 | -2 GB   | ffffffffffffffff | 2 GB    | kernel                                                   |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
 
 
 RISC-V Linux Kernel SV48
 ------------------------
 
-::
-
- ========================================================================================================================
-      Start addr    |   Offset   |     End addr     |  Size   | VM area description
- ========================================================================================================================
-                    |            |                  |         |
-   0000000000000000 |    0       | 00007fffffffffff |  128 TB | user-space virtual memory, different per mm
-  __________________|____________|__________________|_________|___________________________________________________________
-                    |            |                  |         |
-   0000800000000000 | +128    TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical
-                    |            |                  |         | virtual memory addresses up to the -128 TB
-                    |            |                  |         | starting offset of kernel mappings.
-  __________________|____________|__________________|_________|___________________________________________________________
-                                                              |
-                                                              | Kernel-space virtual memory, shared between all processes:
-  ____________________________________________________________|___________________________________________________________
-                    |            |                  |         |
-   ffff8d7ffee00000 |  -114.5 TB | ffff8d7ffeffffff |    2 MB | fixmap
-   ffff8d7fff000000 |  -114.5 TB | ffff8d7fffffffff |   16 MB | PCI io
-   ffff8d8000000000 |  -114.5 TB | ffff8f7fffffffff |    2 TB | vmemmap
-   ffff8f8000000000 |  -112.5 TB | ffffaf7fffffffff |   32 TB | vmalloc/ioremap space
-   ffffaf8000000000 |  -80.5  TB | ffffef7fffffffff |   64 TB | direct mapping of all physical memory
-   ffffef8000000000 |  -16.5  TB | fffffffeffffffff | 16.5 TB | kasan
-  __________________|____________|__________________|_________|____________________________________________________________
-                                                              |
-                                                              | Identical layout to the 39-bit one from here on:
-  ____________________________________________________________|____________________________________________________________
-                    |            |                  |         |
-   ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | modules, BPF
-   ffffffff80000000 |   -2    GB | ffffffffffffffff |    2 GB | kernel
-  __________________|____________|__________________|_________|____________________________________________________________
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   |    Start addr    |  Offset   |     End addr     |  Size   | VM area description                                   |
+   +==================+===========+==================+=========+=======================================================+
+   | 0000000000000000 |    0      | 00007fffffffffff | 128 TB  | user-space virtual memory, different per mm           |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   | 0000800000000000 | +128 TB   | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical   |
+   |                  |           |                  |         | virtual memory addresses up to the -128 TB            |
+   |                  |           |                  |         | starting offset of kernel mappings.                   |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   |                            Kernel-space virtual memory, shared between all processes:                             |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   | ffff8d7ffee00000 | -114.5 TB | ffff8d7ffeffffff | 2 MB    | fixmap                                                |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   | ffff8d7fff000000 | -114.5 TB | ffff8d7fffffffff | 16 MB   | PCI io                                                |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   | ffff8d8000000000 | -114.5 TB | ffff8f7fffffffff | 2 TB    | vmemmap                                               |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   | ffff8f8000000000 | -112.5 TB | ffffaf7fffffffff | 32 TB   | vmalloc/ioremap space                                 |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   | ffffaf8000000000 | -80.5 TB  | ffffef7fffffffff | 64 TB   | direct mapping of all physical memory                 |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   | ffffef8000000000 | -16.5 TB  | fffffffeffffffff | 16.5 TB | kasan                                                 |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   |                                 Identical layout to the 39-bit one from here on:                                  |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   | ffffffff00000000 | -4 GB     | ffffffff7fffffff | 2 GB    | modules, BPF                                          |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+
+   | ffffffff80000000 | -2 GB     | ffffffffffffffff | 2 GB    | kernel                                                |
+   +------------------+-----------+------------------+---------+-------------------------------------------------------+

base-commit: 0cdb3579f1ee4c1e55acf8dfb0697b660067b1f8

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#1 lore raw
Quoted 1 line · Bagas Sanjaya

Documentation: riscv: tableize memory layout

Minor nit about the $subject - but this is the docs, so I guess there's nowhere better to mention grammar: "tableize" is not a word. I think what you want here is "tabulate".

Quoted 1 line

The memory layout is written as table but it is inside literal code

^ as a table ^ inside a

Anyway, those are minor nits I saw in passing, one actual comment and a simple question below.
Thanks,
Conor.

Quoted 52 lines

block, which renders as preformatted text. Write the layout in reST grid table instead.

---
 Documentation/riscv/vm-layout.rst | 120 +++++++++++++++---------------
 1 file changed, 58 insertions(+), 62 deletions(-)
Documentation/riscv/vm-layout.rst +5 -31
index 5b36e45fef60bd..139320e35de81f 100644
@@ -30,70 +30,66 @@ the RISC-V Linux Kernel resides.
 RISC-V Linux Kernel SV39
 ------------------------
 
-::
-
-  ========================================================================================================================
-      Start addr    |   Offset   |     End addr     |  Size   | VM area description
-  ========================================================================================================================
-                    |            |                  |         |
-   0000000000000000 |    0       | 0000003fffffffff |  256 GB | user-space virtual memory, different per mm
-  __________________|____________|__________________|_________|___________________________________________________________
-                    |            |                  |         |
-   0000004000000000 | +256    GB | ffffffbfffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical
-                    |            |                  |         |     virtual memory addresses up to the -256 GB
-                    |            |                  |         |     starting offset of kernel mappings.
-  __________________|____________|__________________|_________|___________________________________________________________
-                                                              |
-                                                              | Kernel-space virtual memory, shared between all processes:
-  ____________________________________________________________|___________________________________________________________
-                    |            |                  |         |
-   ffffffc6fee00000 | -228    GB | ffffffc6feffffff |    2 MB | fixmap
-   ffffffc6ff000000 | -228    GB | ffffffc6ffffffff |   16 MB | PCI io
-   ffffffc700000000 | -228    GB | ffffffc7ffffffff |    4 GB | vmemmap
-   ffffffc800000000 | -224    GB | ffffffd7ffffffff |   64 GB | vmalloc/ioremap space
-   ffffffd800000000 | -160    GB | fffffff6ffffffff |  124 GB | direct mapping of all physical memory
-   fffffff700000000 |  -36    GB | fffffffeffffffff |   32 GB | kasan
-  __________________|____________|__________________|_________|____________________________________________________________
-                                                              |
-                                                              |
-  ____________________________________________________________|____________________________________________________________
-                    |            |                  |         |
-   ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | modules, BPF
-   ffffffff80000000 |   -2    GB | ffffffffffffffff |    2 GB | kernel
-  __________________|____________|__________________|_________|____________________________________________________________
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   |    Start addr    | Offset  |     End addr     |  Size   | VM area description                                      |
+   +==================+=========+==================+=========+==========================================================+
+   | 0000000000000000 |    0    | 0000003fffffffff | 256 GB  | user-space virtual memory, different per mm              |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+

Documentation/riscv/vm-layout.rst the RISC-V Linux Kernel resides. · line 47

Quoted 10 lines
Documentation/riscv/vm-layout.rst +10 -0
+   | 0000004000000000 | +256 GB | ffffffbfffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical      |
+   |                  |         |                  |         | virtual memory addresses up to the -256 GB               |
+   |                  |         |                  |         | starting offset of kernel mappings.                      |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   |                             Kernel-space virtual memory, shared between all processes:                             |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffc6fee00000 | -228 GB | ffffffc6feffffff | 2 MB    | fixmap                                                   |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffc6ff000000 | -228 GB | ffffffc6ffffffff | 16 MB   | PCI io                                                   |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
                                                        ^

Will these numbers remain right-aligned in the formatted doc? They were aligned before in the text form & no longer appear to be.

Documentation/riscv/vm-layout.rst the RISC-V Linux Kernel resides. · line 56

Quoted 9 lines
Documentation/riscv/vm-layout.rst +9 -0
+   | ffffffc700000000 | -228 GB | ffffffc7ffffffff | 4 GB    | vmemmap                                                  |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffc800000000 | -224 GB | ffffffd7ffffffff | 64 GB   | vmalloc/ioremap space                                    |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffd800000000 | -160 GB | fffffff6ffffffff | 124 GB  | direct mapping of all physical memory                    |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | fffffff700000000 | -36 GB  | fffffffeffffffff | 32 GB   | kasan                                                    |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   |                                  Identical layout to the 39-bit one from here on:                                  |

This one /is/ sv39. I'd leave this as a blank to match the styling in the original document.

Quoted 7 lines
Documentation/riscv/vm-layout.rst +5 -0
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffff00000000 | -4 GB   | ffffffff7fffffff | 2 GB    | modules, BPF                                             |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffff80000000 | -2 GB   | ffffffffffffffff | 2 GB    | kernel                                                   |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
 
 
#2 lore raw
Quoted 15 lines · Conor Dooley
Quoted 5 lines
Documentation/riscv/vm-layout.rst +5 -0
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   |    Start addr    | Offset  |     End addr     |  Size   | VM area description                                      |
+   +==================+=========+==================+=========+==========================================================+
+   | 0000000000000000 |    0    | 0000003fffffffff | 256 GB  | user-space virtual memory, different per mm              |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+

Documentation/riscv/vm-layout.rst the RISC-V Linux Kernel resides. · line 47

Quoted 10 lines
Documentation/riscv/vm-layout.rst +10 -0
+   | 0000004000000000 | +256 GB | ffffffbfffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical      |
+   |                  |         |                  |         | virtual memory addresses up to the -256 GB               |
+   |                  |         |                  |         | starting offset of kernel mappings.                      |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   |                             Kernel-space virtual memory, shared between all processes:                             |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffc6fee00000 | -228 GB | ffffffc6feffffff | 2 MB    | fixmap                                                   |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffc6ff000000 | -228 GB | ffffffc6ffffffff | 16 MB   | PCI io                                                   |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
Quoted 4 lines
                                                        ^

Will these numbers remain right-aligned in the formatted doc? They were aligned before in the text form & no longer appear to be.

These numbers also become wrapped in their cells.

However, in order to fix alignment of these, custom CSS is needed, similar to one in StackOverflow [1].

[1]: https://stackoverflow.com/a/7351383

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#3 lore raw
Quoted 21 lines · Bagas Sanjaya
Quoted 15 lines · Conor Dooley
Quoted 5 lines
Documentation/riscv/vm-layout.rst +5 -0
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   |    Start addr    | Offset  |     End addr     |  Size   | VM area description                                      |
+   +==================+=========+==================+=========+==========================================================+
+   | 0000000000000000 |    0    | 0000003fffffffff | 256 GB  | user-space virtual memory, different per mm              |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+

Documentation/riscv/vm-layout.rst the RISC-V Linux Kernel resides. · line 47

Quoted 10 lines
Documentation/riscv/vm-layout.rst +10 -0
+   | 0000004000000000 | +256 GB | ffffffbfffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical      |
+   |                  |         |                  |         | virtual memory addresses up to the -256 GB               |
+   |                  |         |                  |         | starting offset of kernel mappings.                      |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   |                             Kernel-space virtual memory, shared between all processes:                             |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffc6fee00000 | -228 GB | ffffffc6feffffff | 2 MB    | fixmap                                                   |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
+   | ffffffc6ff000000 | -228 GB | ffffffc6ffffffff | 16 MB   | PCI io                                                   |
+   +------------------+---------+------------------+---------+----------------------------------------------------------+
Quoted 4 lines
                                                        ^

Will these numbers remain right-aligned in the formatted doc? They were aligned before in the text form & no longer appear to be.

Quoted 4 lines

These numbers also become wrapped in their cells.

However, in order to fix alignment of these, custom CSS is needed, similar to one in StackOverflow [1].

Hmm. In that case I'd be inclined to agree with Akira that this should be left as is.

Thanks,
Conor.

#4 lore raw
In reply to Bagas Sanjaya

Hi Bagas,

Quoted 3 lines · Bagas Sanjaya

The memory layout is written as table but it is inside literal code block, which renders as preformatted text. Write the layout in reST grid table instead.

What's the purpose of this change?

The tables in html/pdf output after this change are almost unreadable to my eyes due to the proportional font and random wrapping inside table columns.

I think in this particular case, "literal block" is the right choice at least for html output, as can be seen at:

https://www.kernel.org/doc/html/latest/riscv/vm-layout.html
https://www.kernel.org/doc/html/next/riscv/vm-layout.html

Yes, these very wide tables need horizontal scrolling in the alabaster theme (in next), but they look much nicer than your version.

In pdf output, wide literal blocks are force-wrapped and don't look good. Using some smaller font size for latex might help, but most people don't care much of pdf outputs anyway, I guess.

Thanks, Akira

Quoted 5 lines
---
 Documentation/riscv/vm-layout.rst | 120 +++++++++++++++---------------
 1 file changed, 58 insertions(+), 62 deletions(-)