This serves as a reference for developers on how to handle all those address spaces for U-Boot.
Signed-off-by: Jiaxun Yang jiaxun.yang@flygoat.com --- Hi all,
I was trying to clear up long standing myth of virtual address vs physical adddress mapping on MIPS by having a clear division betweem virt and phys adddress everywhere.
In this process I would like to confirm my understanding by writing a document and requesting comments from the community.
Note that there are some sysmem APIs mentioned in the document are not in U-Boot tree, namely ``sysmem_addr_t`` and sysmem_to_phys co. I think they can help with annotating address spaces.
Please kindly comment on the design.
Thanks! --- doc/develop/address_spaces.rst | 73 ++++++++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 74 insertions(+)
diff --git a/doc/develop/address_spaces.rst b/doc/develop/address_spaces.rst new file mode 100644 index 000000000000..05c4a1575f27 --- /dev/null +++ b/doc/develop/address_spaces.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2024 Jiaxun Yang jiaxun.yang@flygoat.com + +Address Spaces +============== + +Introduction +------------ + +In U-Boot, we have three address spaces that are used to describe a memory +address: + + - ``virt``: virtual address space + - ``phys``: physical address space + - ``sysmem``: system memory address space + +On most architectures, we maintain a 1:1:1 mapping between all three address, +with the exception of MIPS and sandbox. + +There are many API misused in existing code base, this document is to clarify +the usage of these address spaces and APIs. Hopefully it will help to reduce +the confusion and porting effort. + +``virt`` +-------- + +This is the address space that is directly used by U-Boot to access memory. +Every pointer in U-Boot must in ``virt`` address space. to get a valid ``virt`` +address from any other address space, you must use relavant mapping functions +to ensure it's being tracked. It is recomanded to use ``ulong`` or pointer types +to store ``virt`` address. + +``phys`` +-------- + +This is the address space that is used to describe the physical memory address. +It's used to describe the physical memory address of a device, or the physical +memory address of a memory region. Usual places you would see ``phys`` address +are addresses comes from Device Tree and some memory related APIs. It is +recommended to use ``fdt_addr_t`` or ``phys_addr_t`` to store ``phys`` address. + +Following APIs are availble to handle ``phys`` address: + + - ``map_physmem()``: Create mapping from physical address to virtual address + - ``unmap_physmem()``: Remove mapping created by ``map_physmem()`` + - ``virt_to_phys()``: Find physical address mapping for a virtual address + - ``ioremap()``: Create mapping for I/O memory region + - ``iounmap()``: Remove mapping created by ``ioremap()`` + +``sysmem`` +---------- + +This is the address space that is used by U-Boot internally to describe RAM +address. It helps to abstract some architecture differences and provide a +consistent way to managed RAM. Usual places you would see ``sysmem`` address +are addresses comes from ``gd->bd->bi_dram[]``, addresses comes from ``LMB`` +addresses being used as memory related config optinos, and addresses being +used as arguments to load commands. It is recommended to use ``sysmem_addr_t`` +to store ``sysmem`` address. + +It is further used by sandbox to simulate memory, and by MIPS to handle +differences between ``virt`` and ``phys`` address spaces. + +Following APIs are availble to handle ``sysmem`` address: + + - ``map_sysmem()``: Create mapping from system memory address to virtual address + - ``unmap_sysmem()``: Remove mapping created by ``map_sysmem()`` + - ``map_to_sysmem()``: Find system memory address mapping for a virtual address + - ``sysmem_to_phys()``: Find physical address mapping for a system memory address + - ``phys_to_sysmem()``: Find system memory address mapping for a physical address + - ``nomap_sysmem()``: Pass through an address unchanged (For sandbox tracking) + - ``nomap_to_sysmem()``: Pass through an address unchanged + diff --git a/doc/develop/index.rst b/doc/develop/index.rst index f82e148b101c..1b8e11cd2f24 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -27,6 +27,7 @@ Implementation .. toctree:: :maxdepth: 1
+ address_spaces directories bloblist bootstd
--- base-commit: ad7dce5abd49ef3b5c93da5303e15449c8c162b4 change-id: 20240517-address-spaces-1c3b9c379b13
Best regards,