[fpga] docs: record Toy/Linux hardware bring-up and programming entry

README.md

@@ -14,9 +14,11 @@ The Arty A7 platforms have their own pinned Chisel build, serial loader, firmwar
 constraints and verification record. Follow its guide directly; the setup and
 demo below describe the existing Kintex-7 flow.
 
-The Toy/Linux target passes complete board implementation and Linux RTL checks.
-Its current Rev E DDR engineering target still requires physical DDR calibration
-and Linux boot acceptance; see its guide before programming.
+The Toy/Linux target passes complete board implementation, Linux RTL checks and
+a physical Arty A7-100T boot with full image readback and five Linux checks.
+Its PCB revision remains unconfirmed and physical Gemmini testing is pending;
+see [the hardware record](platforms/arty-a7-toy/evidence/2026-10-12/README.md)
+and its build/programming guide before using another board.
 
 ## Kintex-7 setup
 

platforms/arty-a7-toy/.gitignore

@@ -9,4 +9,5 @@ __pycache__/
 *.log
 !evidence/**/*.log
 *.jou
+!evidence/**/*.jou
 toy-console.log

platforms/arty-a7-toy/README.md

@@ -2,9 +2,11 @@
 
 A Chisel-generated Toy platform for `xc7a100tcsg324-1`, with CPU, Sv39, full
 FP16/32/64 support and Gemmini 8×8. Complete board implementation, timing, CDC
-checks and Linux RTL tests pass. The physical board revision is unconfirmed:
-this is a **Rev E engineering bring-up target**, awaiting hardware DDR and Linux
-acceptance. See [measured results](VALIDATION.md) before programming.
+checks and Linux RTL tests pass. On 2026-10-12 the connected board was programmed,
+the complete image was read back from DDR and five Linux checks passed on hardware.
+This remains a **Rev E engineering target**: PCB revision is unconfirmed and
+physical Gemmini tests are pending. See [measured results](VALIDATION.md) and
+[the hardware logs](evidence/2026-10-12/README.md).
 
 ## Architecture and scope
 
@@ -79,24 +81,41 @@ products and are not committed. A successful fresh board run produces
 
 ## First hardware boot
 
-1. Confirm the physical DDR/revision matches the official Rev E parameters;
-   connect PROG/UART USB and select the single XC7A100T in Hardware Manager.
-2. Program the selected `.bit` into volatile FPGA SRAM. On Windows:
-   `./program.ps1 -Bitstream <absolute-bitstream-path> -VivadoBin <Vivado-bin>`.
-   The script does not write flash and is not run automatically.
-3. Press BTN0, wait for LED0 (DDR calibrated), and close other serial clients.
-4. Install `pyserial`, then load and byte-verify the image before releasing CPU:
+Confirm the physical DDR/revision matches the official Rev E parameters and
+connect PROG/UART USB. The script requires exactly one attached JTAG target and
+one XC7A100T. It programs the selected `.bit` into volatile FPGA SRAM.
+
+The portable [program.tcl](program.tcl) delegates to
+[board/program_arty.tcl](board/program_arty.tcl), the script used by the hardware
+run. Set both paths to actual files; a clone contains sources and logs, so build
+the `.bit` and Linux payload first using the commands above.
+
+```bash
+vivado -mode batch -source /absolute/path/to/platforms/arty-a7-toy/program.tcl \
+  -tclargs /absolute/path/to/toy_a7.bit
+```
+
+Windows paths with spaces must be quoted. The equivalent PowerShell wrapper is
+`./program.ps1 -Bitstream <bitstream-path> -VivadoBin <Vivado-bin>`.
+
+After JTAG programming, press BTN0, wait for LED0 (DDR calibrated), and close
+other serial clients. Install `pyserial`, then load and byte-verify the Linux
+image before releasing the CPU:
 
 ```bash
 python host/load.py --port COM5 --check-linux build/board-software/fw_payload.bin
 ```
 
 Use the actual serial port. Expect OpenSBI, Linux, BusyBox and five PASS markers
 for COW, page protection, FP64 process context, the timer and the total Linux
-system check. A 17 MiB transfer with full readback takes several minutes at
-1 Mbps. After the script closes the port, an interactive console is available
+system check. The recorded 17 MiB transfer/readback took 544.1 seconds with a
+temporary 2 ms FTDI D2XX latency; default VCP settings can take substantially
+longer. The archived transport script records that experiment; normal loading
+uses `host/load.py`. After it closes the port, an interactive console is available
 with `python -m serial.tools.miniterm COM5 1000000 --eol LF`.
 
 LED1 indicates loader error or nonzero exit, LED2 CPU released, LED3 heartbeat.
 LEDs alone do not establish software success. Preserve the console transcript
 and DDR calibration result; operator acceptance additionally needs Gemmini tests.
+FPGA SRAM and the DDR image are volatile: repeat programming and loading after
+power loss. See the hardware record for exact bitstream/payload SHA256 values.

platforms/arty-a7-toy/SOURCE_LOCK.json

@@ -3,14 +3,14 @@
   "memory_rtl_sha256": "8307d252185ba71a4516d1932d235a5a188816f84a5ed237bb5f3c1281d4b580",
   "files": {
     ".gitattributes": "8d9ebca04236fcd49c43562b5c6ca1d88ded1ff8c8d437fbdfe3822a5ec22d74",
-    ".gitignore": "a53e6d03c290aafb77c981f7e2d7eacf3a0369637725c26386a596fb07432295",
+    ".gitignore": "2c2d881b7e4f197b4b0baf1df40f9f6885dbd3f0d7d0bd83a5e8cca7c908fec9",
     ".jvmopts": "a66471d84e6e2ed0c3c40d5ebbc237d268ed9b04f3528ef22e967a2bd4e8aa44",
-    "README.md": "d641e506cc7296b6d48160058b8c4a561d45f4648ea90a7f84dbbdf81256a63e",
+    "README.md": "8d957c96f6212498b7cf906a264ea6af6a1198b5615f3582f701854e41b35c81",
     "SOFTWARE_BASELINE.json": "3a5c9f65771e6fd7f8172674baf22263ba7c2d9244993c9162ba526344a7b0aa",
     "THIRDPARTY.md": "02ed1d3ddd4fc26a8b1580eb4948ff6cf4f548c0434c89f1c6c2220bed3d4a42",
     "UPSTREAM_MANIFEST.json": "c4a96343e318c452420cf86b34d6008140560eeffa91cd85b4b87b229717c9be",
-    "VALIDATION.md": "ccc142ab197f77c2988019d8c746469736f29f87f5f087ee7462d1ef258b6d76",
-    "board/README.md": "7ee92595392b27a0495b2215c406add9a6d084dba36138068ecc2adeaa0e449b",
+    "VALIDATION.md": "9d188957eed21af33fdd6a0657dfddb5831609523c1b5d412115427a0cdd4e07",
+    "board/README.md": "5a7f01460107df0c5c40d2a2b18c68648ca2d7b20c914c788b880ec1b9f6f95b",
     "board/SOURCE_MANIFEST.json": "03d99f1f43bbf68d92df61db52bdee0019723e2e194ee5f9c12a5ac6d4c5a105",
     "board/arty_a7.xdc": "f13869ba386038557084adabafeb5255943d0b67f1db4b88fd907e4f095d016f",
     "board/axi_fullwidth.sv": "bf07ae27724dbd0a361d732dfb57109f06beef207c47a066d400cb06d7f07d5a",
@@ -67,7 +67,23 @@
     "evidence/2026-10-11/tests/uart-boot/RESULT.json": "46fa4f7f8c510a7d15bb28fd5afbecea196e8e6c80d14f4968f6d1215ef8e62a",
     "evidence/2026-10-11/tests/uart-boot/simulation.log": "a3f5e2eeffd05e81ebf75fc9b3db693fa458308c52e27ce6de58710f87746def",
     "evidence/2026-10-11/tests/unit/RESULT.json": "6253cd9add8621d2581c70edae034aafd6ce95ecb78adb4c12813f4297947089",
-    "evidence/README.md": "fcb907b575fddd2d54604201e296c4dced4f34bc3418828edf5a83524eea4aeb",
+    "evidence/2026-10-12/README.md": "8288b95ca8a1986394e0766e384a2aee3915ba08c9d05beb21522b7dc162a8be",
+    "evidence/2026-10-12/hardware/HARDWARE_RESULT.json": "514fe87e3fb0753d416f670b2b8906e98ae6b6ec49b56154e0833e5863f085e7",
+    "evidence/2026-10-12/hardware/MANIFEST.json": "dc06cd7d47777269119de6306c03d71c8ddf20efb9708ebdfbcd983a02993481",
+    "evidence/2026-10-12/hardware/PROGRAM_RESULT.json": "f45536ce8d86fa2a735ab85a9008d662c793f31d3eadc430f426abd09b95c612",
+    "evidence/2026-10-12/hardware/d2xx_load.py": "bf9a8f8c931b71672932f72992cd03d15977d753eebc891800e6aaefa287218f",
+    "evidence/2026-10-12/hardware/dfx_runtime.txt": "b70e818734e3af5f8b01153d47a37c50449a5f53b008fb4f23849ec0f957b0b9",
+    "evidence/2026-10-12/hardware/linux-console.log": "aceb1739620d1b1554b809c849320ed0a5f20f9a6822d1a6c3dd33fca1d6a2d3",
+    "evidence/2026-10-12/hardware/live-console-first.log": "ac97f527e1ec985ba08ae2b1002a2c14ff0a54fbf8078b94ba4dbe421e3ad005",
+    "evidence/2026-10-12/hardware/live-console.log": "fb2b77f67b02c6e73e0b7bf1e2dbf3557c1d0b98ef0d69ac4c42191107e99bd6",
+    "evidence/2026-10-12/hardware/live_check-first.py": "a3e37a9671d8f526d706922cec581727dfa7bb80510789b08b785caa0443583e",
+    "evidence/2026-10-12/hardware/live_check.py": "822eb8fbb846eb0a41a30eadc163a735dc1932dffdded54dd2117f7aaf0c60e8",
+    "evidence/2026-10-12/hardware/load-and-linux.log": "9633ad82626f7e59ed0b503f0263c5d620c6b6276a262e385ae8785649c1bd8e",
+    "evidence/2026-10-12/hardware/program.jou": "9796d9c11dd2f362818c6833a96a9801f14fe25c357fb798db61f00df210d99d",
+    "evidence/2026-10-12/hardware/program.log": "c754d0f5066dbd34b9035fb77ee6e8ef3fe403b03b56b97f5cdd523aba313511",
+    "evidence/2026-10-12/hardware/program_arty.tcl": "fbb62bafb6df602b0f5f638fb05ae4ecc90494ac162b9a5f5ac314200f7a241c",
+    "evidence/2026-10-12/hardware/summarize_hardware.py": "a0f681a64ca0c441fc614bf8c2ccf664e2de86d02d3d2cfe2eb0b99e7f8edefd",
+    "evidence/README.md": "058e5d4580d68897450dd08eb114469007f9d931bfcd5423809cd1d12811cde0",
     "host/load.py": "a62e48b779c9ce1d6f8f6669523e427cf48bd19be3bf50a554dc391b09b3e3b2",
     "patches/buckyball/GemminiBall.scala": "c18ace5c3ae6645c022af809104e4baf35da657a42ab144ce86260327ebab5aa",
     "patches/buckyball/GemminiExCtrl.scala": "ac3ecc72fa7deb5d50c0c42496b19de9d596b4ebaebd24496bf3792c87d85eaf",
@@ -91,7 +107,8 @@
     "patches/gemmini/Tile.scala": "8bee3fc67cbc6702aba72b805c3858e8cbca7cdecbd317a083b77d108a9e6e08",
     "patches/rocket/FPU.scala": "df54736218a12a6ec9f48b93c3d4a626e3e56c8600e3ad712905c481c47e29e3",
     "patches/rocket/SharedFma.scala": "e2b00a7b6d5c70cc58d7e39605cf169eb901e1d3e15f33dc46d0d981e831bcbb",
-    "program.ps1": "2ed75bd9737b468beed1f564cd0b2aadb74294430d232b56dab2a699a342d49c",
+    "program.ps1": "78405622ac77e9e723fd6437f9649d8ce8c8762274b6cdc6d29ccbbd85c039a3",
+    "program.tcl": "0ff928503cf00798dae132117435e34981a176c586d7aa16e587c47877ba031f",
     "project/build.properties": "a59fccae87ea7dba4034abbbf5333eaaa3dbb2fdcfbf37e98e3752f28c4a3892",
     "project/repositories": "063c457354f9a2bd99f0d1c5c51f0fc3d7ffff04894bb4b740538043fb3b61f6",
     "rtl/FpuRfLvt.sv": "bbc9ad168c94204a946b3e107115fae7f6042fd6c7f95807d7af367449e28950",
@@ -111,7 +128,8 @@
     "scripts/resolve_config.py": "1c4fb7d8533e659c7f8cb9e0ef5eb93f06d29a51d6b3e2449efe648f8f74000d",
     "scripts/run_board_regression.py": "7302be4d5517eb315eb37b3ff8972bf17e2fe42990ae1fb6702c43c632515bfd",
     "scripts/start_board_build.py": "8ee1fa0b002d7f8ea7be7597574f4b88cb10a082eab0d43f43071cf80ad3636d",
-    "scripts/verify_target.py": "b54b05005382da6e73355f29ce34fbacaa7f5b06a35bb3c1583bdb1dfb59b305",
+    "scripts/verify_hardware_evidence.py": "60f3555a6b6ac6a9f567cf1b22caca9755bd4179dcea1f6731a70f8bd26a1202",
+    "scripts/verify_target.py": "bbecbf23f70ab873c630651d6e08aae4ff0efa0f2ae0c5f16924a154cb84ffb2",
     "software/build.sh": "908b5678edf5a710187480974c0c699ca8833faede20d044b7131060c3161292",
     "software/linux_system_check.c": "c1cedf2ce6e2583393c9e7f51fe20558c1402b8d81faf2152e8f6eeaf8058315",
     "software/prepare_dependencies.py": "5bf2eca25081e014ff0de67ae0aeb41cb4380a2767a08a109a3bf6c19238b308",

platforms/arty-a7-toy/VALIDATION.md

@@ -46,7 +46,7 @@ simulation or power measurement is claimed. Gemmini stress coverage is limited
 to M8/N32/K8, shift zero and no loop bias; arbitrary tails, cross-K-tile loop
 accumulation and loop bias are not established by that test.
 
-## Physical acceptance still required
+## Package reproducibility
 
 The staged repository package was separately relocated into a fresh Linux
 directory. Scala/Chisel and OpenSBI were recompiled: generated core/RAM and the
@@ -61,9 +61,27 @@ API-key heuristic. The manifest now labels each digest with a `sha256` field;
 source paths, Git revision and digest values are unchanged. Gitleaks 8.30.1
 reports no leaks in the staged PR; no ignore rule or scanner waiver was added.
 
-Physical board revision is unknown; MIG parameters are official Digilent E.0.
-DDR calibration, physical Linux boot and operator execution on hardware remain
-untested. Treat the image as an engineering target for first bring-up.
+## Physical hardware check: 2026-10-12
+
+[The original hardware record](evidence/2026-10-12/README.md) adds evidence from
+the connected Arty A7-100T; the October 11 records remain unchanged.
+
+- Vivado 2025.1 JTAG programming succeeds on XC7A100T, startup status HIGH.
+- All 17,409,032 payload bytes are written to DDR and individually read back
+  before RUN; transfer/readback takes 544.1 seconds. Bitstream and payload hashes
+  match the original implementation and RTL-validated software.
+- Physical OpenSBI v1.9, Linux 6.6.0 and BusyBox shell boot. COW, page protection,
+  FP64 process context, timer and total system-check PASS; process exit status 0.
+  The intentional child SIGSEGV belongs to the passing page-protection oracle.
+- Subsequent shell reads of `/proc/version` and `/proc/meminfo` succeed;
+  MemTotal is 245,784 KiB. Transport restores the original 16 ms FTDI latency.
+
+PCB revision remains unknown; this exact official E.0 MIG image works on the
+connected board. Physical Gemmini operator regression, FP16/FP32 exhaustive
+checks, full 256 MiB DDR sweep, long-duration stability and power measurements
+are still pending. Programming uses volatile SRAM; no configuration flash was
+written. Treat the result as successful first bring-up, not full hardware release.
+
 DRC retains 360 warnings; methodology retains 49 warnings and 16 advisories,
 including DSP pipeline recommendations, MIG clock/reset structure, control-set
 packing and a potential D-cache SDQ address collision. Reports are preserved;

platforms/arty-a7-toy/board/README.md

@@ -2,7 +2,8 @@
 
 Build and programming commands are in [the platform guide](../README.md).
 This directory targets Arty A7-100T `xc7a100tcsg324-1` with official Digilent
-Rev E.0 DDR parameters. Physical board revision and DDR acceptance are pending.
+Rev E.0 DDR parameters. The recorded hardware run passes full payload DDR
+readback and Linux checks; physical PCB revision remains unconfirmed.
 
 - `toy_a7_top.sv`: 100 MHz input, MMCM/BUFG clocks, per-domain reset sequencing,
   physical UART/LED/DDR pins, actual MIG and AXI Clock Converter instances.
@@ -19,7 +20,8 @@ Rev E.0 DDR parameters. Physical board revision and DDR acceptance are pending.
   bitstream. Setup/hold, CDC Critical, bus skew, routing errors and DRC errors
   stop the build. No warning severity downgrade or CDC waiver is applied.
 - `program_arty.tcl`: explicit volatile JTAG programming; exactly one target
-  and one XC7A100T required. It does not program configuration flash.
+  and one XC7A100T required. The platform's `../program.tcl` entry delegates here.
+  The exact script used for first bring-up is also archived with the hardware logs.
 
 `vendor/` contains unmodified pinned Digilent MIG/board inputs and their license.
 Vivado generates proprietary vendor IP into ignored build directories locally.

platforms/arty-a7-toy/evidence/2026-10-12/README.md

@@ -0,0 +1,77 @@
+# First physical Toy/Linux bring-up
+
+The Arty A7-100T was programmed on **2026-10-12, Asia/Shanghai**, using the
+engineering image from [PR #5](https://github.com/DangoSys/fpga/pull/5), commit
+`257b632a533dd98a7c526870edbd21c5a6976d09`. The PCB revision remains unknown;
+MIG uses the pinned official Digilent E.0 parameters.
+
+| Recorded hardware run | Result |
+|---|---|
+| FPGA / programming tool | XC7A100T / Vivado 2025.1 |
+| JTAG / serial | `210319BCC5FCA` / COM5, 1 Mbps |
+| Programming | PASS, startup status HIGH, volatile SRAM |
+| Complete DDR image readback | 17,409,032 bytes, all equal, 544.1 seconds |
+| Software | OpenSBI v1.9, Linux 6.6.0, BusyBox shell |
+| Linux checks / exit status | Five PASS markers / 0 |
+| Timer check | `elapsed_ns=103836000` |
+| Live shell MemTotal | 245,784 KiB |
+| Load, boot and checks | 577.922 seconds |
+
+## Logs and provenance
+
+[`hardware/MANIFEST.json`](hardware/MANIFEST.json) hashes every original artifact;
+[`HARDWARE_RESULT.json`](hardware/HARDWARE_RESULT.json) records the outcome and
+coverage. Files retain their original bytes, timestamps in logs and experiment
+paths. These paths are provenance, not prerequisites for a new checkout.
+
+- [`program.log`](hardware/program.log), [`program.jou`](hardware/program.jou),
+  [`PROGRAM_RESULT.json`](hardware/PROGRAM_RESULT.json): JTAG device selection,
+  programming and startup state. The exact used
+  [`program_arty.tcl`](hardware/program_arty.tcl) is archived alongside them.
+- [`load-and-linux.log`](hardware/load-and-linux.log): complete write/readback
+  progress, verified RUN, boot and Linux checks.
+- [`linux-console.log`](hardware/linux-console.log): original serial bytes;
+  PASS for COW, page protection, FP64 process context, timer and total check.
+- [`live-console-first.log`](hardware/live-console-first.log): process exit
+  status 0, then an unsuccessful auxiliary probe because `uname`/`grep` links
+  are absent in the minimal rootfs. [`live-console.log`](hardware/live-console.log)
+  confirms the kernel, memory and interactive shell using shell builtins.
+- Archived Python files and `dfx_runtime.txt` preserve the actual procedure.
+  The D2XX transport uses the existing host loader unchanged, opens only UART B,
+  temporarily sets latency from 16 to 2 ms, then restores 16 ms. No registry or
+  EEPROM change is made. These archived scripts include local paths; use the
+  maintained platform entry points for a new run.
+
+The page-protection test deliberately triggers a child SIGSEGV. Its parent
+checks the fault and prints PASS; that trace is expected.
+
+## Repeat programming and boot
+
+Use [`../../program.tcl`](../../program.tcl), which resolves and delegates to
+[`../../board/program_arty.tcl`](../../board/program_arty.tcl). From any directory:
+
+```bash
+vivado -mode batch -source /absolute/path/to/platforms/arty-a7-toy/program.tcl \
+  -tclargs /absolute/path/to/toy_a7.bit
+```
+
+The script requires one attached JTAG target and one XC7A100T. On Windows the
+equivalent wrapper is `program.ps1 -Bitstream <path> -VivadoBin <Vivado-bin>`.
+After programming, press BTN0, wait for DDR readiness/LED0, close other serial
+clients and load the software from the platform directory:
+
+```bash
+python host/load.py --port COM5 --check-linux build/board-software/fw_payload.bin
+python -m serial.tools.miniterm COM5 1000000 --eol LF
+```
+
+Choose the actual port. Build products are not committed; follow the platform
+build guide to create the `.bit` and payload. The measured files are identified by:
+
+- Bitstream SHA256: `ccc33c511e613561fb9dd1e9c847bd3b84037da1d078c44cd3de197d55dffde1`.
+- Payload SHA256: `eb2ee34cc1a744498ac63b4e3fae425d4bb06be422ae6d41bd1ead696201134f`.
+
+Programming and DDR contents are volatile; repeat both steps after power loss.
+PCB revision identification, physical Gemmini tests, exhaustive FP16/FP32 checks,
+full DDR sweep, long-duration stability and power measurements remain pending.
+The prior 98.82% Slice utilization and warning/coverage limits still apply.