Re: [PATCH v2 3/3] doc: arch: arm64: describe pagetable debugging

[Tom Rini <trini@konsulko.com>]

[-- Attachment #1: Type: text/plain, Size: 2768 bytes --]

On Fri, Jun 07, 2024 at 10:42:51PM +0200, Caleb Connolly wrote:
> Add some brief documentation on using dump_pagetables() to print out
> U-Boot's pagetables during boot.
> 
> Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
> ---
>  doc/arch/arm64.rst | 37 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
> 
> diff --git a/doc/arch/arm64.rst b/doc/arch/arm64.rst
> index 7c0713504c47..0c851304aad4 100644
> --- a/doc/arch/arm64.rst
> +++ b/doc/arch/arm64.rst
> @@ -47,8 +47,45 @@ Notes
>  
>  6. CONFIG_ARM64 instead of CONFIG_ARMV8 is used to distinguish aarch64 and
>     aarch32 specific codes.
>  
> +MMU
> +---
> +
> +U-Boot uses a simple page table for MMU setup. It uses the smallest number of bits
> +possible for the virtual address based on the maximum memory address (see the logic
> +in ``get_tcr()``).
> +
> +As with all platforms, U-Boot on ARM64 uses a 1:1 mapping of virtual to physical addresses.
> +In general, the memory map is expected to remain static once the MMU is enabled.
> +
> +It is possible to debug the pagetable generated by U-Boot with the built in
> +``dump_pagetable()`` and ``walk_pagetable()`` functions (the former being a simple
> +wrapper for the latter). For example the following can be added to ``setup_all_pgtables()``
> +after the first call to ``setup_pgtables()``:
> +
> +.. code-block:: c
> +
> +    dump_pagetable(gd->arch.tlb_addr, get_tcr(NULL, NULL));
> +
> +This will result in a print like the following:
> +
> +.. code-block:: text
> +
> +    Walking pagetable at 000000017df90000, va_bits: 36. Using 3 levels
> +    [0x17df91000]                   |  Table |               |
> +      [0x17df92000]                 |  Table |               |
> +        [0x000001000 - 0x000200000] |  Pages | Device-nGnRnE | Non-shareable
> +      [0x000200000 - 0x040000000]   |  Block | Device-nGnRnE | Non-shareable
> +    [0x040000000 - 0x080000000]     |  Block | Device-nGnRnE | Non-shareable
> +    [0x080000000 - 0x140000000]     |  Block | Normal        | Inner-shareable
> +    [0x17df93000]                   |  Table |               |
> +      [0x140000000 - 0x17de00000]   |  Block | Normal        | Inner-shareable
> +      [0x17df94000]                 |  Table |               |
> +        [0x17de00000 - 0x17dfa0000] |  Pages | Normal        | Inner-shareable
> +
> +For more information, please refer to the function documentation in
> +``arch/arm/include/asm/armv8/mmu.h``.

Since the function comments are kernel-doc style, can you please rework
this to leverage "kernel-doc::" and make sure it renders nicely? And
this may show we should be putting some function comments in 2/3 of this
series as well.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]