MobileViT FPGA project

This repository contains the MobileViT FPGA RTL, board-interface Tcl, simulation files, and Vivado project scripts.

This work was done as an undergraduate course graduation project for SNU ECE.

Repository layout

rtl/core/        MobileViT compute RTL
rtl/ip/          wrappers for generated Divider Generator and Block Memory Generator IP
rtl/top/         board top-level wrapper (`main`)
rtl/board/       board module-reference RTL used by the block design
rtl/tb/          simulation testbenches
rtl/lut/         lookup-table RTL/header files
rtl/sim_ip/      behavioral stand-ins for generated IP, used only by simulator flows
lut/             `$readmemh` payloads
board/bd/        interface block-design Tcl
board/constraints/ board timing/reference constraints
vivado/tcl/      project, IP, and implementation Tcl flows
vivado/sim.f     short Icarus design file list
vivado/synth.f   short Vivado synthesis file list
scripts/         short shell/PowerShell/batch helpers
hw_test/         Python host-side board interaction and hardware smoke-test utilities
hw_test/datasets/ dataset payloads used by host-side board tests (download separately)
docs/            detailed usage notes

RTL Hierarchy

mobilevit_top
└─ mobilevit_board
   └─ mobilevit_core
      ├─ axi_lite_apb
      ├─ apb_regs
      └─ mobilevit_runner
         ├─ model_controller
         ├─ stream_loader / stream_storer
         ├─ memory_subsystem
         │  └─ sram_* memories
         ├─ stem_rolling / stem_block
         ├─ mv2_block
         │  └─ dw_engine
         ├─ mvit_block
         ├─ mobilevit_transformer
         │  ├─ layernorm_core
         │  │  └─ layernorm_seq
         │  │     └─ rsqrt_fixed_q14
         │  └─ mobilevit_attention_core
         │     └─ divnorm_perden
         ├─ qkv_scratch
         │  └─ qkv_bank
         ├─ pe_array_8x16
         ├─ pw_linear
         ├─ pw_tile_engine
         ├─ transformer_out
         ├─ cls_head_engine
         └─ cls_engine

Create a Vivado project

The source tree and the Vivado project directory may live in different locations. Open Vivado Tcl Console and run:

set ::MVIT_SRC_DIR  {C:/git/mvit}
set ::MVIT_PROJ_DIR {D:/vivado_projects/mvit_board_prj}
set ::MVIT_PART     {xc7a100tcsg324-1}

source [file join $::MVIT_SRC_DIR vivado tcl create_board_project.tcl]
launch_runs synth_1 -jobs 4

This creates the Vivado project under MVIT_PROJ_DIR, regenerates the interface block design, creates the compute IP, adds RTL from MVIT_SRC_DIR, and sets the synthesis top to main.

For step-by-step commands, see docs/BOARD_TCL.md and vivado/tcl/console_board_walkthrough.tcl.

Simulation

Linux/macOS with Icarus Verilog:

./scripts/full.sh

Windows PowerShell:

.\scripts\full.ps1

Windows cmd:

scripts\full.bat

Simulation requirements and environment variables are documented in docs/SIM.md.

Hardware host test (hw_test/)

hw_test/ is used for Python-side host interaction with the FPGA board after bitstream generation. It is separated from RTL simulation so that board execution, APB register checks, model launch, VDMA status checks, and output capture can be run from a single host script.

Expected layout:

hw_test/
├─ README.md                    host-side usage notes
├─ board_test.py                main Python entry point for board execution
├─ host_driver.py               serial/APB helper functions
├─ expected/
│  └─ expected_output.mem       reference output for the provided test vector
└─ datasets/
   └─ ...                       input/weight/model payloads

Full model-flow testbench

Command:

./scripts/full.sh

Reproducibility notes

The default board configuration is intended to be the reproducible FPGA implementation target.

Vivado version: see Environment
Top module: main
Board part: xc7a100tcsg324-1
Project creation entry point: vivado/tcl/create_board_project.tcl
Host-side test entry point: hw_test/board_test.py

Environment

tested with Vivado 23.1, Windows 11, Python 3.11.10, Icarus Verilog / iverilog