[PATCH RFC] doc: Document address spaces used by U-Boot

[Jiaxun Yang]

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 at 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 at 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,
-- 
Jiaxun Yang <jiaxun.yang at flygoat.com>