Add Linux userspace & kernel driver support for CGRA4ML

[JDRadatti]

SUMMARY

This PR adds Linux support for CGRA4ML, enabling inference on the CGRA accelerator from a Linux userspace application on a Zynq FPGA. It introduces a kernel driver with IOCTL-based register access and DMA-coherent buffer management, a userspace platform adapter that overrides the bare-metal runtime.h macros, a shared library (libinference.so), C/Python examples, and a test suite.

CHANGES

New: Linux Kernel Driver (deepsocflow/linux/driver/)

• Character device (/dev/cgra4ml) with IOCTL commands for register access, buffer query, HW reset/start, wait done, and status dump
• 5 DMA-coherent buffers (weights, input, output, ocm0, ocm1) allocated in probe, accessible via mmap with vm_pgoff buffer index

New: Linux Userspace Adapter (deepsocflow/c/deepsocflow_linux.h)

• Macro-override header that replaces direct MMIO register access with IOCTL calls
• Virtual-to-physical address translation for the DMA-coherent weights buffer
• flush_cache becomes a no-op (memory is already DMA-coherent)
• Seamlessly adapts runtim.h; no changes needed to the core inference loop

New: Host Initialization (deepsocflow/linux/host.c)

• host_setup(): opens device, queries buffers via GET_BUFS ioctl, mmaps DMA buffer, loads wbx.bin
• host_cleanup(): unmaps buffer, closes device
• Exported from libinference.so for both C and Python callers

New: Build System (deepsocflow/linux/Makefile)

• Targets: kernel_prepare (clones and configures linux-xlnx), driver (kernel module), lib (libinference.so), linux_example, bundle (collects deployables indo deploy/ dir), bootgen (bitstream conversion to .bit.bin)
• Cross-compilation for aarch64-linux-gnu- with a single make linux target for the full build

New: Examples

• linux_example.c: C inference entry point: host_setup --> run --> print_output --> host_cleanup
• linux_example.py: Python equivalent using ctypes to call into libinference.so

New: Test Suite (deepsocflow/linux/test/)

• reg_test.c: register read/write verification
• ioctl_test.c: IOCTL interface smoke test
• dma_buf_test.c: DMA buffer mmap and pattern write/readback
• run_smoke.sh: test runner
• Comprehensive test README with expected output and test flow diagram

Other fixes & improvements

• Updated Vivado flow TCL to use relative paths instead of hardcoded absolute paths
• Device tree example for CGRA4ML node
• Update README with steps to run on linux

ORGANIZATION

deepsocflow/linux/
├── driver/                # Linux kernel module (cgra4ml_drv.ko)
│   ├── cgra4ml_main.c     # Module probe/remove, ioctl dispatch, mmap 
│   ├── cgra4ml_hw.c       # Register read/write, reset, start, wait done
│   ├── cgra4ml_dma.c      # DMA-coherent buffer alloc/free/mmap
│   ├── cgra4ml_ioctl.h    # Shared userspace-kernel IOCTL definitions
│   ├── cgra4ml_regs.h     # AXI-Lite register map offsets
│   ├── cgra4ml_priv.h     # Driver-private types (cgra4ml_dev, dma_buf)
│   ├── cgra4ml.dts        # Device-tree node example
│   └── Makefile
├── host.c                 # host_setup/host_cleanup (exported from libinference.so)
├── linux_example.c        # C inference example
├── linux_example.py       # Python inference example (ctypes)
├── Makefile               # Top-level Linux build (driver, lib, bundle, bootgen)
└── test/                  # Test suite
    ├── reg_test.c         # Register access test
    ├── ioctl_test.c       # IOCTL interface test
    ├── dma_buf_test.c     # DMA buffer mmap test
    ├── run_smoke.sh       # Automated smoke test
    ├── Makefile           # Test build
    └── README.md

TODO

• Build and deploy a full Linux image using Yocto for production
• Benchmark inference performance on hardware
• Test on PYNQ-Z1 / PYNQ-Z2
• Test on ZCU102 and other ZynqMP platforms
• Test with different Vivado versions
• Add Jupyter notebook example
• libinference.so target in /linux/test/Makefile could be moved to /linux/Makefile

NEED TO FIX

• BOARDSTORE_BRANCH is hardcoded in the Makefile (Hardcoded to 2024.2, but works on my machine, running Vivado 2025.2)
• PROJECT_NAME is hardcoded in the Makefile (Hardcoded to dsf_zcu104)

Contributors:

@allan70627
@JDRadatti