From: Jiaxun Yang <jiaxun.yang@flygoat.com>
To: u-boot@lists.denx.de
Cc: Tom Rini <trini@konsulko.com>, Simon Glass <sjg@chromium.org>,
Jiaxun Yang <jiaxun.yang@flygoat.com>
Subject: [PATCH RFC] doc: Document address spaces used by U-Boot
Date: Fri, 17 May 2024 12:45:17 +0100 [thread overview]
Message-ID: <20240517-address-spaces-v1-1-93e14c260b73@flygoat.com> (raw)
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,
--
Jiaxun Yang <jiaxun.yang@flygoat.com>
next reply other threads:[~2024-05-17 11:45 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-05-17 11:45 Jiaxun Yang [this message]
2024-05-18 8:08 ` [PATCH RFC] doc: Document address spaces used by U-Boot Heinrich Schuchardt
2024-05-18 11:35 ` Jiaxun Yang
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240517-address-spaces-v1-1-93e14c260b73@flygoat.com \
--to=jiaxun.yang@flygoat.com \
--cc=sjg@chromium.org \
--cc=trini@konsulko.com \
--cc=u-boot@lists.denx.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).