PYNQ Vision Operator Deployment
The goal is to align software arrays, hardware interfaces, and verification results. First determine whether the user is deploying a new operator, locating an existing fault, or optimizing performance, while maintaining existing authorizations and project status; do not expand every task into a complete retraining or refactoring.
Minimum Input
Requires algorithm/preprocessing, at least one set of golden input/output, bit/HWH or HLS top-level, a physical board, and the PYNQ environment. If any item is missing, first perform offline checks supported by available materials, and indicate which conclusions still depend on the missing data.
Read the porting guide and fill in the tensor contract. The example is a generic grayscale tensor, not a hardware configuration that can be directly loaded onto any board. A new model must re-determine shape, dtype, layout, color, scaling/padding, quantization scale, rounding, saturation, output decoding, and transfer byte count. Bit-level formats such as packed INT4 require additional packing rules; the existing contract checker only accepts unpacked numeric arrays.
Selecting a Validation Path
- First-time integration: Contract check → fixed-input integer reference → single-frame PL raw output → continuous frames → application accuracy → segmented timing.
- Result mismatch: Save intermediate results at each stage (preprocessing, quantization nodes, PL raw tensor) and locate the first point of divergence; do not modify post-processing thresholds to mask earlier errors.
- Throughput or latency anomaly: Fix input conditions, record frame numbers and timestamps within the same clock domain; use the timing script to separate queuing, PL/DMA, and post-processing.
- Board replacement: Re-identify DMA, address width, cache coherency, clock/reset, and interrupts; retain the golden reference and comparison methodology.
Complete reproducible prompts are available in the workflows; only read the entry corresponding to the current task.
Hardware and Buffering
First distinguish between standard AXI DMA and custom HLS IODMA. For standard simple mode, refer to the adaptation template; custom interfaces must follow register and fixed-length/TLAST contracts. Do not treat Python API names as hardware protocols.
Continuous buffering requires clear ownership: after CPU writes, synchronize to the device; after hardware completes and is no longer accessing, synchronize back to the CPU. On exception, retain in-flight buffers; do not unconditionally free them in finally. See the DMA lifecycle for details.
HWH is an interface description and does not prove that the disk bitstream has been loaded. When binding to an already loaded hardware design, verify the load identity, address, and reference output. If LCD and inference share the PL, do not load two complete Overlays sequentially to obtain combined hardware.
Validation and Optimization
Integer hardware raw outputs should be element-wise identical in principle; for floating-point algorithms, use a pre-specified absolute tolerance, and record dtype and non-finite values. Use the comparison script; do not enlarge tolerance to substitute for interface repair. Evaluate quantization model accuracy and implementation consistency separately.
Also check LUT, Slice, FF, BRAM, DSP, timing, and stream backpressure. Compare FIFO against fixed weights, input, frequency, and parallelism; record model changes separately. Compute throughput as the number of valid completed frames divided by the real measurement window; compute latency as the time between two ends of the same frame, not the sum of stage medians.
Deliver the contract, raw output, identity of source/bit/HWH, inspection results, and measurement scope. Common errors and method failure conditions are listed in the troubleshooting list. Project effectiveness and transfer boundaries are described in the validation notes.