install: add Hikvision U-Boot migration for HiWatch DS-I203 - #137
Conversation
PR Summary by QodoAdd Hikvision U-Boot migration for HiWatch DS-I203
AI Description
Diagram
High-Level Assessment
Files changed (25)
|
Code Review by Qodo
1. Protocol tools miss Hikvision recovery
|
![qodo-free-for-open-source-projects[bot]](https://avatars.githubusercontent.com/in/1068000?s=60&v=4){kind=small}
Move the install implementation out of the CLI into reusable defib.install modules and add a separate stock-U-Boot bootstrap abstraction for migrations that start from an already-running vendor bootloader rather than the SoC boot ROM. Add the vendor bootstrap registry, the reusable Hikvision U-Boot console/YMODEM implementation, firmware artifact override support, standard NOR layout helpers, environment helpers, and installer plumbing needed for a board-specific stock migration. Keep this mechanism separate from BootProtocol because BootProtocol describes the SoC boot-ROM recovery dialect, while vendors.* starts from a running vendor U-Boot. Verification: python -m pytest tests/test_install_flash_helpers.py tests/test_uart_command_integrity.py tests/test_uboot_env.py tests/test_ymodem.py -q Hardware verification is not standalone for this commit because it intentionally does not register a concrete board selector. The following HiWatch DS-I203 commit binds this reusable layer to physical hardware and carries the end-to-end stock-U-Boot migration evidence.
Bind the reusable stock-U-Boot migration path to the physical HiWatch DS-I203. Register hi3518ev100:hiwatch-ds-i203 as a Hikvision stock-U-Boot target, map it to the DDR3/256 MiB OpenIPC U-Boot variant, use the safe 0x81000000 chainload address, and apply transient phyaddru=3 only for installer TFTP. Add the board documentation and migration contract tests covering the stock Hikvision console, existing-OpenIPC detection, factory MAC preservation, NOR layout ownership, and release artifact selection. Verification: python -m pytest tests/test_ds_i203_final_contract.py tests/test_firmware.py -q Hardware verification used a physical HiWatch DS-I203 with Hi3518EV100, IMX122, 256 MiB DDR3 and 16 MiB GD25Q128 SPI NOR. Defib entered Hikvision U-Boot 2010.06 through Ctrl+U / HKVS, chainloaded the DDR3/256 MiB OpenIPC U-Boot over YMODEM, detected the 16 MiB NOR layout, flashed OpenIPC firmware, preserved the factory MAC, and booted the matching DS-I203 firmware profile successfully. The validated path was: Hikvision U-Boot -> Ctrl+U / HKVS -> YMODEM OpenIPC U-Boot -> TFTP flash -> environment migration -> OpenIPC boot.
Harden the stock-U-Boot migration path so destructive install steps fail closed instead of continuing on ambiguous or invalid state. Require explicit --wipe-env for registered stock-U-Boot NOR migrations, reject oversized U-Boot overrides through the normal CLI error path, broaden NOR-size parsing for valid U-Boot probe formats, and require parseable CRC values for both TFTP RAM verification and flash readback instead of silently skipping verification when output is incomplete. Keep vendor migrations from erasing the environment as part of the U-Boot partition write, preserve the captured factory ethaddr across the explicit environment migration, and add focused regression coverage for the destructive preflight and CRC failure cases. Verification: python -m pytest tests/test_ds_i203_final_contract.py tests/test_install_flash_helpers.py -q Hardware verification used the HiWatch DS-I203 stock-U-Boot migration path with explicit --wipe-env. The board completed the migration on 16 MiB NOR, preserved the factory MAC and reached OpenIPC successfully; later review commits further strengthen transport and persistent-environment verification without changing this commit's fail-closed contract.
Fix the shared installer and transport issues found during review of the HiWatch DS-I203 stock-U-Boot migration. Restore explicit TFTP RAM addressing for generic installs, bound serial TX draining, keep RFC2217 flush semantics explicit, verify persistent SPI environment contents after saveenv, handle TransportError cleanly, and protect Hikvision loady/go with UART echo verification. Also make --nor-size a true override, add the hi3518ev100 RAM base, restore JSON error output, harden U-Boot error parsing, remove dead helpers, use raw U-Boot for YMODEM and pad only for flash, and expand YMODEM/transport/install regression coverage. Hardware verification: python -m defib install -c hi3518ev100:hiwatch-ds-i203 --firmware $HOME\Downloads\hiwatch-ds-i203-202609151816.tgz --uboot $HOME\Downloads\u-boot-hi3518ev100-ddr3-256m-universal.bin --wipe-env -p COM15 --tftp-via host --nic "Беспроводная сеть" --host-ip 192.168.1.11 --device-ip 192.168.1.64 --no-final-reset -d The DS-I203 completed stock Hikvision U-Boot -> OpenIPC U-Boot migration on hardware, detected 16 MiB NOR, flashed and CRC-verified U-Boot/kernel/rootfs/rootfs_data, preserved the factory MAC, saved the environment, re-probed SPI, and physically verified the environment CRC before leaving the board at the OpenIPC prompt.
Add explicit install-stage selection for development, recovery, and targeted validation without replaying the complete production install. --stage selects an exact set from uboot, kernel, rootfs, rootfs-data, env, and reset. --skip-stage subtracts stages from the normal production sequence, and the two forms cannot be combined. Explicit stage selection performs reset only when reset is selected. Keep the default install path unchanged. Start TFTP only when selected stages need image transfer, keep environment erase coupled to the env stage, and reject unsafe partial persistent installs when a genuine stock U-Boot was only chainloaded temporarily. Regression coverage verifies default and explicit stage resolution, skip semantics, env-only execution without TFTP or partition writes, reset selection, invalid combinations, and stock-migration safety. Verification: python -m pytest tests/test_install_stages.py -q The stage controls were also exercised on the HiWatch DS-I203 with an env-only run against an already-running OpenIPC U-Boot. That run completed the environment migration and its physical SPI CRC verification and was used while validating the required post-reset sf probe handling.
aa18898 to
ab20fbe
Compare
|
Addressed the requested review changes and force-pushed the rewritten five-commit series. The original three commits now have full bodies with rationale, verification commands, and hardware evidence. Review remediation is isolated in The final tree was revalidated on the physical DS-I203 after the review fixes, including UART echo verification for Local final gate: 873 passed / 10 skipped / 4 known Windows-baseline tests deselected, fuzz 16 passed, locked Ruff 0.15.8 clean, strict mypy clean, and |
1 participant
While porting OpenIPC to a HiWatch DS-I203 (HI3518EV100, IMX122, 256 MiB DDR3, 16 MiB SPI NOR), I found that Defib's normal HiSilicon boot-ROM recovery path is not usable through the camera's exposed UART.
The recovery path available on the stock camera is Hikvision U-Boot 2010.06:
Ctrl+Uenters theHKVS #console, andloadycan receive a replacement U-Boot over YMODEM.The board also needs the DDR3/256 MiB OpenIPC U-Boot added here: OpenIPC/u-boot-hi3516cv100#6
The matching OpenIPC device profile is here: OpenIPC/builder#159
This PR connects that stock Hikvision recovery path to Defib's normal install flow and hardens the shared install/transport code found during review.
What changed
BootProtocol: boot protocols describe SoC boot-ROM recovery, whilevendors.*starts from an already-running vendor U-Boot.Ctrl+U,HKVS #, factory-MAC capture,loady/YMODEM,go, and detection of an already-running OpenIPC U-Boot.loadyandgo, now use UART echo verification before the terminating CR is sent.hi3518ev100:hiwatch-ds-i203resolves tou-boot-hi3518ev100-ddr3-256m-universal.binwithout changing the generichi3518ev100artifact.--ubootremains available for a local override.cli/app.pyintodefib.install.--nor-sizeis a genuine explicit override; the CLI default is now0, meaning auto-detect.tftpboot; only the stock-U-Boot path uses the shortloadaddrform.hi3518ev100RAM base instead of relying on prefix/fallback ordering.rootfs_dataerase verification.ethaddracross environment replacement. Installer-only values such as DS-I203phyaddru=3remain transient; persistent runtime board policy stays in the Builder profile.saveenv: Defib re-probes SPI, reads the env partition, computes its data CRC, and compares it to the stored environment CRC.TransportTimeout, now use the controlled installer failure path and release UART/power/TFTP resources. Pre-TFTP environment verification failures are covered as well.SerialTransport.flush_output()uses a boundedout_waitingdrain instead of unboundedtcdrain()or output-buffer purging.flush_output()is intentionally an explicit no-op and never uses PURGE_DATA.--output jsonerror behavior for installer preflight failures.list-chips, and added protocol-level YMODEM tests including retry and final-handshake behavior.--stage/--skip-stageinstall controls in a separate commit for targeted development/recovery validation. The normal no-flag production flow is unchanged; explicit stage selection only performs the requested persistent operations and starts TFTP only when required.Hardware verification
Final end-to-end acceptance was performed on a physical HiWatch DS-I203:
The final migration run used:
The run completed:
HKVS #entry;loadyandgo;rootfs_dataerase;mtdpartspersistence;saveenv;SPI CRC 7A58A0B5);The environment-only stage path was also exercised against an already-running OpenIPC U-Boot while validating the post-reset SPI re-probe and persistent CRC check.
Earlier complete device-profile acceptance also confirmed 256 MiB physical RAM, the intended 128 MiB Linux / 128 MiB MMZ split, PHY address 3 / MDIO0, IMX122, and Majestic startup.
Testing
Final local gate on the published tree:
873 passed, 10 skipped, 4 deselectedin the full Python suite.netshdecoding and Windows symlink privilege.16 passedintests/fuzz.0.15.8from the repository lockfile: clean onsrc/andtests/.git diff --check: clean.The first three commits were also rewritten to include the rationale, verification commands, and hardware evidence required by
CLAUDE.md.