Skip to content

tools/xm-isp-tuning: a Xiongmai GK7206 camera's ISP tuning, as an SDK PQ bin - #344

Merged
openipc-ai merged 4 commits into
masterfrom
tools-xm-isp-tuning
Nov 19, 2026
Merged

openipc-ai merged 4 commits into
masterfrom
tools-xm-isp-tuning

Conversation

@openipc-ai

Copy link
Copy Markdown
Contributor

Tools that take a Xiongmai GK7206 camera's ISP tuning out of its stock firmware and turn it into the XMedia SDK's own format, a PQ bin that xmedia_isp_import() loads. The SDK ships no tuning for most sensors, SC465SL included.

Two ways to read the tuning, both under tools/xm-isp-tuning/:

  • Unicorn capture (xm-isp-capture.py): runs the stock App's ISP monitor thread in emulation and records the SDK attribute setters it calls. It takes under a second, but only sees the App's init path.
  • Twin export (twin/xm-twin-export.py): boots the whole stock firmware in gk7206v11a, lets the App bring the ISP up, then dumps the attribute blocks and exports a PQ bin from inside the twin. Static camera tools go in typed at the shell, and results come out as hex over the console, because the busybox has no network fetcher and an SD card gets formatted by the App's recorder.

For SC465SL the twin export is the correct one. Interpolated to the ISO a stock camera was at, its noise-reduction and sharpening tables give the values that camera reports live in /proc/umap/isp:

field stock camera twin capture
TNR motion thresholds 32/65 32.5/64.9 22/43
chroma strength 248 248 224
sharpen texture 16 16 13
sharpen overshoot 86 86 113

The static blocks and the AWB calibration are byte-identical between the two methods. The README documents the use and the limits: night/IR mode is untested, daylight is untested, and the addresses are specific to this App build.

The exported bin is in OpenIPC/firmware#2905.

… as an SDK PQ bin

Xiongmai's firmware for GK7206V1 cameras tunes the ISP from per-sensor
tables compiled into its App; the XMedia SDK publishes no tuning for most
sensors, so firmware running the SDK alone gets the ISP library's generic
defaults -- on an IVG-K8 (GK7206V11 + SC465SL) a far noisier, bluer
picture than the stock firmware's on the same board.

xm-isp-capture.py runs the stock App's ISP monitor thread under Unicorn
(libc stubbed, the statically linked SDK returning 0, the SDK's attribute
setters and getters caught) and records what the App puts in force, block
by block, as the SDK's own structures. xm-isp-finish drops what the App
sets at run time instead of from tables; on the camera attrtool applies the
set, ae-ainr the AE curve and AINR switch points, and pqexport writes the
PQ bin xmedia_isp_import() loads. The addresses for one App build
(V1.10.T02.20261103) are a JSON profile.

Measured: applied to an OpenIPC IVG-K8 beside a stock one in low light
(ISO ~20000, 125 ms), the same picture; re-running the capture reproduces
the set behind the SC465SL profile in OpenIPC/firmware#2905 byte for byte;
the camera tools run on the board as built.
…e in the twin

Booting the stock GK7206V11 firmware in gk7206v11a and dumping the ISP
there gives the App's runtime tables, which the Unicorn capture misses
for STNR, BNR temporal, sharpen and LCE. Checked against a stock
camera's /proc/umap/isp at two ISOs.
@qodo-free-for-open-source-projects

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

Copy link
Copy Markdown

PR Summary by Qodo

Extract Xiongmai GK7206 ISP tuning as XMedia PQ bins

✨ Enhancement 🕐 40+ Minutes

Grey Divider

AI Description

• Add Unicorn capture and full-firmware twin export paths for extracting stock ISP tuning.
• Convert captured blocks into SDK-loadable PQ bins to replace generic sensor defaults.
• Document why twin-derived SC465SL tables are preferred and where validation remains incomplete.
Merge Risk 🟡 Medium

Blast radius 🟢 Low 💥 1 capability

  • 1 affected end-to-end capability after fault-specific containment; implementation boundaries do not widen its functional scope.
  • All new tools form one operator workflow, and no existing code consumes them.
Behavioral complexity 🟡 Medium 🧩 Data transformation

  • Before: no tool existed.
  • After: Unicorn emulation of the vendor App, mapped onto SDK structure layouts, then finished and applied.
  • New correctness condition: the profile addresses and struct layouts must match the App build and SDK.
  • This is new standalone code with no changes to existing logic.
Potential damage 🟡 Medium 🩹 Recoverable

  • Image quality could degrade on the camera the operator applies the set to.
  • Other systems are unaffected.
  • Reboot, or re-apply the baseline dump from attrtool dump.
Assessed commit 49b3dfb
Diagram

graph TD
  App["Stock App"] --> Capture["Unicorn capture"] --> Finish["Block finishing"] --> Camera["Camera ISP"] --> Export["SDK PQ export"] --> Bin[("PQ bin")]
  App --> Twin["QEMU twin"] --> Finish
  Twin --> Export
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Unicorn capture only
  • ➕ Completes quickly without booting the full firmware.
  • ➖ Misses later App rewrites to SC465SL noise-reduction, sharpening, and LCE tables.
2. Decode vendor tables statically
  • ➕ Could extract tuning offline without executing vendor code.
  • ➖ Requires mapping proprietary packed layouts to SDK structures and reproducing the App's runtime transformations.

Recommendation: Use the twin's live ISP blocks as the primary SC465SL source and retain Unicorn capture for AWB calibration that cannot be read from the ISP. The stock-camera comparisons support this combination over capture alone; static decoding adds substantial work without capturing runtime behavior.

Files changed (14) +1102 / -1

Enhancement (8) +788 / -0
ae-ainr.cApply runtime AE settings and AINR thresholds +55/-0

Apply runtime AE settings and AINR thresholds

• Sets an ISO-indexed AE compensation curve and control limits, then updates AINR switching thresholds on ISP pipe 0.

tools/xm-isp-tuning/camera/ae-ainr.c

attrtool.cDump and apply raw SDK attribute blocks +66/-0

Dump and apply raw SDK attribute blocks

• Provides a table-driven utility to read ISP, AE, and AWB attributes into named binary files and apply selected files back to pipe 0.

tools/xm-isp-tuning/camera/attrtool.c

hexout.cTransfer guest files through hex console output +20/-0

Transfer guest files through hex console output

• Prints files as marked hexadecimal records with lengths and checksums, allowing the twin exporter to recover them from a serial console.

tools/xm-isp-tuning/camera/hexout.c

pqexport.cExport live SDK state to a PQ bin +38/-0

Export live SDK state to a PQ bin

• Calls the SDK exporter for ISP, AWB, and AE modules and writes the resulting records in the PQ-bin format accepted by the SDK importer.

tools/xm-isp-tuning/camera/pqexport.c

xm-isp-decode.cSummarize captured ISP tuning fields +96/-0

Summarize captured ISP tuning fields

• Reads saved attribute blocks and prints selected sharpening, noise-reduction, AE, AWB, and other settings for inspection.

tools/xm-isp-tuning/host/xm-isp-decode.c

xm-isp-finish.cPrepare captured blocks for camera application +104/-0

Prepare captured blocks for camera application

• Keeps table-derived blocks while excluding runtime-controlled settings. Sets required automatic modes, BNR temporal behavior, and SDK AWB limits using a baseline dump.

tools/xm-isp-tuning/host/xm-isp-finish.c

xm-twin-export.pyExport live tuning from a booted firmware twin +92/-0

Export live tuning from a booted firmware twin

• Boots stock firmware in the GK7206 QEMU machine, transfers static utilities through the guest shell, and dumps live attributes and a PQ bin. Recovers the results from marked hexadecimal serial output.

tools/xm-isp-tuning/twin/xm-twin-export.py

xm-isp-capture.pyCapture App ISP setters under Unicorn +317/-0

Capture App ISP setters under Unicorn

• Loads the stock ARM App, stubs libc and SDK calls, and records SDK attribute blocks from its ISP monitor path. Uses a build-specific profile, camera baseline blocks, and synthetic AE/AWB readings to drive capture.

tools/xm-isp-tuning/xm-isp-capture.py

Documentation (2) +119 / -1
README.mdLink ISP tuning tools from the GK7206 overview +3/-1

Link ISP tuning tools from the GK7206 overview

• Points readers to the new tooling for extracting stock Xiongmai tuning as an SDK PQ bin.

README.md

README.mdDocument extraction routes, SC465SL results, and limits +116/-0

Document extraction routes, SC465SL results, and limits

• Explains the Unicorn and twin workflows, build and camera commands, and why live twin tables are preferred for SC465SL. Records low-light comparisons and identifies untested night, daylight, sensor, and App-build cases.

tools/xm-isp-tuning/README.md

Other (4) +195 / -0
build.shBuild camera and host utilities against XMedia headers +76/-0

Build camera and host utilities against XMedia headers

• Cross-compiles camera tools, builds host finishing and decoding tools, and derives SDK structure sizes and offsets from an ARM object. Checks that host structure sizes match the camera layout.

tools/xm-isp-tuning/build.sh

sdkshim.cBridge SDK uClibc symbols for musl tools +19/-0

Bridge SDK uClibc symbols for musl tools

• Supplies the small set of uClibc-compatible symbols needed to link and run camera utilities against the SDK libraries.

tools/xm-isp-tuning/camera/sdkshim.c

layout.cExpose target SDK structure layouts to the capture +27/-0

Expose target SDK structure layouts to the capture

• Declares symbols encoding attribute sizes and AE/AWB field offsets. The build script extracts their sizes from an ARM object for the Unicorn capture layout.

tools/xm-isp-tuning/host/layout.c

ipc_gk7206v11_k8-v1.10.t02.20261103.jsonMap one Xiongmai App build for emulated capture +73/-0

Map one Xiongmai App build for emulated capture

• Records the App checksum, monitor and SDK address ranges, pipe layout, and setter/getter addresses used to intercept attribute calls. The addresses are specific to the identified firmware build.

tools/xm-isp-tuning/profiles/ipc_gk7206v11_k8-v1.10.t02.20261103.json

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

qodo-free-for-open-source-projects Bot commented Nov 19, 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. Twin blocks cannot reach the final set ✓ Resolved
Description
xm-twin-export.py saves dump/bnr.bin as dump__bnr.bin, while xm-isp-finish looks for
/bnr.bin. Passing the twin output through the documented finishing route skips every dumped ISP
block and still reports that the final set is ready.

2. Fresh captures crash before dumping ✓ Resolved
Description
attrtool dump passes the result of fopen() directly to fwrite() without checking whether the
destination directory exists. The documented ./attrtool dump base/ command does not create base,
so a fresh run dereferences a null file pointer.

3. The finishing step fails on a fresh run ✓ Resolved
Description
xm-isp-finish opens files under OUT_DIR but never creates that directory. The documented command
uses final without a preceding directory-creation step, so its first available captured block
causes the command to fail.

View action required (2)
4. Failed reads become valid-looking blocks ✓ Resolved
Description
attrtool dump writes its zero-initialized buffer even when the SDK getter returns an error. A
failed getter therefore leaves a full-size block that capture can use as its baseline and that a
later apply command can send to the ISP.

5. A failed twin export can appear complete ✓ Resolved
Description
run() matches the shell's exit-status marker but discards its value, and the export command's
result is ignored. If pqexport.static fails and creates no twin.bin, hexout emits `@@MISSING
twin.bin`; the parser can still write the other files and finish without requiring that bin.


Remediation recommended

6. Failed block applications report success ✓ Resolved
Description
attrtool apply prints a setter's result but returns zero regardless of that result, a short input
file, or a missing requested file. The documented apply command can consequently continue to
ae-ainr and PQ export after failing to install part of the intended tuning.

7. Auto-exposure failures go unnoticed ✓ Resolved
Description
ae-ainr overwrites the AE setter's result with the subsequent AINR getter or setter result and
then returns zero unconditionally. If AE rejects the new curve but AINR succeeds, the documented
export sequence proceeds with the previous exposure settings.

8. An AINR read failure prints stack data ✓ Resolved
Description
ae-ainr leaves a uninitialized when xmedia_isp_get_ainr_attr() fails but prints its threshold
fields unconditionally. On that failure path, its status line reads indeterminate values instead of
reporting only the SDK error.

View review recommended (2)
9. Failed rebuilds can reuse old camera tools ✓ Resolved
Description
build.sh suppresses compiler-pipeline failures with || true and then tests only whether the
output path is executable. After an earlier successful build, a failed rebuild can leave its old
binary in place while the script reports that the tools were built.

10. Corrupted twin files can pass validation ✓ Resolved
Description
xm-twin-export.py checks the received byte count but never compares the checksum in each @@END
record. A same-length byte change during console transfer is written as a valid-looking block or PQ
bin despite hexout having supplied a way to detect it.

Grey Divider

Tip of the day
💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

- attrtool: creates the dump directory, writes no block for a failed
  getter, checks its writes, exits non-zero on any failed get, set or
  missing file, and logs line by line (a crashing getter -- smart_info
  under the stock App -- no longer swallows the log).
- ae-ainr: reports the AE and AINR results separately and fails if
  either did; no uninitialised AINR fields on a failed read.
- xm-isp-finish: creates its output directory.
- build.sh: a failed compile fails the build instead of keeping an old
  binary; with SDK_STATIC it also builds the static tools the twin route
  types in (camera/sdkshim_static.c, the uClibc gaps of the SDK's static
  objects).
- xm-twin-export.py: writes <block>.bin as xm-isp-finish reads them;
  checks each command's exit status; verifies every file against
  hexout's length and checksum, re-requesting damaged ones (the App's
  log can cut a hex line); requires the PQ export and the NR/sharpen
  blocks; lists the dump with a shell loop (this busybox colours ls);
  sets xmuart=0 in a copy of the flash itself, keeping every other
  saved variable.

Two full twin runs give byte-identical ISP blocks, and the README's
route (export, AWB from the capture, finish) reproduces the shipped
sc465sl set exactly.
@openipc-ai

Copy link
Copy Markdown
Contributor Author

Review fixes in a0c65ff and 49b3dfb, all ten findings:

  1. Twin blocks under flattened names. The export writes <block>.bin, which is what xm-isp-finish reads. The README route (export, then AWB from the capture, then finish) reproduces the shipped SC465SL set byte for byte.
  2. attrtool crashing on a missing dump directory. It now creates the directory and checks every open and write.
  3. xm-isp-finish failing on a fresh output directory. It now creates its output directory.
  4. Blocks written for failed reads. A failed getter now writes no block.
  5. Exit status ignored. run() checks each command's exit status, and the PQ export and the noise-reduction and sharpen blocks are required.
  6. apply reporting success after failures. attrtool apply now exits non-zero on a failed set, a short or missing file, or an unknown block name.
  7. AE result overwritten. ae-ainr reports the AE and AINR results separately and fails if either does.
  8. Uninitialised AINR fields printed. The thresholds are printed only when the read succeeded.
  9. Old binaries kept after a failed build. A failed compile now fails build.sh. With SDK_STATIC set, it also builds the static tools the twin route needs.
  10. Checksum never compared. Each file is now checked against hexout's length and checksum, and damaged files are fetched again. This was a real problem: on one run the App's console log cut a hex line, and the check caught it.

Also fixed along the way:

  • The script sets xmuart=0 in a copy of the flash itself, keeping every other saved variable. qemu-boot/uboot-env.py rebuilds the environment from U-Boot's defaults, which would drop them.
  • The dump is listed with a shell loop, because this busybox colours ls output.
  • attrtool logs line by line, so the log shows that the getter that crashes under the stock App is smart_info.

Two full twin runs gave byte-identical ISP blocks. The rebuilt camera tools were checked on an IVG-K8.

@openipc-ai
openipc-ai merged commit f0c2fcb into master Nov 19, 2026
19 checks passed
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