Skip to content

gpio dump: every pin's mux and level, once and read-only - #279

Merged
widgetii merged 3 commits into
masterfrom
gpio-dump
Nov 12, 2026
Merged

widgetii merged 3 commits into
masterfrom
gpio-dump

Conversation

@widgetii

@widgetii widgetii commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

ipctool gpio dump [--json]: for every pin of every GPIO bank, the function its pad carries now and, where that is the GPIO, the direction and level. It reads each bank once, writes nothing and exits.

Why

The existing GPIO commands don't answer "what is this board's GPIO state":

  • gpio scan answers "what changes". It loops until Ctrl-C and lists only pins already muxed to GPIO.
  • gpio mux writes.

That question comes up when one firmware drives a peripheral and another doesn't. Comparing a stock Xiongmai N51813L with its OpenIPC sibling needed a hand-merged reginfo plus a gpio scan killed by PID, because stock busybox has no timeout (and no tr). With this command it is one run per camera and a diff.

Behaviour

  • Text: GPIO2_2 pad 18 GPIO2_2 out 0. A pad muxed to another function prints just that function, with no state and no trailing padding.
  • --json: an array with one object per pin: gpio, pad, mux (gpio, function, unknown, none or unreadable), function, gpio_muxed, and dir and value when it is a GPIO.
  • Pads with no mux row (IPCHW_PADMUX_NO_PAD): these are always the GPIO. They show as [none] with their state, as GPIO8_x and GPIO11_7 do on Hi3518CV100.
  • A selector the table doesn't name: [unknown], with no GPIO state.
  • Read errors: an unreadable bank or mux register goes to stderr, and the exit status is a failure. The output stays well-formed but never passes as complete.
  • Other vendors: SigmaStar and Novatek keep GPIO state outside these PL061 banks, so they are refused (not supported on this SoC yet) rather than misreported.

Testing

< GPIO0_7  pad 7    SYS_RSTN_OUT
> GPIO0_7  pad 7    GPIO0_7              out 1
< GPIO1_3  pad 11   EPHY_CLK
> GPIO1_3  pad 11   GPIO1_3              out 1
< GPIO2_2  pad 18   UART1_RTSN
> GPIO2_2  pad 18   GPIO2_2              out 0
< GPIO3_2  pad 26   MII_RXCK
> GPIO3_2  pad 26   GPIO3_2              out 0
< GPIO5_1  pad 41   USB_PWREN
> GPIO5_1  pad 41   GPIO5_1              out 1
< GPIO6_0  pad 48   SDIO_CARD_DETECT
> GPIO6_0  pad 48   GPIO6_0              in  1
< GPIO6_1  pad 49   SDIO_CARD_POWER_EN
> GPIO6_1  pad 49   GPIO6_1              in  1

Note for anyone testing on a V1 part: a binary built with a Cortex-A7-defaulting toolchain segfaults on every command on ARM926. CI's hi3516cv100 toolchain targets ARMv5, so the CI artefact is fine.

Review

The four Qodo findings are fixed in 7eb85ce, and the re-review marks all four resolved:

  • Pads are classified by ipchw_padmux_get()'s documented return values and the IPCHW_PADMUX_F_GPIO flag.
  • Read failures fail the command.

That commit was re-run on both units: exit 0, 96 pins each, the same 7-pin diff, and no stderr output.

`gpio scan` answers "what changes": it loops until Ctrl-C and lists only pins
already muxed to GPIO. `gpio mux` writes. Neither answers "what is this board's
GPIO state", which is the question when one firmware drives a peripheral and
another does not. Comparing a stock Xiongmai N51813L with its OpenIPC sibling
needed a hand-merged `reginfo` and a `gpio scan` that had to be killed by PID,
because stock busybox has no `timeout`.

`ipctool gpio dump [--json]` prints, for every pin of every PL061 bank, the
function its pad carries now. Where that is the GPIO, or the table has no row
for the pad, it also prints the direction and level. It reads each bank once,
writes nothing and exits. `--json` gives one object per pin, so two cameras
diff directly. SigmaStar and Novatek keep GPIO state outside these banks, so
they are refused rather than misreported.
Pad the function column only when a direction and level follow it, so no line
ends in spaces and two dumps diff cleanly.
@qodo-free-for-open-source-projects

Copy link
Copy Markdown

PR Summary by Qodo

Add read-only GPIO dump with per-pin mux and level

✨ Enhancement 📝 Documentation 🕐 20-40 Minutes

Grey Divider

AI Description

• Add a one-shot GPIO dump so firmware pin states can be compared without changing registers.
• Show each pin’s pad function, plus direction and level when muxed to GPIO; support text and JSON.
• Refuse unsupported SoCs rather than report GPIO state from incompatible hardware.
Diagram

graph TD
  CLI["GPIO dump CLI"] --> Supported{"Supported SoC?"} -->|yes| Bank["PL061 bank reads"] --> Mux["Padmux lookup"] --> IsGPIO{"GPIO muxed?"} -->|yes| State["Direction and level"] --> Output["Text or JSON"]
  IsGPIO -->|no| Output
  Supported -->|no| Refuse["Unsupported error"]
Loading
High-Level Assessment

The dedicated, read-only command fits the use case: it reuses existing GPIO bank mapping and padmux lookup while avoiding scan’s continuous polling and mux’s writes. Combining existing command output would be harder to run and compare reliably on stock firmware.

Files changed (3) +110 / -3

Enhancement (1) +106 / -1
reginfo.cImplement one-shot GPIO state dump +106/-1

Implement one-shot GPIO state dump

• Adds gpio dump dispatch and optional JSON output. For supported PL061 SoCs, it reads each bank’s direction and data registers once, looks up every pad’s current function, and reports GPIO state only where applicable; unsupported SoCs are refused.

src/reginfo.c

Documentation (2) +4 / -2
README.mdDocument the GPIO dump command +2/-1

Document the GPIO dump command

• Adds dump and its optional JSON output to the command listing. Describes its per-pin mux and level reporting as read-only.

README.md

main.cAdvertise GPIO dump in CLI help +2/-1

Advertise GPIO dump in CLI help

• Updates the built-in usage text to list dump alongside scan and mux and describe its read-only output.

src/main.c

@qodo-free-for-open-source-projects

qodo-free-for-open-source-projects Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

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

Grey Divider


Action required

1. Unknown mux modes appear as GPIO ✓ Resolved
Description
gpio_dump_cmd treats ipchw_padmux_get() returning 0 as proof that the pin is muxed to GPIO.
That return value actually means the selector is unnamed or reserved, so a readable bank causes the
dump to attach a GPIO direction and level to a mode it cannot identify.

2. Pins without mux rows lose their state ✓ Resolved
Description
gpio_dump_cmd assigns IPCHW_PADMUX_NO_PAD the function "unreadable" and sets is_gpio to
false rather than applying its stated no-row fallback. On supported bank ranges with missing mux
rows, such as GPIO11_7 on CV100, the pin is listed without its direction or level even when the bank
reads succeed.

3. Failed bank reads produce a successful dump ✓ Resolved
Description
gpio_dump_cmd records failed direction or data reads only in readable, then returns
EXIT_SUCCESS after suppressing the affected GPIO state. If /dev/mem cannot supply either
register, JSON output is missing direction and value for that bank while callers receive a success
status.


Remediation recommended

4. Mux read errors look like non-GPIO modes ✓ Resolved
Description
gpio_dump_cmd maps every negative ipchw_padmux_get() result to "unreadable" and
gpio_muxed:false without distinguishing an I/O failure or unavailable table. If a padmux register
cannot be read while its GPIO bank can, the command emits a non-GPIO record and exits successfully
despite not knowing the pad's function.

Grey Divider

Tip of the day
💡 Did you know, you can open the rule or relationship behind a finding in one click

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

…ad errors

Review fixes (Qodo on #279):

- 0 from ipchw_padmux_get() is a selector the table does not name. It is now
  reported as mux "unknown" with no GPIO state, instead of being taken as GPIO.
- IPCHW_PADMUX_NO_PAD is the pad with no mux row: nothing can select another
  function onto it, so it is the GPIO, as mux "none" with its direction and
  level. GPIO8_x and GPIO11_7 on Hi3518CV100 used to lose their state.
- GPIO-ness comes from IPCHW_PADMUX_F_GPIO, the documented flag, not a name
  comparison.
- An unreadable bank or mux register is reported on stderr and makes the exit
  status a failure. The dump is still printed, as well-formed JSON with an
  "error" field on affected GPIO pins, but never passes as complete. A SoC
  with no pin-mux table is refused up front.

JSON gains a "mux" field: gpio, function, unknown, none or unreadable.
@widgetii
widgetii merged commit 9ab52d5 into master Nov 12, 2026
5 checks passed
@widgetii
widgetii deleted the gpio-dump branch November 12, 2026 13:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant