[PATCH 1/2] Documentation: troubleshooting: mention bootrom command

[PATCH 1/2] Documentation: troubleshooting: mention bootrom command

[Ahmad Fatoum]

The bootrom command is easily overlooked, but it's useful when debugging
BootROM refusing to boot on i.MX8M, so mention it.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/devel/troubleshooting.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/devel/troubleshooting.rst b/Documentation/devel/troubleshooting.rst
index f96b4d2b15ff..796f5eef4f13 100644
--- a/Documentation/devel/troubleshooting.rst
+++ b/Documentation/devel/troubleshooting.rst
@@ -142,6 +142,17 @@ System-on-Chip.
   functions that can be used to toggle a GPIO. These can be used for
   debugging early hangs by toggling an LED for example.
 
+- Inspect via fallback boot method
+
+  On some systems, a failure to boot from one boot medium causes the
+  BootROM to try a fallback. If the fallback can actually boot barebox,
+  you may be able to get more information once the shell is reached.
+  For example, if the BootROM refuses eMMC boot, is eMMC at least usable
+  from within barebox?
+  barebox can also decode BootROM logs on some SoCs via
+  :ref:`command_bootrom`, which can answer questions as whether the
+  BootROM even attempted access to the desired boot medium.
+
 - Trace BootROM activity
 
   If you have no indication that the barebox prebootloader is being started,
-- 
2.47.3

[PATCH 2/2] Documentation: troubleshooting: add debugging via built-in init scripts

[Ahmad Fatoum]

Trick is useful on occasion and might no be immediately obvious to
users, so mention it.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/devel/troubleshooting.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/devel/troubleshooting.rst b/Documentation/devel/troubleshooting.rst
index 796f5eef4f13..aed9870d6e46 100644
--- a/Documentation/devel/troubleshooting.rst
+++ b/Documentation/devel/troubleshooting.rst
@@ -363,6 +363,19 @@ Interactive Console
   This should make it easier to debug similar issues in future should you
   run into them.
 
+- Collect some more information
+
+  Even if you can't interactively type commands into the shell to introspect
+  the system, you can add an init script into the built-in environment to
+  run some commands. To do that, just place your shell script into
+  ``defaultenv/defaultenv-2-base/init/`` and rebuild.
+  Some useful commands to run:
+  - :ref:`command_dmesg` to replay the log, potentially with different log level
+  - :ref:`command_of_dump` if device tree description may be erroneous
+  - :ref:`command_clk_dump` if serial is missing due to clock issues
+  - :ref:`command_devinfo` to list the devices barebox knows about
+  - :ref:`command_iomem` to display the I/O memory map from barebox's point of view
+
 Kernel Hang
 ===========
 
-- 
2.47.3

[PATCH] fixup! Documentation: troubleshooting: add debugging via built-in init scripts

[Ahmad Fatoum]

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/devel/troubleshooting.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/devel/troubleshooting.rst b/Documentation/devel/troubleshooting.rst
index aed9870d6e46..9cd669334b8b 100644
--- a/Documentation/devel/troubleshooting.rst
+++ b/Documentation/devel/troubleshooting.rst
@@ -374,6 +374,7 @@ Interactive Console
   - :ref:`command_of_dump` if device tree description may be erroneous
   - :ref:`command_clk_dump` if serial is missing due to clock issues
   - :ref:`command_devinfo` to list the devices barebox knows about
+  - :ref:`command_drvinfo` to list the drivers and the devices bound to them
   - :ref:`command_iomem` to display the I/O memory map from barebox's point of view
 
 Kernel Hang
-- 
2.47.3

Re: (subset) [PATCH] fixup! Documentation: troubleshooting: add debugging via built-in init scripts

[Sascha Hauer]

On Thu, 24 Sep 2026 17:06:21 +0200, Ahmad Fatoum wrote:
> 


Applied, thanks!

[1/1] fixup! Documentation: troubleshooting: add debugging via built-in init scripts
      https://git.pengutronix.de/cgit/barebox/commit/?id=d2e1dd036edf (link may not be stable)

Best regards,
-- 
Sascha Hauer <s.hauer@pengutronix.de>