Pynq notebook support

[gflengas]

PYNQ Driver for DeepSoCFlow

Overview

This pull request introduces a PYNQ-based Python driver that replicates the bare-metal C runtime for the DeepSoCFlow CGRA accelerator. The driver enables pure Python workflows on FPGA boards running Linux images with PYNQ notebooks, making it significantly easier to test and validate neural network inference without requiring using Vitis. Both the driver and the notebook can be uploaded to the Jupyter environment once, and then the user can try different models/architectures by simply uploading the configuration, y_exp.txt, wbx.bin, design_1.bit, and design_1.hwh files.

The target board for testing was ZCU102, using vivado 2023.2 for the synthesis.

Key Additions

• xmodel.py: the tool now generates a config.json file (in addition to the existing C header config_fw.h) containing all hardware configuration parameters and bundle definitions in JSON format.
• pynq_driver.py: PYNQ-based driver replacing the bare-metal C runtime
• CGRA4ML_PYNQ.ipynb: Jupyter notebook demonstrating the PYNQ driver usage
• README.md: includes instructions on how to use the framework with the PYNQ driver and notebook

Motivation

My team is exploring ways to run larger Neural Network architectures in FPGAs, in order to deploy directly on a satellite. One of the proposed frameworks was CGRA4ML.

Previously, testing the DeepSoCFlow accelerator on boards required:

• Creating the Vitis project.
• Running it with a breakpoint in order to upload the wbx.bin file.

This PR streamlines the workflow by:

• Generating JSON configuration alongside C headers
• Providing a complete Python driver that mirrors C runtime behavior
• Maintaining bit-accurate compatibility with the bare-metal C runtime, thanks to comparisons with the reference files generated in the vectors folder.

Files

1. deepsocflow/py/pynq_driver.py NEW

Purpose: PYNQ-based driver replacing the bare-metal C runtime

Features:

• Complete implementation with Google-style docstrings
• Memory management matching the C Memory_st structure exactly
• Automatic memory allocation (OCM, weights, biases, buffers)
• Hardware register configuration and PS-PL synchronization
• Full inference pipeline with bundle processing
• Post-processing: bias, quantization, activation (LeakyReLU), pooling, softmax
• Support for residual connections and tiling operations
• Comprehensive inline comments explaining complex hardware interactions

No Functional Constraints: All algorithmic logic maintains bit-accurate compatibility with the C runtime.

2. deepsocflow/py/CGRA4ML_PYNQ.ipynb NEW

Purpose: Jupyter notebook demonstrating the PYNQ driver usage

Features:

• Markdown cells with clearer step-by-step explanations
• Code organization with explicit file path management
• Error handling and validation
• Step-by-step initialization and setup
• Model inference execution
• Automated validation against expected outputs
• Detailed difference reporting for debugging
• Proper resource cleanup

3. deepsocflow/py/xmodel.py EXTENDED

Purpose: Model export tool

New Feature:

• config.json file generation alongside C headers
• Exports complete hardware definitions and bundle configurations

4. README.md EXTENDED

Extended the explanation section on how to run the framework specifically using the PYNQ driver and the notebook.

Complete Workflow

Step 1: Export Model (Development Machine)

1. Run the example

# Edit SIM and SIM_PATH in the file to match your simulator
cd run/work
python ../example.py

2. Bitstream generation

# Make sure correct fpga board was specified in the above script. Default is ZCU102
# Open Xilinx Vivado, cd into deepsocflow, and type the following in TCL console
cd run/work
source vivado_flow.tcl

Step 2: Deploy to target Board

1. Create a new folder for the project on the jupyter enviroment and add the pynq_driver.py and CGRA4ML_PYNQ.ipynb files.
2. Upload the necessary files using either scp command or with the upload utility from jupyter:
   • config.json
   • y_exp.txt
   • wbx.bin
   • design_1.bit and design_1.hwh

Step 3: Run Inference on PYNQ

Open the CGRA4ML_PYNQ notebook, run all the cells and inspect the output of the model.

Configuration File Format

The config.json file contains two main sections:

Hardware Defines

{
  "defines": {
    "N_BUNDLES": 10,
    "PE_ROWS": 4,
    "PE_COLS": 4,
    "X_BITS_L2": 2,
    "W_BYTES": 12345,
    "Y_TYPE_str": "int8",
    "B_TYPE_str": "int16",
    "O_TYPE_str": "int32",
    ...
  }
}

Bundle Configurations

{
  "bundles": [
    {
      "n": 1, "h": 32, "w": 32, "co": 64,
      "is_bias": 1, "is_softmax": 0, "pool": "POOL_NONE",
      "ca_shift": 8, "ca_pl_scale": 0, "ca_nzero": 1,
      "b_val_shift": 0, "b_bias_shift": 0,
      ...
    }
  ]
}

Backward Compatibility

• Existing C runtime workflows unaffected
• config_fw.h still generated for bare-metal C code
• xmodel.py maintains all existing functionality
• No breaking changes to hardware interfaces