commit bfaeb9092479d42a4388c7cebf633ba571e0af7c
parent 4218bc760e95ebe88b461025f964d168d9e34efa
Author: Vishrut Gurrala <maydayv7@gmail.com>
Date: Wed, 25 Mar 2026 03:08:34 +0530
Week 1: Add README and Use cases (Part 3: Finalizing)
Diffstat:
2 files changed, 46 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -122,3 +122,41 @@ pip install pyserial rich
python tui.py --port /dev/ttyUSB0 --regexes inputs/regexes.txt
# On Windows: python tui.py --port COM3 --regexes inputs/regexes.txt
```
+
+The TUI auto-detects the first available USB-Serial port if `--port` is omitted.
+
+## 8. File Layout
+
+```text
+XIIRegexBuilder/
+├── inputs/
+│ ├── regexes.txt # one regex per line
+│ └── test_strings.txt # one test string per line
+├── src/
+│ ├── main.cpp # pipeline entry point
+│ ├── lexer.{h,cpp} # tokeniser
+│ ├── parser.{h,cpp} # recursive-descent AST builder
+│ ├── nfa.{h,cpp} # Glushkov NFA construction
+│ ├── emitter.{h,cpp} # Verilog code generator
+│ ├── golden.cpp # C++ std::regex reference
+│ └── parser_tester.cpp # unit-test harness
+├── output/ # generated by `make run`
+│ ├── nfa_0.v … nfa_N.v
+│ ├── top.v
+│ ├── uart_rx.v # UART receiver
+│ ├── uart_tx.v # UART transmitter
+│ ├── uart_rx_fifo.v # Input FIFO
+│ ├── top_fpga.v # FPGA top-level
+│ ├── tb_top.v
+│ ├── constraints.xdc
+│ └── expected_matches.txt
+├── tui.py # Python TUI
+├── scripts/
+│ ├── synth.tcl # Vivado synthesis script
+│ └── program.tcl # Vivado programming script
+├── Makefile
+├── README.md
+├── Specifications.md
+├── details.md
+└── usecase.md
+```
diff --git a/docs/usecases.md b/docs/usecases.md
@@ -23,3 +23,11 @@ Modern financial markets generate enormous volumes of structured text — orders
## Why FPGA and Not Just Faster Software?
The fundamental advantage is parallelism. A software engine checks N regexes sequentially — throughput degrades linearly as N grows. An FPGA runs all N FSMs in the same clock cycle, so throughput is flat regardless of how many patterns are active. At scale, no amount of SIMD optimisation closes that gap.
+
+The second advantage is determinism. Software latency varies with cache state, OS scheduling, and branching behaviour. Hardware latency is a fixed number of clock cycles, every time — essential when a one-microsecond edge translates directly into profit.
+
+---
+
+## The Bottom Line
+
+In quantitative finance, the matching decision needs to happen before any further processing, on a continuous high-speed stream, against many patterns simultaneously, with the lowest and most predictable latency possible. That is precisely the problem this system is designed to solve.