commit 2296e98334fb70f3982baf354471684a12b83ae2
parent 03632b820298e2fbe967e1a85518b4e3563342e6
Author: Vishrut Gurrala <maydayv7@gmail.com>
Date: Tue, 24 Mar 2026 06:34:17 +0530
Week 1: Add README and Use cases (Part 1: Initial definitions)
Diffstat:
2 files changed, 63 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -0,0 +1,53 @@
+# XIIRegexBuilder: FPGA-Accelerated Regular Expression Matching Engine
+
+Group Number: 6
+
+## 1. System Description
+
+Our project is a custom hardware accelerator for high-speed text processing. A C++ compiler translates regular expressions into parallel, one-hot encoded hardware Finite State Machines (FSMs) in Verilog. These FSMs are synthesised onto an FPGA to parse continuous ASCII character streams, bypassing the sequential bottleneck of software-based regex engines.
+
+The host PC communicates with the FPGA over a standard USB-UART serial link at 115200 baud. An included Python terminal UI (`tui.py`) lets you type strings interactively and see per-regex match results, cumulative byte counts, and per-regex hit counters rendered in a colour-coded table.
+
+## 2. Use Cases
+
+- **FIX Protocol Parsing**: High-speed filtering of electronic trading messages (orders/fills) to route data before it reaches the software stack.
+- **Market Data Feed Filtering**: Scanning millions of events per second to discard irrelevant instrument data at line-rate, saving CPU cycles.
+- **Trade Surveillance**: Detecting malicious network patterns (e.g., spoofing, wash trading) continuously across live, high-speed data flows.
+
+## 3. FPGA Relevance
+
+- **Massive Parallelism**: An FPGA evaluates all N regex FSMs simultaneously in a single clock cycle, whereas software throughput degrades linearly as N grows.
+- **Strict Determinism**: Hardware matching ensures a fixed, predictable number of clock cycles per match, eliminating OS scheduling and cache-miss latency variations.
+
+## 4. System Architecture
+
+```text
+[Host PC]
+ │ USB-UART 115200-8N1
+ ▼
+uart_rx ──► uart_rx_fifo (16-byte circular FIFO)
+ │
+ ▼
+ Control FSM ──► top.v (parallel NFA engine)
+ │ │
+ │ match_bus[N-1:0]
+ │ byte_count[31:0]
+ │ match_count_k[15:0]
+ ▼
+ TX Serializer ──► uart_tx ──► [Host PC]
+```
+
+### Hardware Modules
+
+| File | Description |
+| ----------------------- | ------------------------------------------------------------------- |
+| `output/uart_tx.v` | 8-N-1 UART transmitter (parallel-in / serial-out) |
+| `output/uart_rx_fifo.v` | 16-byte circular FIFO (distributed RAM) between RX and engine |
+| `output/top_fpga.v` | Top-level integrating FIFO, NFA engine, counters, TX serializer FSM |
+
+### Response Packet (FPGA → Host)
+
+Every time the NFA engine finishes a string (newline received), the FPGA sends one ASCII line:
+
+```text
+MATCH=<N-bit binary> BYTES=<8 hex digits> HITS=<4hex per regex, comma-separated>\r\n
diff --git a/docs/usecases.md b/docs/usecases.md
@@ -0,0 +1,10 @@
+# Why Hardware Regex Matching Matters
+
+## The Core Problem
+
+Modern financial markets generate enormous volumes of structured text — orders, quotes, news, and trade confirmations — all arriving as high-speed character streams. Firms need to filter, detect, and act on specific patterns within this data faster than any software stack can manage. Hardware regex matching on an FPGA puts that decision as close to the wire as physically possible.
+
+---
+
+## Key Use Cases in Quantitative Finance
+