fpgasystems · JonasDann · Jan 7, 2026 · Jan 7, 2026 · Jan 8, 2026 · Jan 11, 2026
diff --git a/.env b/.env
@@ -1 +1 @@
-PYTHONPATH=build_hw:coyote/sim
+PYTHONPATH=hardware/build_hw:coyote/sim
diff --git a/.gitignore b/.gitignore
@@ -1,10 +1,11 @@
-build_hw/**
+build
+hardware/build_hw
 
 # Generated unit test files
-unit-tests/diff/**
-unit-tests/sim_dump.vcd
-unit-tests/sim.out
-unit-tests/vapor_view.json
+hardware/unit-tests/diff/**
+hardware/unit-tests/sim_dump.vcd
+hardware/unit-tests/sim.out
+hardware/unit-tests/vapor_view.json
 
 # Vivado generated files
 *.jou

diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -2,7 +2,7 @@
     "python.testing.unittestArgs": [
         "-v",
         "-s",
-        "./unit-tests",
+        "./hardware/unit-tests",
         "-p",
         "*_test.py"
     ],

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,20 +1,9 @@
-cmake_minimum_required(VERSION 3.0)
+cmake_minimum_required(VERSION 3.16)
 project(libstf)
 
-set(CYT_DIR ${CMAKE_SOURCE_DIR}/coyote/)
-set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${CYT_DIR}/cmake)
+# NOTE: This CMakeLists.txt is only here because of VSCode
 
-find_package(CoyoteHW REQUIRED)
+# Find dependencies
+add_subdirectory(coyote/sw coyote)
 
-set(N_REGIONS 1)
-set(EN_STRM 1)
-set(N_STRM_AXI 4)
-set(FDEV_NAME u55c)
-
-validation_checks_hw()
-
-load_apps (
-    VFPGA_C0_0 "src"
-)
-
-create_hw()
+add_subdirectory(software)
diff --git a/README.md b/README.md
@@ -12,44 +12,64 @@
 This library is a collection of common modules used to develop hardware designs. Some modules are 
 specific to developing vFPGAs for Coyote. The main functionality libstf offers is:
 
-- Interfaces that transport a specific number of elements, adapters to AXI4S interfaces, and other helpers (src/data_interfaces.sv and src/hdl/stream)
-- Utilities for configuration registers accessed through an AXI4L interface (src/hdl/config)
-- Crossbar (src/hdl/crossbar)
-- Dictionary (src/hdl/dict)
-- Stream normalization (src/hdl/normalization)
-- vFPGA-specific stream output writer that generates memory requests and communicates with a memory manager on the CPU side (src/hdl/output)
+- Interfaces that transport a specific number of elements (ndata), adapters to AXI4S interfaces, and other helpers (hardware/src/data_interfaces.sv and hardware/src/hdl/stream)
+- Utilities for configuration registers accessed through an AXI4L interface (hardware/src/hdl/config)
+- Crossbar (hardware/src/hdl/crossbar)
+- Dictionary (hardware/src/hdl/dict)
+- Stream normalization (hardware/src/hdl/normalization)
+- Coyote vFPGA-specific stream output writer that generates memory requests and communicates with a output buffer manager on the CPU side (hardware/src/hdl/output)
 
-This library is *work in progress*.
+It also features some of the corresponding software-side components to use the hardware. This 
+repository is *work in progress* and quite a bit of documentation is missing. Please feel free to 
+contribute.
 
-## Getting Started
+## Getting Started (Hardware)
 Clone the repo and download the Coyote submodule:
 ```bash
 git clone --recurse-submodules https://github.com/fpgasystems/libstf
 ```
 
 The recommended way to get started with libstf is to start exploring the Python unit tests in the 
-`unit-tests` folder. To execute the unit tests, you have to set up the Coyote simulation project 
-with:
+`hardware/unit-tests` folder. To execute the unit tests, you have to set up the Coyote simulation 
+project with:
 
 ```bash
 ./sim_setup.sh
 ```
 
-This creates the `build_hw` folder. Anytime you create or rename files in `src/hdl`, you have to 
-execute this command again. Afterwards, the unit tests should show up in VSCode.
+This creates the `hardware/build_hw` folder. Anytime you create or rename files in `src/hdl`, you 
+have to execute this command again. Afterwards, the unit tests should show up in VSCode.
+
+## Getting Started (Software)
+You have to install jemalloc which is required for the HugePageMemoryPool like this:
+
+```bash
+./scripts/install_jemalloc.sh
+```
+
+This will install jemalloc in `~/opt/jemalloc`. The you can build the libstf library as follows:
+
+```bash
+mkdir build && cd build
+cmake -DCMAKE_PREFIX_PATH=$HOME/opt ..
+make
+```
+
+Notice the `-DCMAKE_PREFIX_PATH=$HOME/opt`: this is so that CMake will look in the path where
+jemalloc has been installed with the script and link libstf against it.
 
 ## Code Style
 For now, we have a couple of code style rules:
 
 - Camel case for class names and snake case for file names and everything else in the code
-- _i postfix for interfaces
-- _t postfix for types
+- _i suffix for interfaces
+- _t suffix for types
 - n_ prefix for next signals in state logic
 - inst_ prefix for module instantiations
-- *Width* always refers to width in bits and *size* to width in bytes
+- The term *width* always refers to width in bits and *size* to width in bytes
 
 ## TODOs
-1. Get types and NUM_ELEMENTS from interface instead of parameters
+1. Get types and NUM_ELEMENTS from interface instead of parameters (on hold because this crashes Vivado sometimes)
 2. Add interface assertions
 
 ## License

diff --git a/coyote b/coyote
diff --git a/hardware/CMakeLists.txt b/hardware/CMakeLists.txt
@@ -0,0 +1,20 @@
+cmake_minimum_required(VERSION 3.0)
+project(libstf)
+
+set(CYT_DIR ${CMAKE_SOURCE_DIR}/../coyote)
+set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${CYT_DIR}/cmake)
+
+find_package(CoyoteHW REQUIRED)
+
+set(N_REGIONS 1)
+set(EN_STRM 1)
+set(N_STRM_AXI 4)
+set(FDEV_NAME u55c)
+
+validation_checks_hw()
+
+load_apps (
+    VFPGA_C0_0 "src"
+)
+
+create_hw()
diff --git a/src/hdl/axi/axi_demultiplexer.sv → hardware/src/hdl/axi/axi_demultiplexer.sv b/src/hdl/axi/axi_demultiplexer.sv → hardware/src/hdl/axi/axi_demultiplexer.sv
diff --git a/hardware/src/hdl/axi/axi_multiplexer.sv b/hardware/src/hdl/axi/axi_multiplexer.sv
@@ -0,0 +1,48 @@
+`timescale 1ns / 1ps
+
+import libstf::*;
+
+module AXIMultiplexer #(
+    parameter NUM_STREAMS
+) (
+    input logic clk,
+    input logic rst_n,
+
+    ready_valid_i.s select, // #(logic[$clog2(NUM_STREAMS) - 1:0])
+
+    AXI4S.s in[NUM_STREAMS],
+    AXI4S.m out
+);
+
+ndata_i #(data8_t, AXI_DATA_BITS / 8) in_data[NUM_STREAMS]();
+ndata_i #(data8_t, AXI_DATA_BITS / 8) out_data();
+
+for (genvar I = 0; I < NUM_STREAMS; I++) begin
+    assign in_data[I].data  = in[I].tdata;
+    assign in_data[I].keep  = in[I].tkeep;
+    assign in_data[I].last  = in[I].tlast;
+    assign in_data[I].valid = in[I].tvalid;
+    assign in[I].tready     = in_data[I].ready;
+end
+
+DataMultiplexer #(
+    .data_t(data8_t),
+    .NUM_ELEMENTS(AXI_DATA_BITS / 8),
+    .NUM_STREAMS(NUM_STREAMS)
+) inst_mux (
+    .clk(clk),
+    .rst_n(rst_n),
+
+    .select(select),
+
+    .in(in_data),
+    .out(out_data)
+);
+
+assign out.tdata      = out_data.data;
+assign out.tkeep      = out_data.keep;
+assign out.tlast      = out_data.last;
+assign out.tvalid     = out_data.valid;
+assign out_data.ready = out.tready;
+
+endmodule
diff --git a/src/hdl/axi/axi_width_converter.sv → hardware/src/hdl/axi/axi_width_converter.sv b/src/hdl/axi/axi_width_converter.sv → hardware/src/hdl/axi/axi_width_converter.sv
diff --git a/src/hdl/common.sv → hardware/src/hdl/common.sv b/src/hdl/common.sv → hardware/src/hdl/common.sv
diff --git a/src/hdl/config/config_interfaces.sv → hardware/src/hdl/config/config_interfaces.sv b/src/hdl/config/config_interfaces.sv → hardware/src/hdl/config/config_interfaces.sv
diff --git a/src/hdl/config/config_macros.svh → hardware/src/hdl/config/config_macros.svh b/src/hdl/config/config_macros.svh → hardware/src/hdl/config/config_macros.svh
diff --git a/src/hdl/config/global_config.sv → hardware/src/hdl/config/global_config.sv b/src/hdl/config/global_config.sv → hardware/src/hdl/config/global_config.sv
diff --git a/src/hdl/config/mem_config.sv → hardware/src/hdl/config/mem_config.sv b/src/hdl/config/mem_config.sv → hardware/src/hdl/config/mem_config.sv
diff --git a/src/hdl/config/read_config_splitter.sv → ...re/src/hdl/config/read_config_splitter.sv b/src/hdl/config/read_config_splitter.sv → ...re/src/hdl/config/read_config_splitter.sv
diff --git a/.../config/registers/config_read_register.sv → .../config/registers/config_read_register.sv b/.../config/registers/config_read_register.sv → .../config/registers/config_read_register.sv
diff --git a/...ig/registers/config_read_register_file.sv → ...ig/registers/config_read_register_file.sv b/...ig/registers/config_read_register_file.sv → ...ig/registers/config_read_register_file.sv
diff --git a/...hdl/config/registers/config_write_fifo.sv → ...hdl/config/registers/config_write_fifo.sv b/...hdl/config/registers/config_write_fifo.sv → ...hdl/config/registers/config_write_fifo.sv
diff --git a/.../registers/config_write_ready_register.sv → .../registers/config_write_ready_register.sv b/.../registers/config_write_ready_register.sv → .../registers/config_write_ready_register.sv
diff --git a/...config/registers/config_write_register.sv → ...config/registers/config_write_register.sv b/...config/registers/config_write_register.sv → ...config/registers/config_write_register.sv
diff --git a/src/hdl/config/stream_config.sv → hardware/src/hdl/config/stream_config.sv b/src/hdl/config/stream_config.sv → hardware/src/hdl/config/stream_config.sv
@@ -4,7 +4,6 @@
 `include "config_macros.svh"
 
 module StreamConfig #(
-    parameter NUM_SELECT,
     parameter NUM_STREAMS
 ) (
     input logic clk,

diff --git a/src/hdl/config/write_config_splitter.sv → ...e/src/hdl/config/write_config_splitter.sv b/src/hdl/config/write_config_splitter.sv → ...e/src/hdl/config/write_config_splitter.sv
diff --git a/src/hdl/crossbar/coupler.sv → hardware/src/hdl/crossbar/coupler.sv b/src/hdl/crossbar/coupler.sv → hardware/src/hdl/crossbar/coupler.sv
diff --git a/src/hdl/crossbar/creditor.sv → hardware/src/hdl/crossbar/creditor.sv b/src/hdl/crossbar/creditor.sv → hardware/src/hdl/crossbar/creditor.sv
diff --git a/src/hdl/crossbar/crossbar.sv → hardware/src/hdl/crossbar/crossbar.sv b/src/hdl/crossbar/crossbar.sv → hardware/src/hdl/crossbar/crossbar.sv
diff --git a/src/hdl/crossbar/decoupler.sv → hardware/src/hdl/crossbar/decoupler.sv b/src/hdl/crossbar/decoupler.sv → hardware/src/hdl/crossbar/decoupler.sv
diff --git a/src/hdl/crossbar/reorder.sv → hardware/src/hdl/crossbar/reorder.sv b/src/hdl/crossbar/reorder.sv → hardware/src/hdl/crossbar/reorder.sv
diff --git a/src/hdl/crossbar/reorder_decoupler.sv → ...are/src/hdl/crossbar/reorder_decoupler.sv b/src/hdl/crossbar/reorder_decoupler.sv → ...are/src/hdl/crossbar/reorder_decoupler.sv
diff --git a/src/hdl/crossbar/reorder_enumerator.sv → ...re/src/hdl/crossbar/reorder_enumerator.sv b/src/hdl/crossbar/reorder_enumerator.sv → ...re/src/hdl/crossbar/reorder_enumerator.sv
diff --git a/src/hdl/crossbar/tagged_duplicator.sv → ...are/src/hdl/crossbar/tagged_duplicator.sv b/src/hdl/crossbar/tagged_duplicator.sv → ...are/src/hdl/crossbar/tagged_duplicator.sv
diff --git a/src/hdl/crossbar/tagged_multiplexer.sv → ...re/src/hdl/crossbar/tagged_multiplexer.sv b/src/hdl/crossbar/tagged_multiplexer.sv → ...re/src/hdl/crossbar/tagged_multiplexer.sv
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		PYTHONPATH=build_hw:coyote/sim
		PYTHONPATH=hardware/build_hw:coyote/sim
+2 −2		contrib/vm/driver-guest/guest_dev.h
+7 −2		driver/include/coyote_defs.h
+7 −0		driver/src/coyote_setup.c
+173 −30		driver/src/vfpga/vfpga_gup.c
+1 −1		driver/src/vfpga/vfpga_isr.c
+10 −10		driver/src/vfpga/vfpga_ops.c
+53 −0		hw/hdl/mmu/axis_last_rewriter.sv
+32 −12		hw/hdl/mmu/mmu_assign.sv
+8 −2		hw/hdl/mmu/mmu_top.sv
+6 −0		hw/hdl/pkg/axi_intf.sv
+2 −0		hw/hdl/pkg/lynx_intf.sv
+37 −20		hw/templates/dynamic_top_tmplt.txt
+204 −204		hw/templates/lynx_pkg_tmplt.txt
+91 −91		hw/templates/user_wrapper_tmplt.txt
+8 −4		sim/hw/c_axil.svh
+23 −7		sim/hw/ctrl_simulation.svh
+1 −0		sim/sw/include/BinaryInputWriter.hpp
+24 −10		sim/sw/include/BinaryOutputReader.hpp
+33 −17		sim/sw/include/BlockingQueue.hpp
+152 −0		sim/sw/include/Broadcast.hpp
+4 −8		sim/sw/include/Common.hpp
+60 −16		sim/sw/src/cThread.cpp
+29 −3		sw/include/cDefs.hpp
+47 −10		sw/src/cThread.cpp
+108 −0		util/README.md
+82 −0		util/launch_with_numa_bound.sh