help-uboot: install defib from the repository, not from PyPI

[openipc-ai]

The side-loading section told readers to run uv tool install defib. defib has never been published to PyPI, so that installs an unrelated package or nothing at all — defib's own README was corrected for this in OpenIPC/defib@c163d87, this page was not.

The reporter in OpenIPC/firmware#2381, mid-recovery on a bricked Hi3516CV300, took the line literally enough to paste it into a Python REPL:

>>> uv tool install git+https://github.com/OpenIPC/defib
  File "<python-input-0>", line 1
    uv tool install git+https://github.com/OpenIPC/defib
    ^^^^
SyntaxError: invalid syntax

Two more things in the same block sent that same reader into a wall, so they are fixed here too.

burn -t alone does not stop the autoboot, and the page recommended exactly that. The bootloader being uploaded lives only in RAM, so on a camera whose flash cannot boot it autoboots, fails and resets — and the reset discards the RAM copy, leaving the terminal attached to a board that is dead again:

Wrong Image Format for bootm command
ERROR: can't get kernel image!
resetting ...

--- Terminal mode (Ctrl-C to exit) ---

It reads as the tool not working, which is what the reporter concluded. -b sends the Ctrl-C that avoids it, and the page now recommends -b -t with the reason.

The backup step recommended defib agent read, which cannot work for anyone who followed the install line above it. The flash agent is bare-metal code compiled per SoC and no prebuilt binary ships in the package, so defib agent refuses outright. The page now recommends defib dump-flash, which reads the flash out through the U-Boot console and needs nothing built, and says what the agent actually costs — while keeping it named for the status-register lock bits, which are the one job worth building it for.

Related: OpenIPC/defib#135 makes that refusal explain itself instead of saying "No agent binary for 'hi3516cv300'", which reads as an unsupported chip.

Testing

Documentation only — no build, no camera. Worth noting that the repo's cspell.yaml does not gate anything: there is no workflow in this repository, and the config is inert regardless — its markdown ignoreRegExpList includes /[A-Z]*/g, which matches an empty string at every position, so a deliberate misspelling in plain prose goes unreported. I checked with cspell 8.19.4 in a container rather than assume. Unrelated to this change, but someone may want to look at it.

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Correct defib installation and U-Boot recovery instructions

🐞 Bug fix 📝 Documentation 🕐 Less than 10 minutes

AI Description

• Installs defib directly from GitHub because no official PyPI package exists.
• Uses -b -t to interrupt autoboot and preserve RAM-loaded U-Boot.
• Replaces agent backup with console dumping and documents agent build requirements.

Diagram

graph TD
  A["Git repository"] --> B["Install defib"] --> C["Interrupt autoboot"] --> D["U-Boot console"] --> E["Dump flash"]
  D -. "Lock recovery" .-> F["Build SoC agent"] --> G["Clear lock bits"]

Loading

High-Level Assessment

The PR's approach is appropriate: repository installation reflects defib's actual distribution, dump-flash works without unavailable prebuilt agents, and -b -t prevents loss of the RAM-loaded bootloader. PyPI installation and agent-first backups were correctly dismissed because they cannot reliably support this recovery path.

Files changed (1) +22 / -7

Other (1) +22 / -7

help-uboot.mdCorrect defib setup, autoboot interruption, and flash backup guidance +22/-7

Correct defib setup, autoboot interruption, and flash backup guidance

• Changes defib installation from an invalid PyPI package reference to the GitHub repository and adds '-b' to stop autoboot before opening the terminal. It replaces the unavailable agent-based backup with 'dump-flash' and explains when compiling the SoC-specific agent remains necessary.

en/help-uboot.md

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. The guide exposes flash-lock implementation details ✓ Resolved 📘 Rule violation ⛨ Security

Description

The new explanation says the bare-metal agent clears flash status-register lock bits and directs
readers to vendor boot-log markers such as WPS=1 and Total Lock Blks. This publishes
register-level and bootloader-internal mechanisms for a vendor component rather than limiting the
guide to the observable backup and erase behaviour.

Code

en/help-uboot.md[R437-447]

+That reads the flash out through the U-Boot console and needs nothing else
+installed. There is a much faster route, `defib agent read`, but the flash
+agent is bare-metal code compiled per SoC and no prebuilt binary ships in the
+package — you need a defib checkout and `make SOC=<soc>` in its `agent/`
+directory before `defib agent` will do anything.
+
If a later `sf erase` appears to succeed but the data does not change, the
vendor bootloader has armed the flash's status-register block protection —
watch for `WPS=1` or `Total Lock Blks` in the boot log. The `defib agent` path
-clears those lock bits explicitly before erasing.
+clears those lock bits explicitly before erasing, which is the one job worth
+building the agent for.

Evidence

The changed prose adds the status-register lock-bit mechanism and says the agent clears those bits,
while the surrounding text identifies the relevant output from the vendor bootloader. These are
register-level and internal bootloader details covered by the checklist's failure criteria.

Rule 1: Documents behaviour, not the internals behind it
en/help-uboot.md[437-447]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The guide adds implementation details about flash status-register lock bits, vendor bootloader output, and the internal purpose of the bare-metal agent. The compliance checklist prohibits publishing register-level mechanisms or internal component details for closed components.
## Issue Context
Keep the operator-facing instructions for `defib dump-flash` and the observable symptom that an erase may appear to succeed without changing data, but remove the internal lock-bit and boot-log terminology. If mentioning the faster agent, describe only its user-visible prerequisite and effect.
## Fix Focus Areas
- en/help-uboot.md[437-447]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can tweak Display preferences with a live preview to see your comment before it ships

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗