* [PATCH v2 1/4] Documentation: devel: porting: split out architecture intro
2025-07-11 7:32 [PATCH v2 0/4] Documentation: devel: add new troubleshooting Ahmad Fatoum
@ 2025-07-11 7:32 ` Ahmad Fatoum
2025-07-11 7:32 ` [PATCH v2 2/4] Documentation: devel: architecture: detail first/second stage handling Ahmad Fatoum
` (2 subsequent siblings)
3 siblings, 0 replies; 5+ messages in thread
From: Ahmad Fatoum @ 2025-07-11 7:32 UTC (permalink / raw)
To: barebox; +Cc: Ahmad Fatoum
In preparation for adding a debugging chapter, move the parts in the
porting guide that are equally applicable to debugging to its separate
file, so they can be referenced easily.
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
v1 -> v2:
- no change
---
Documentation/devel/architecture.rst | 78 ++++++++++++++++++++++++++
Documentation/devel/porting.rst | 83 +++-------------------------
2 files changed, 85 insertions(+), 76 deletions(-)
create mode 100644 Documentation/devel/architecture.rst
diff --git a/Documentation/devel/architecture.rst b/Documentation/devel/architecture.rst
new file mode 100644
index 000000000000..83556095098a
--- /dev/null
+++ b/Documentation/devel/architecture.rst
@@ -0,0 +1,78 @@
+.. _architecture:
+
+####################
+barebox architecture
+####################
+
+The usual barebox binary consists of two parts. A prebootloader doing
+the bare minimum initialization and then the proper barebox binary.
+
+barebox proper
+==============
+
+This is the main part of barebox and, like a multi-platform Linux kernel,
+is platform-agnostic: The program starts, registers its drivers and tries
+to match the drivers with the devices it discovers at runtime.
+It initializes file systems and common management facilities and finally
+starts an init process. barebox knows no privilege separation and the
+init process is built into barebox.
+The default init is the :ref:`Hush`, but can be overridden if required.
+
+For such a platform-agnostic program to work, it must receive external
+input about what kind of devices are available: For example, is there a
+timer? At what address and how often does it tick? For most barebox
+architectures this hardware description is provided in the form
+of a flattened device tree (FDT). As part of barebox' initialization
+procedure, it unflattens (parses) the device tree and starts probing
+(matching) the devices described within with the drivers that are being
+registered.
+
+The device tree can also describe the RAM available in the system. As
+walking the device tree itself consumes RAM, barebox proper needs to
+be passed information about an initial memory region for use as stack
+and for dynamic allocations. When barebox has probed the memory banks,
+the whole memory will become available.
+
+As result of this design, the same barebox proper binary can be reused for
+many different boards. Unlike Linux, which can expect a bootloader to pass
+it the device tree, barebox *is* the bootloader. For this reason, barebox
+proper is prefixed with what is called a prebootloader (PBL). The PBL
+handles the low-level details that need to happen before invoking barebox
+proper.
+
+Prebootloader (PBL)
+===================
+
+The :ref:`prebootloader <pbl>` is a small chunk of code whose objective is
+to prepare the environment for barebox proper to execute. This means:
+
+ - Setting up a stack
+ - Determining a memory region for initial allocations
+ - Provide the device tree
+ - Jump to barebox proper
+
+The prebootloader often runs from a constrained medium like a small
+(tens of KiB) on-chip SRAM or sometimes even directly from flash.
+
+If the size constraints allow, the PBL will contain the barebox proper
+binary in compressed form. After ensuring any external DRAM can be
+addressed, it will unpack barebox proper there and call it with the
+necessary arguments: an initial memory region and the FDT.
+
+If this is not feasible, the PBL will contain drivers to chain load
+barebox proper from the storage medium. As this is usually the same
+storage medium the PBL itself was loaded from, shortcuts can often
+be taken: e.g. a SD-Card could already be in the correct mode, so the
+PBL driver can just read the blocks without having to reinitialize
+the SD-card.
+
+barebox images
+==============
+
+In a typical build, the barebox build process generates multiple images
+(:ref:`multi_image`). All enabled PBLs are each linked with the same
+barebox proper binary and then the resulting images are processed to be
+in the format expected by the loader.
+
+The loader is often a BootROM, but maybe another first stage bootloader
+or a hardware debugger.
diff --git a/Documentation/devel/porting.rst b/Documentation/devel/porting.rst
index 9dab2a301f2a..88847f42a8f7 100644
--- a/Documentation/devel/porting.rst
+++ b/Documentation/devel/porting.rst
@@ -15,83 +15,14 @@ about porting barebox to new hardware.
Introduction
************
-Your usual barebox binary consists of two parts. A prebootloader doing
-the bare minimum initialization and then the proper barebox binary.
+Before starting your barebox port, you'll want to familiarize yourself with
+key concepts of the :ref:`barebox architecture <architecture>` namely the
+prebootloader, barebox proper and the multi-image support.
-barebox proper
-==============
-
-This is the main part of barebox and, like a multi-platform Linux kernel,
-is platform-agnostic: The program starts, registers its drivers and tries
-to match the drivers with the devices it discovers at runtime.
-It initializes file systems and common management facilities and finally
-starts an init process. barebox knows no privilege separation and the
-init process is built into barebox.
-The default init is the :ref:`Hush`, but can be overridden if required.
-
-For such a platform-agnostic program to work, it must receive external
-input about what kind of devices are available: For example, is there a
-timer? At what address and how often does it tick? For most barebox
-architectures this hardware description is provided in the form
-of a flattened device tree (FDT). As part of barebox' initialization
-procedure, it unflattens (parses) the device tree and starts probing
-(matching) the devices described within with the drivers that are being
-registered.
-
-The device tree can also describe the RAM available in the system. As
-walking the device tree itself consumes RAM, barebox proper needs to
-be passed information about an initial memory region for use as stack
-and for dynamic allocations. When barebox has probed the memory banks,
-the whole memory will become available.
-
-As result of this design, the same barebox proper binary can be reused for
-many different boards. Unlike Linux, which can expect a bootloader to pass
-it the device tree, barebox *is* the bootloader. For this reason, barebox
-proper is prefixed with what is called a prebootloader (PBL). The PBL
-handles the low-level details that need to happen before invoking barebox
-proper.
-
-Prebootloader (PBL)
-===================
-
-The :ref:`prebootloader <pbl>` is a small chunk of code whose objective is
-to prepare the environment for barebox proper to execute. This means:
-
- - Setting up a stack
- - Determining a memory region for initial allocations
- - Provide the device tree
- - Jump to barebox proper
-
-The prebootloader often runs from a constrained medium like a small
-(tens of KiB) on-chip SRAM or sometimes even directly from flash.
-
-If the size constraints allow, the PBL will contain the barebox proper
-binary in compressed form. After ensuring any external DRAM can be
-addressed, it will unpack barebox proper there and call it with the
-necessary arguments: an initial memory region and the FDT.
-
-If this is not feasible, the PBL will contain drivers to chain load
-barebox proper from the storage medium. As this is usually the same
-storage medium the PBL itself was loaded from, shortcuts can often
-be taken: e.g. a SD-Card could already be in the correct mode, so the
-PBL driver can just read the blocks without having to reinitialize
-the SD-card.
-
-barebox images
-==============
-
-In a typical build, the barebox build process generates multiple images
-(:ref:`multi_image`). All enabled PBLs are each linked with the same
-barebox proper binary and then the resulting images are processed to be
-in the format expected by the loader.
-
-The loader is often a BootROM, but maybe another first stage bootloader
-or a hardware debugger.
-
-Let us now put these new concepts into practice. We will start by adding
-a new board for a platform, for which similar boards already exist.
-Then we'll look at adding a new SoC, then a new SoC family and finally
-a new architecture.
+Once you've read through, let us now put these new concepts into practice.
+We will start by adding a new board for a platform, for which similar boards
+already exist. Then we'll look at adding a new SoC, then a new SoC family
+and finally a new architecture.
**********************
Porting to a new board
--
2.39.5
^ permalink raw reply [flat|nested] 5+ messages in thread* [PATCH v2 2/4] Documentation: devel: architecture: detail first/second stage handling
2025-07-11 7:32 [PATCH v2 0/4] Documentation: devel: add new troubleshooting Ahmad Fatoum
2025-07-11 7:32 ` [PATCH v2 1/4] Documentation: devel: porting: split out architecture intro Ahmad Fatoum
@ 2025-07-11 7:32 ` Ahmad Fatoum
2025-07-11 7:32 ` [PATCH v2 3/4] Documentation: user: split community from feedback Ahmad Fatoum
2025-07-11 7:32 ` [PATCH v2 4/4] Documentation: devel: troubleshooting: add new chapter Ahmad Fatoum
3 siblings, 0 replies; 5+ messages in thread
From: Ahmad Fatoum @ 2025-07-11 7:32 UTC (permalink / raw)
To: barebox; +Cc: Ahmad Fatoum
barebox is at mercy of the BootROM in relation to how its first/second
stages need to be structured. In the optimal case, the user need not
about it, but when issues arises, it becomes very important to know
_where_ the issue occurs.
Let's add some general background information about that.
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
v1 -> v2:
- no change
---
Documentation/devel/architecture.rst | 136 +++++++++++++++++++++++++--
1 file changed, 129 insertions(+), 7 deletions(-)
diff --git a/Documentation/devel/architecture.rst b/Documentation/devel/architecture.rst
index 83556095098a..b557ec830dc7 100644
--- a/Documentation/devel/architecture.rst
+++ b/Documentation/devel/architecture.rst
@@ -60,19 +60,141 @@ addressed, it will unpack barebox proper there and call it with the
necessary arguments: an initial memory region and the FDT.
If this is not feasible, the PBL will contain drivers to chain load
-barebox proper from the storage medium. As this is usually the same
-storage medium the PBL itself was loaded from, shortcuts can often
-be taken: e.g. a SD-Card could already be in the correct mode, so the
-PBL driver can just read the blocks without having to reinitialize
-the SD-card.
+barebox proper from the storage medium, usually the same
+storage medium the PBL itself was loaded from.
barebox images
==============
In a typical build, the barebox build process generates multiple images
-(:ref:`multi_image`). All enabled PBLs are each linked with the same
-barebox proper binary and then the resulting images are processed to be
+(:ref:`multi_image`). Normally, all enabled PBLs are each linked with the
+same barebox proper binary and then the resulting images are processed to be
in the format expected by the loader.
The loader is often a BootROM, but maybe another first stage bootloader
or a hardware debugger.
+
+Ideally, a single image is all that's needed to boot into barebox.
+Depending on BootROM, this may not be possible, because the BootROM hardcodes
+assumptions about the image that it loads. This is often the case with
+BootROMs that boot from a file system (often FAT): They expect a ``BOOT.BIN``
+file, ``MLO`` or similarly named file that does not exceed a fixed file size,
+because that file needs to be loaded into the small on-chip SRAM available on
+the SoC. In such cases, most barebox functionality will be located in a separate
+image, e.g. ``barebox.bin``, which is loaded by ``BOOT.BIN``, once DRAM has
+been successfully set up.
+
+There are two ways we generate such small first stage bootloaders in barebox:
+
+Old way: ≥ 2 configs
+---------------------
+
+The old way is to have a dedicated barebox first stage config that builds a
+very small non-interactive barebox for use as first stage.
+Due to size constraints, the first stage config is usually board-specific, while
+the second-stage config can target multiple boards at once.
+
+In this setup, each of the first and second stage each consist of their own
+prebootloader and barebox proper.
+
+* first stage prebootloader: Does DRAM setup and extracts first stage
+ barebox proper into DRAM.
+
+* first stage barebox proper: runs in DRAM and chainloads the second stage binary.
+
+* first stage prebootloader: is already running in DRAM, so it doesn't need to do
+ any hardware setup and instead directly extract second stage barebox proper
+
+* second stage barebox proper: your usual barebox experience, which can have an
+ interactive shell and boot an operating system
+
+An Example for this is ``am335x_mlo_defconfig``.
+
+New way: single config
+----------------------
+
+The new way avoids having a dedicated barebox first stage config by doing both
+the low level first stage setup and the chainloading from the same barebox
+prebootloader. Despite the prebootloader lacking nearly all driver frameworks found
+in barebox proper this is often made possible by reusing the hardware set up
+by the BootROM:
+
+BootROMs usually don't deinitialize hardware before jumping to the first stage
+bootloader. That means that the barebox prebootloader could just keep reusing
+the pre-configured SD-Card and host controller for example and issue read block
+commands right away without having to reinitialize the SD-card.
+
+In this setup, only one prebootloader binary will be built. Depending on
+the bootflow defined by the BootROM, it may be executed more than once however:
+
+BootROM loads directly into DRAM
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some BootROMs have built-in support for executing multiple programs and
+loading them to different locations. In that case, a full second stage
+barebox binary can be loaded as second stage with the first stage RAM
+setup handled outside barebox.
+
+An example for Mask ROM loading one image into SRAM and another afterwards
+into DRAM are the boards in ``rockchip_v8_defconfig``: A DRAM setup blob
+is loaded as first stage followed by barebox directly into DRAM as second
+stage.
+
+A slightly different example are what most boards in ``imx_v7_defconfig``
+are doing: The i.MX bootrom can execute the bytecode located in the DCD
+(Device Configuration Data) table that's part of the bootloader header.
+This byte code has simple memory read/write and control flow primitives
+that are sufficient to setup a DDR2/DDR3 DRAM, so that barebox can be
+loaded into it right away.
+
+The option of being loaded into SRAM first and chainloading from there
+is also available, but not used frequently for the 32-bit i.MX platforms.
+For the 64-bit platforms with (LP)DDR4, the RAM controller setup is
+too complex to express with DCD opcodes, leading to the approach described
+below.
+
+BootROM loads into SRAM from offset
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For BootROMs, where the first stage bootloader is loaded from a raw offset
+on the boot medium, the barebox image is usually a single binary, which
+is processed as follows:
+
+* The BootROM reads the first X bytes containing the prebootloader (and
+ some truncated barebox proper content) into the on-chip SRAM and executes
+ it.
+
+* The prebootloader will set up DRAM and then chainload the whole of barebox
+ proper into it. The offset and size of barebox proper are compiled into
+ the PBL, so it knows where to look.
+
+* The prebootloader will then invoke itself again, but this time while running
+ from DRAM. The re-executed prebootloader detects that it's running in DRAM
+ or at a lower exception level and will then proceed to extract barebox
+ proper to the end of the initial memory region and execute it.
+
+And example for this is the ``imx_v8_defconfig``.
+
+.. note:: Some SoCs like the i.MX8M Nano and Plus provide a boot API in ROM
+ that can be used by the prebootloader to effortlessly chainload the second stage
+ cutting down complexity in the prebootloader greatly. Thanks BootROM authors!
+
+BootROM loads into SRAM from file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the BootROM expects a file, it most often does a size check,
+necessitating a second binary for the whole of barebox proper.
+
+The boot flow then looks as follows:
+
+* The BootROM reads the first binary, which includes only the prebootloader
+ from the file system into on-chip SRAM and executes it
+
+* The prebootloader will set up DRAM and then load the second binary
+ into it. It has no knowledge of its offsets and sizes, but gets that
+ information out of the FAT filesystem.
+
+* The second stage binary contains both its own prebootloader and a barebox
+ binary. The second stage prebootloader does not need to do any special
+ hardware setup, so it will proceed to extract barebox proper to the end of
+ the initial memory region and execute it.
--
2.39.5
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH v2 3/4] Documentation: user: split community from feedback
2025-07-11 7:32 [PATCH v2 0/4] Documentation: devel: add new troubleshooting Ahmad Fatoum
2025-07-11 7:32 ` [PATCH v2 1/4] Documentation: devel: porting: split out architecture intro Ahmad Fatoum
2025-07-11 7:32 ` [PATCH v2 2/4] Documentation: devel: architecture: detail first/second stage handling Ahmad Fatoum
@ 2025-07-11 7:32 ` Ahmad Fatoum
2025-07-11 7:32 ` [PATCH v2 4/4] Documentation: devel: troubleshooting: add new chapter Ahmad Fatoum
3 siblings, 0 replies; 5+ messages in thread
From: Ahmad Fatoum @ 2025-07-11 7:32 UTC (permalink / raw)
To: barebox; +Cc: Ahmad Fatoum
Place the Matrix/IRC links more prominently by moving them above the
information for how to send patches.
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
v1 -> v2:
- new patch
---
Documentation/user/introduction.rst | 19 ++++++++++++-------
1 file changed, 12 insertions(+), 7 deletions(-)
diff --git a/Documentation/user/introduction.rst b/Documentation/user/introduction.rst
index cba1d09986b8..5b2a39f3c5c3 100644
--- a/Documentation/user/introduction.rst
+++ b/Documentation/user/introduction.rst
@@ -15,10 +15,10 @@ development binary as well as for lean production systems.
Just like busybox is the Swiss Army Knife for embedded Linux,
barebox is the Swiss Army Knife for bare metal, hence the name.
-.. _feedback:
+.. _community:
-Feedback
---------
+Community
+---------
For sending patches, asking for help and giving general feedback you are
always welcome to write an e-mail to the barebox mailing list at
@@ -31,6 +31,15 @@ Mails sent to the barebox mailing list are archived on
`lore.barebox.org <https://lore.barebox.org/barebox/>`_ and
`lore.kernel.org <https://lore.kernel.org/barebox/>`_.
+There's also an IRC channel, which is
+`bridged to Matrix <https://app.element.io/#/room/#barebox:matrix.org>`_:
+#barebox on Libera Chat.
+
+.. _feedback:
+
+Sending Patches
+---------------
+
barebox uses a similar patch process as the Linux kernel, so most of the
`Linux guide for submitting patches <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_
also applies to barebox, except for the need to select your recipient;
@@ -48,7 +57,3 @@ and have ``FETCH_HEAD`` point at it::
CI tests are executed by Github Actions can be used by forking
`the project on Github <https://github.com/barebox/barebox>`.
-
-There's also an IRC channel, which is
-`bridged to Matrix <https://app.element.io/#/room/#barebox:matrix.org>`_:
-#barebox on Libera Chat.
--
2.39.5
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH v2 4/4] Documentation: devel: troubleshooting: add new chapter
2025-07-11 7:32 [PATCH v2 0/4] Documentation: devel: add new troubleshooting Ahmad Fatoum
` (2 preceding siblings ...)
2025-07-11 7:32 ` [PATCH v2 3/4] Documentation: user: split community from feedback Ahmad Fatoum
@ 2025-07-11 7:32 ` Ahmad Fatoum
3 siblings, 0 replies; 5+ messages in thread
From: Ahmad Fatoum @ 2025-07-11 7:32 UTC (permalink / raw)
To: barebox; +Cc: Ahmad Fatoum
A consequence of running bare metal is that early failures are difficult
to diagnose. Let's add a troubleshooting section to help users take
the first step in diagnosing issues.
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
v1 -> v2:
- Fix various typos (Ulrich)
- Usage components for PBL/proper instead of stages
- Move DEBUG_LL and DEBUG_INITCALLS into separate section at
the very top. This is the most relevant
- Add Symptoms to all sections
- Expand on the Driver Probe Stage
- Reference ML/Matrix
---
Documentation/devel/devel.rst | 2 +
Documentation/devel/troubleshooting.rst | 465 ++++++++++++++++++++++++
Documentation/devicetree/index.rst | 2 +
3 files changed, 469 insertions(+)
create mode 100644 Documentation/devel/troubleshooting.rst
diff --git a/Documentation/devel/devel.rst b/Documentation/devel/devel.rst
index d985bff40d42..b90805263bbd 100644
--- a/Documentation/devel/devel.rst
+++ b/Documentation/devel/devel.rst
@@ -8,7 +8,9 @@ Contents:
.. toctree::
:maxdepth: 2
+ architecture
porting
+ troubleshooting
filesystems
background-execution
project-ideas
diff --git a/Documentation/devel/troubleshooting.rst b/Documentation/devel/troubleshooting.rst
new file mode 100644
index 000000000000..8e31148b9c06
--- /dev/null
+++ b/Documentation/devel/troubleshooting.rst
@@ -0,0 +1,465 @@
+.. _troubleshooting:
+
+##########################
+Boot Troubleshooting Guide
+##########################
+
+Especially during development or bring-up, very early failure situations can leave
+the system hanging before recovery is even possible.
+
+This guide helps diagnose and debug such issues across barebox' different boot stages.
+
+Boot Flow Overview
+==================
+
+A barebox binary consists of two main components:
+
+1. **PBL (Pre-Bootloader)**: This is a smaller barebones loader that does
+ what's necessary to download the full barebox binary.
+ At the very least, this is decompressing barebox proper and jumping
+ to it while passing it a device tree.
+ Depending on platform, it may also need to setup DRAM, install a secure
+ monitory like TF-A or a secure operating system like OP-TEE and chainload
+ barebox from a boot medium.
+2. **barebox proper**: The main bootloader logic. This is always loaded
+ by a prebootloader passing a device tree and including drivers for
+ device initialization, environment setup, and booting the OS.
+
+Refer to the :ref:`barebox architecture <architecture>` for more background
+information on the two components and how they map to different boot stages
+and images.
+
+If barebox hangs, it's essential to identify *where* at which boot stage,
+this failure occurs:
+
+- Does the hang happen in the first stage, i.e., while executing from
+ on-chip SRAM?
+
+- Or does the hang happen while in the second stage, i.e., while executing
+ from external SDRAM?
+
+And also which component in barebox is affected:
+
+- Is the issue in the prebootloader?
+
+- Or is barebox proper already loaded and started?
+
+Enable Earlier Console Output
+=============================
+
+Before delving deeper into debugging, make sure to enable following
+options:
+
+- Enable ``CONFIG_DEBUG_LL``
+
+ This enables very early low-level UART debugging.
+ It bypasses console frameworks and writes directly to UART registers.
+ Many boards in barebox, print a ``>`` character, when ``CONFIG_DEBUG_LL``
+ is enabled. If you see such a character after enabling ``DEBUG_LL``, it
+ indicates that the barebox prebootloader has been found and control was
+ successfully handed over to it. Note that on some SoCs, ``DEBUG_LL``
+ requires co-operation from the board entry point, e.g., the pin muxing for
+ the serial console needs to be done in software in some situations before
+ the UART is accessible from the outside.
+
+ .. note::
+ Make sure the correct UART index or address is selected under
+ **Kernel low-level debugging por** in ``menuconfig``.
+ Configuring the wrong UART might hang your system, because barebox would
+ be tricked into accessing hardware that's not there or is powered off.
+ The numbering/addresses of ports are described in the System-on-Chip
+ datasheet or reference manual and may differ from labels on the hardware.
+ Refer to the config symbol help text and ``/chosen/stdout-path`` in the
+ device tree if unsure.
+
+- Enable ``CONFIG_DEBUG_INITCALLS`` while ``CONFIG_DEBUG_LL`` is enabled
+
+ This shows output for each initcall level, helping pinpoint where execution stops.
+ ``CONFIG_DEBUG_LL`` is useful here, because it allows showing output, even
+ before the first serial driver is probed.
+
+- If you still don't see any output besides an early ``>`` or ``a``
+ character, enable ``CONFIG_PBL_CONSOLE`` and ``CONFIG_DEBUG_PBL``
+
+ For boards that don't have an early ``putc_ll('>');``, the first output
+ being printed is often the debugging output from the ``uncompress.c``
+ entry point (``barebox_pbl_start()``). Enable these options to see if
+ the CPU gets that far.
+
+ .. warning::
+ CONFIG_DEBUG_PBL increases the size of the PBL, which can make it
+ exceed a hard limit imposed by a previous stage bootloader.
+ Best case, this will be caught by the build system, but might not
+ if you are adding a new board and haven't told it yet.
+
+The following sections each start with a list of symptoms, common problems
+that cause them and what to try to debug them. Skip the sections that don't
+align with your symptoms.
+
+Completely Silent Console
+=========================
+
+Even the barebox prebootloader is most often loaded by another
+bootloader. This is commonly a mask BootROM hardwired into the
+System-on-Chip.
+
+**Symptoms**:
+
+- Despite enabling the config options described in the previous
+ section, the console is fully silent.
+
+**Common problems**:
+
+- Wrong bootloader image or format
+- Bootloader installed to wrong location
+- System hang before serial driver probe
+- Enabled, but misconfigured CONFIG_DEBUG_LL
+
+**What to try**:
+
+- Check for BootROM boot indicators:
+
+ Some BootROMs (e.g. AT91) write to a serial port when they start up
+ or blink a GPIO (e.g. STM32MP) if they fail to boot the next stage
+ bootloader.
+
+- Check that barebox is in the format and at the location that the
+ previous stage bootloader expects.
+
+ Compare with a previously working bootloader image, refer to the
+ barebox documentation and/or the vendor documentation or ask around.
+
+- Output a character from the entry point
+
+ If you don't have any calls to ``putc_ll`` already, you can stick
+ your own ``putc_ll('>');`` there and see if it makes it to the
+ serial port. Compare with other boards to see what initialization
+ is needed for a serial port (pinmux, clocks, baudrate, ...etc.)
+
+- Toggle a GPIO from the board entry point
+
+ A number of platforms (e.g. i.MX or STM32MP) have header-only GPIO helper
+ functions that can be used to toggle a GPIO. These can be used for
+ debugging early hangs by toggling an LED for example.
+
+- Trace BootROM activity
+
+ If you have no indication that the barebox prebootloader is being started,
+ consider tracing what the BootROM is doing, e.g. via JTAG or a logic analyzer
+ for the SD card.
+
+If you managed to get some way to output debug info, move along to the
+next step.
+
+Hang after First Stage PBL Console Output
+=========================================
+
+The first stage prebootloader handles:
+- Basic initialization (e.g., clocks, SDRAM)
+- Installation of secure firmware if applicable
+- Invocation of the second stage
+
+**Symptoms**:
+
+- You see some output from the prebootloader, but you don't see
+ any debug messages starting with ``uncompress.c:``.
+
+**Common problems**:
+
+- Issues in board entry point
+- Hang in firmware
+
+**What to try**:
+
+- Check where hang occurs
+
+ If you get just some early output, you'll need to pinpoint, where the issue
+ occurs. If enabling ``CONFIG_PBL_CONSOLE`` along with a correctly configured
+ ``CONFIG_DEBUG_PBL`` doesn't help, try adding ``putc_ll('@')`` (or any other
+ character) to find out, where the startup is stuck. ``putc_ll`` has the
+ benefit of being usable everywhere, even before ``setup_c()`` is or
+ ``relocate_to_current_adr()`` is called. Once these are called, you may
+ also use ``puts_ll()`` or just normal ``printf`` if ``CONFIG_PBL_CONSOLE=y``.
+
+- Check if hang occurs in other loaded firmware
+
+ On platforms like i.MX8/9 and RK35xx, barebox will install ARM trusted
+ firmware as secure monitor and possibly OP-TEE as secure OS.
+ Hangs can happen if TF-A or OP-TEE is configured to access the wrong
+ console (hang/abort on accessing peripheral with gated clock).
+ If output ends with the banner of the firmware, jumping back to barebox
+ may have failed. In that case, double check that the memory size
+ configured for TF-A/OP-TEE is correct and that the entry addresses
+ used in barebox and TF-A/OP-TEE are identical.
+
+Hang During Chainloading
+========================
+
+Once basic system initialization is done, barebox prebootloader
+will load the second stage.
+
+**Symptoms**:
+
+- You see debug messages starting with ``uncompress.c:``, but
+ none that start with ``start.c:``
+
+**Common problems**:
+
+- Wrong SDRAM setup
+- Corrupted barebox proper read from boot medium
+
+**What to try**:
+
+- Check computed addresses
+
+ If your last output is ``jumping to uncompressed image``, this suggests that
+ the hang occurred while trying to execute barebox proper. barebox prints
+ the regions it uses for its stack, barebox itself and the initial RAM
+ as debug output. Verify these with the actual size of RAM installed and
+ check if values are sane.
+
+- Check that barebox was loaded correctly
+
+ You can enable ``CONFIG_COMPILE_TEST`` and ``CONFIG_PBL_VERIFY_PIGGY``
+ to have the barebox build system compute a hash of barebox proper,
+ which the prebootloader will compare against the hash it computes
+ over the compressed data read from the boot medium.
+
+- Check SDRAM setup
+
+ SDRAM setup differs according to the RAM chip being used, the System-on-Chip,
+ the PCB traces between them as well as outside factors like temperature.
+ When a System-on-Module is used, the hardware vendor will optimally provide
+ a validated RAM setup to be used. If RAM layout is custom, the System-on-Chip
+ vendor usually provides tools for calculating initial timings and tuning them
+ at runtime.
+
+ Because writes can be posted, issues with wrongly set up SDRAM may only become
+ apparent on first execution or read and not during mere writing.
+
+ Issues of writes silently misbehaving should be detectable by
+ ``CONFIG_PBL_VERIFY_PIGGY``, which reads back the data to hash it.
+
+ If the prebootloader is already running from SDRAM, boot hangs due to completely
+ wrong SDRAM setup are less likely, but running a memory test from within barebox
+ proper is still recommended.
+
+- Check if an exception happened
+
+ barebox can print symbolized stack traces on exceptions, but support for that
+ is only installed in barebox proper. Early exceptions are currently not enabled
+ by default, but can be enabled manually with ``CONFIG_ARM_EXCEPTIONS_PBL``.
+
+Preinitcall Stage
+=================
+
+The prebootloader ``barebox_pbl_start`` ends up calling ``barebox_non_pbl_start``
+in barebox proper. This function does:
+
+- relocation and setting up the C environment
+- setting up the ``malloc()`` area and KASAN
+- calling ``start_barebox``, which runs the registered initcalls
+
+**Symptoms**:
+
+- You see debug messages starting with ``start.c:``, but none that start
+ with ``initcall->``
+
+**Common problems**:
+
+- None, this is quite straight-forward code
+
+**What to try**:
+
+- Check if the code is executed. This can be done with ``putc_ll``. ``printf``
+ is not safe to use everywhere in this function, because the C environment
+ may not be set up yet.
+
+Initcall Stage
+==============
+
+After decompression and jumping to barebox proper, barebox will walk through
+the compiled in initcalls.
+
+**Symptoms**:
+
+- You see debug messages starting with ``initcall->``, but system hangs before
+ reaching a shell
+
+**Common problems**:
+
+- Hangs during hardware initialization
+
+**What to try**:
+
+- Enable ``CONFIG_DEBUG_PROBES``
+
+ Initcalls don't necessarily correspond to driver probes as a driver may be
+ registered before a device or the device probe is postponed until resources
+ become available.
+
+ This option prints each driver probe attempt and can help isolate the
+ problematic peripheral.
+
+- Check what was the last executed function was
+
+ Each ``initcall->`` log message is followed by a barebox function name.
+ Each ``probe->`` log message is followed by the name of the device about
+ to be probed.
+ This should make it possible to pinpoint where the hang occurred.
+
+- Add extra debugging in the file of the hang
+
+ You can add ``#define DEBUG`` at the start of any barebox file (before the
+ C headers!) to print out all debug messages for that file regardless of log
+ level.
+
+- Isolate where exactly the hang occurs
+
+ By spreading some ``pr_notice("%s:%d\n", __func__, __LINE__);`` around the
+ driver, you should be able to pinpoint what causes the hang.
+
+- Disable drivers selectively to see if a shell can be reached.
+
+ This allows you to see if the hang is a general problem or if it's only
+ caused by a single device driver.
+
+Interactive Console
+===================
+
+**Symptoms**:
+
+- You see output only with ``CONFIG_DEBUG_LL``, but not otherwise
+
+**Common problems**:
+
+- No consoles are enabled or the user is looking at the wrong console.
+
+**What to try**:
+
+- Enable ``CONFIG_CONSOLE_ACTIVATE_ALL``
+
+ Useful for testing. Instructs barebox proper to print out logs on all
+ console devices that it registers.
+
+- Enable ``CONFIG_CONSOLE_ACTIVATE_ALL_FALLBACK`` after figuring out correct console
+
+ This will fall back to activating all consoles, when no console was activated
+ by normal means (e.g., via the environment or the device tree
+ ``/chosen/stdout`` property).
+
+ This should make it easier to debug similar issues in future should you
+ run into them.
+
+Kernel Hang
+===========
+
+**Symptoms**:
+
+- Hang after a line like
+ ``Loaded kernel to 0x40000000, devicetree at 0x41730000``
+
+With kernel hangs, it's important to find out, whether the hang happens in barebox
+still or already while executing the kernel.
+Without EFI loader support in barebox, there is no calling back from kernel to barebox,
+so a kernel hanging is usually indicative of an issue within the kernel itself.
+
+It's often useful to copy the kernel image into ``/tmp`` instead of booting directly
+to verify that the hang is not just a very slow network connection for example.
+The ``-v`` option to :ref:`command_cp` is useful for that.
+The file size copied may differ from the original if the mean of transport rounds
+up to a specific block size. In that case, round up the size on the host system
+and run a digest function like :ref:`command_md5sum` to check that the image
+was transferred successfully.
+
+If the image is transferred correctly, the :ref:`command_boot` verbosity is increased
+by each extra ``-v`` option. At higher verbosity level, this will also print out
+the device tree passed to the kernel. The :ref:`command_of_diff` command is useful
+to :ref:`visualize only the fixups that were applied by barebox to the device tree<of_diff>`.
+
+If you are sure that the kernel is indeed being loaded, the ``earlycon`` kernel
+feature can enable early debugging output before kernel serial drivers are loaded.
+barebox can fixup an earlycon option if ``global.bootm.earlycon=1`` is specified.
+
+Spurious Aborts/Hangs
+=====================
+
+**Symptoms**:
+
+- Hangs/panics/aborts that happen in a non-deterministic fashion and whose
+ probability is greatly influenced by enabling/disabling barebox options
+ and corresponding shifts in the barebox binary
+
+It's generally advisable to run a memory test to verify basic operation and to check
+if the RAM size is sane. barebox provides two commands for this: :ref:`command_memtest`
+and :ref:`command_memtester`. In addition, some silicon vendors like NXP provide their
+own memory test blobs, which barebox can load to SRAM via :ref:`command_memcpy` and
+execute using :ref:`command_go`. By having the memory test outside DRAM, a much more
+thorough memory test is possible.
+
+With ``CONFIG_MMU=y``, the decompression of barebox proper in the prebootloader
+and the runtime of barebox proper will execute with MMU enabled for improved performance.
+
+This increase in performance is due to caches and speculative execution.
+barebox will mark memory mapped I/O devices and secure firmware as ineligible for
+being accessed speculatively, but it can only do so if the memory size it's told
+is correct and if secure memory is marked reserved in the device tree.
+
+The memory map as barebox sees it can be printed with the :ref:`command_iomem`
+command. Everything outside ``ram`` region is mapped non executable and uncacheable
+by default. Everything inside ``ram`` regions that doesn't have a ``[R]`` next
+to it is cacheable by default. The :ref:`command_mmuinfo` command can be used
+to show specific information about the MMU attributes for an address.
+
+Memory Corruption Issues
+========================
+
+Some hangs might be caused by heap corruption, stack overflows, or use-after-free bugs.
+
+**What to try**:
+
+- Enable ``CONFIG_KASAN`` (Kernel Address Sanitizer)
+
+ This provides runtime memory checking in barebox proper and can detect
+ invalid memory accesses.
+
+ .. warning::
+ KASAN gratly increases memory usage and may itself cause hangs in
+ constrained environments.
+
+
+Summary of Debug Options
+========================
+
++-----------------------------+-------------------------------------------------------+
+| Option | Description |
++=============================+=======================================================+
+| CONFIG_DEBUG_LL | Early low-level UART output |
++-----------------------------+-------------------------------------------------------+
+| CONFIG_PBL_CONSOLE | Print statements from PBL |
++-----------------------------+-------------------------------------------------------+
+| CONFIG_DEBUG_PBL | Enable all debug output in the PBL |
++-----------------------------+-------------------------------------------------------+
+| CONFIG_PBL_VERIFY_PIGGY | Verify barebox proper in PBL before decompression |
++-----------------------------+-------------------------------------------------------+
+| CONFIG_ARM_EXCEPTIONS_PBL | Enable exception handlers in PBL |
++-----------------------------+-------------------------------------------------------+
+| CONFIG_DEBUG_INITCALLS | Logs each initcall |
++-----------------------------+-------------------------------------------------------+
+| CONFIG_DEBUG_PROBES | Logs each driver probe |
++-----------------------------+-------------------------------------------------------+
+| CONFIG_KASAN | Detects memory corruption |
++-----------------------------+-------------------------------------------------------+
+
+Final Tips
+==========
+
+- Reach out to :ref:`other barebox users <community>`
+
+ Search the mailing list, send a mail yourself or ask on IRC/Matrix.
+
+- If all else fails, a JTAG debugger to single-step through the code can
+ be very useful. To help with this, ``CONFIG_PBL_BREAK`` triggers an
+ exception at the start of execution of the individual barebox stages,
+ which ``scripts/gdb/helper.py`` can use to correctly set the base
+ address, so symbols are correctly located.
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 94e8d04f63c3..4f25b6c6869b 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -175,6 +175,8 @@ In the ``chosen``-node, barebox fixes up
These values can be read from the booted linux system in ``/proc/device-tree/``
or ``/sys/firmware/devicetree/base``.
+.. _of_diff:
+
To see a dry run of what barebox would fixup, the ``of_diff`` command can be
used::
--
2.39.5
^ permalink raw reply [flat|nested] 5+ messages in thread