Merge branch 'main' of https://github.com/vicharak-in/shrike

Author: dpks2003

docs/getting_started.md

@@ -102,7 +102,7 @@ We have already generated and hosted a bitstream to blink led [here](https://git
 
 Checkout guide to learn how to generate your own fpga design [here](./generating_your_first_bitstream.md).
 
-Onces you have done this go to arduino and hit compile your compilation should finish without error if error occurs don't we have s discord hope on there. 
+Once you have done this, open Arduino IDE and click on Compile. The compilation should complete without any errors. If you encounter any errors, don’t worry—we have a Discord community. Hop in there and we’ll help you out.
 
 If the compilation has been done without any error then it's time to connect the board in boot mode " PRESS THE BOOT BUTTON WHILE CONNECTING THE BOARD WITH PC" ( this should be done only the first time of setting up if arduino are if you have programmed the board with any other way last time).
 

docs/introduction.md

@@ -25,9 +25,10 @@ The beauty of this setup is that you can reprogram the FPGA an unlimited number
 As discussed earlier, we’ll need to learn how compilation works for both systems: the FPGA and the micro-controller (RP2350/RP2040).
 
 The binary files that the FPGA understands are called **bitstreams**.  
-Follow the guide here to learn how to generate a bitstream for the FPGA:  [Generating Your First Bitstream](https://vicharak-in.github.io/shrike-lite/generating_your_first_bitstream.html)
+Follow the guide here to learn how to generate a bitstream for the FPGA: 
+ [Generating Your First Bitstream](https://vicharak-in.github.io/shrike/generating_your_first_bitstream.html)
 
 Once you have the bitstream, you’re ready to load it into the FPGA through a microcontroller (RP2040) program.
 
 We’ll start with a simple blink-LED example to say hello to the world of hardware.  
-Along the way, we’ll also set up the required software and toolchain.
+Along the way, we’ll also set up the required software and toolchain.

docs/reading_list.md

@@ -26,6 +26,6 @@ This is a compilation of the resources and references suggested for Shrike and F
 
 
 ## 3. Communities to Join
-1. [ULX3S](https://discord.gg/WwWtuk5w)
-2. [TinyVision](https://discord.gg/RQXEF59m)
-3. [1bitsquared](https://discord.gg/nrnGxCuF)
+1. ULX3S
+2. TinyVision
+3. 1bitsquared

examples/Vector-4/README.md

@@ -0,0 +1,103 @@
+# Vector - 4
+
+This project implements a custom **4-bit Soft-Core CPU** on the Vicharak's **Shrike Lite** board. 
+
+Instead of using physical buttons and LEDs, this CPU is controlled entirely via **SPI**. The RP2040 acts as the master, sending instructions, loading memory, and single-stepping the clock.
+
+---
+
+## System Architecture
+
+The system is a hybrid design:
+* **RP2040 (Master):** Handles the high-level logic, user interface, and controls the CPU execution.
+* **FPGA (Slave):** Contains the CPU core, memory (RAM/ROM), and ALU.
+
+### Specifications
+| Feature | Detail |
+| :--- | :--- |
+| **Data Width** | 4-bit (Nibble) |
+| **Address Space** | 16 lines of Program Memory, 16 slots of Data Memory |
+| **Clocking** | Manual Stepping via SPI (Synchronous to FPGA System Clock) |
+| **Interface** | 8-bit SPI Packet (Command + Payload) |
+
+---
+<img width="2816" height="1536" alt="Vector-4 Schematic" src="https://github.com/user-attachments/assets/e860ca24-936c-403d-bab5-7254de5bde37" />
+
+## The SPI Interface
+
+To interact with the CPU, the RP2040 sends **8-bit packets** over SPI. The FPGA replies simultaneously with the current CPU state.
+
+### Input Packet (RP2040 -> FPGA)
+| Bit [7:4] | Bit [3:2] | Bit [1] | Bit [0] |
+| :---: | :---: | :---: | :---: |
+| **DATA Payload** | **INSTRUCTION** | **RESET** | **STEP** |
+| 4-bit Value | Mode Selector | 1 = Reset CPU | 1 = Execute Cycle |
+
+* **DATA Payload:** The number to be loaded into memory or the PC.
+* **INSTRUCTION:**
+    * `00` **LOADPROG**: Write payload to Program Memory at current PC.
+    * `01` **LOADDATA**: Write payload to Data Memory at current PC.
+    * `10` **SETRUNPT**: Set the Program Counter (PC) to the payload value.
+    * `11` **RUNPROG**: Normal execution mode.
+* **RESET:** Active High. Clears PC, Registers, and Memory.
+* **STEP:** Rising-edge trigger. The CPU executes **one cycle** per packet where this bit is `1`.
+
+### Output Packet (FPGA -> RP2040)
+| Bit [7:4] | Bit [3:0] |
+| :---: | :---: |
+| **REGVAL** | **PC** |
+| Current Accumulator Value | Current Program Counter |
+
+---
+
+## Instruction Set Architecture (ISA)
+
+The CPU supports 16 operations. These opcodes are stored in the **Program Memory**.
+
+| Opcode | Name | Description |
+| :--- | :--- | :--- |
+| `0` | **LOAD** | `Reg = Data[PC]` (Immediate Load) |
+| `1` | **STORE** | `Data[Address] = Reg` (Indirect Store) |
+| `2` | **ADD** | `Reg = Reg + Data[PC]` |
+| `3` | **MUL** | `Reg = Reg * Data[PC]` |
+| `4` | **SUB** | `Reg = Reg - Data[PC]` |
+| `5` | **SHIFTL** | Left Shift |
+| `6` | **SHIFTR** | Right Shift |
+| `7` | **JUMPTOIF**| Jump to `Data[PC]` if the MSB of Input (Bit 7) is High |
+| `8` | **LOGICAND**| Logical AND (`&&`) |
+| `9` | **LOGICOR** | Logical OR (`\|\|`) |
+| `10`| **EQUALS** | `Reg = (Reg == Data[PC])` |
+| `11`| **NEQ** | `Reg = (Reg != Data[PC])` |
+| `12`| **BITAND** | Bitwise AND (`&`) |
+| `13`| **BITOR** | Bitwise OR (`\|`) |
+| `14`| **LOGICNOT**| Logical NOT (`!`) |
+| `15`| **BITNOT** | Bitwise NOT (`~`) |
+
+---
+
+## Hardware Connections
+
+This design was tested using the following connections between the Shrike Lite FPGA (Slave) and the RP2040 (Master).
+
+### Top Module Interface
+These signals correspond to the top-level Verilog module (`top.v`).
+
+| Signal        | Direction | Description                          |
+|---------------|-----------|--------------------------------------|
+| `clk`         | In        | System clock (50 MHz typical)        |
+| `clk_en`      | Out       | Clock enable (always 1)              |
+| `rst_n`       | In        | Reset Pin (active low)               |
+| `spi_ss_n`    | In        | Input target select signal (active low) |
+| `spi_sck`     | In        | Input SPI clock signal               |
+| `spi_mosi`    | In        | Input from controller (Master Out)   |
+| `spi_miso`    | Out       | Output to controller (Master In)     |
+
+### Pin Mapping Table
+
+| Signal Function | FPGA Pin (GPIO) | RP2040 Pin | Direction |
+| :--- | :---: | :---: | :--- |
+| **SPI Clock** | 3 | 2 | RP2040 Output -> FPGA Input |
+| **Chip Select** | 4 | 1 | RP2040 Output -> FPGA Input |
+| **MOSI** | 5 | 3 | RP2040 Output -> FPGA Input |
+| **MISO** | 6 | 0 | FPGA Output -> RP2040 Input |
+| **Reset** | 18 | 14 | RP2040 Output -> FPGA Input |

examples/Vector-4/firmware/micropython/vector-4.py

@@ -0,0 +1,245 @@
+from machine import Pin, SPI
+import time
+
+# --- PIN DEFINITIONS ---
+SCK  = 2
+CS   = 1
+MOSI = 3
+MISO = 0
+RST  = 14
+
+# --- INSTRUCTION SET ---
+OP_LOAD     = 0
+OP_STORE    = 1
+OP_ADD      = 2
+OP_MUL      = 3
+OP_SUB      = 4
+OP_SHIFTL   = 5
+OP_SHIFTR   = 6
+OP_JUMPTOIF = 7
+OP_LOGICAND = 8
+OP_LOGICOR  = 9
+OP_EQUALS   = 10
+OP_NEQ      = 11
+OP_BITAND   = 12
+OP_BITOR    = 13
+OP_LOGICNOT = 14
+OP_BITNOT   = 15
+
+# --- MODES ---
+MODE_LOADPROG = 0
+MODE_LOADDATA = 1
+MODE_SETRUNPT = 2
+MODE_RUNPROG  = 3
+
+# --- SETUP ---
+print("\n=== 4-BIT CPU FINAL VERIFICATION ===")
+
+reset_pin = Pin(RST, Pin.OUT, value=1)
+
+def hard_reset():
+    reset_pin.value(0)
+    time.sleep(0.05)
+    reset_pin.value(1)
+    time.sleep(0.1)
+
+# Lowered baudrate to 50kHz for maximum stability
+cs = Pin(CS, Pin.OUT, value=1)
+spi = SPI(0, baudrate=50_000, polarity=0, phase=0, bits=8, firstbit=SPI.MSB,
+          sck=Pin(SCK), mosi=Pin(MOSI), miso=Pin(MISO))
+
+# --- HELPERS ---
+
+def send_packet(data, instr, reset, step):
+    packet = 0
+    packet |= (data & 0x0F) << 4
+    packet |= (instr & 0x03) << 2
+    packet |= (reset & 0x01) << 1
+    packet |= (step & 0x01) << 0
+    
+    tx = bytes([packet])
+    rx = bytearray(1)
+    
+    cs.value(0)
+    time.sleep(0.005) # Increased delay for stability
+    spi.write_readinto(tx, rx)
+    time.sleep(0.005)
+    cs.value(1)
+    time.sleep(0.02)
+    return rx[0]
+
+def read_state():
+    resp = send_packet(0, 0, 0, 0)
+    reg = resp >> 4
+    pc = resp & 0x0F
+    return pc, reg
+
+def write_prog(addr, opcode):
+    send_packet(addr, MODE_SETRUNPT, 0, 1)
+    send_packet(opcode, MODE_LOADPROG, 0, 1)
+
+def write_data(addr, val):
+    send_packet(addr, MODE_SETRUNPT, 0, 1)
+    send_packet(val, MODE_LOADDATA, 0, 1)
+
+def check(test_name, expected_reg, expected_pc=None):
+    pc, reg = read_state()
+    pc_match = True if expected_pc is None else (pc == expected_pc)
+    reg_match = (reg == expected_reg)
+    
+    if pc_match and reg_match:
+        print(f"  [PASS] {test_name}")
+    else:
+        print(f"  [FAIL] {test_name}")
+        print(f"         Got PC:{pc} REG:{reg}")
+        print(f"         Exp PC:{expected_pc if expected_pc is not None else 'Any'} REG:{expected_reg}")
+
+def peek_data(addr):
+    """Safely reads data at addr by temporarily swapping Opcode to LOAD"""
+    # 1. Save current opcode (we assume we know what it is or overwrite it later)
+    # Since we are in a test, we will just restore what we expect.
+    
+    # 2. Write LOAD opcode to this address
+    write_prog(addr, OP_LOAD)
+    
+    # 3. Execute it
+    send_packet(addr, MODE_SETRUNPT, 0, 1)
+    send_packet(0, MODE_RUNPROG, 0, 1)
+    
+    # 4. Read Result
+    pc, reg = read_state()
+    return reg
+
+# --- TESTS ---
+
+def test_arithmetic():
+    print("\n--- Test 1: Arithmetic ---")
+    
+    # 1. SETUP DATA
+    write_data(0, 3) 
+    write_data(1, 2) 
+    write_data(2, 3) 
+    write_data(3, 2) # CHANGED: Using 2 for MUL test (2*2=4)
+    
+    # 2. SETUP PROGRAM
+    write_prog(0, OP_LOAD)
+    write_prog(1, OP_ADD)
+    write_prog(2, OP_SUB)
+    write_prog(3, OP_MUL)
+    
+    # 3. RUN
+    send_packet(0, MODE_SETRUNPT, 0, 1) 
+    
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    check("LOAD 3", 3)
+    
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    check("ADD 2 (3+2=5)", 5)
+    
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    check("SUB 3 (5-3=2)", 2)
+    
+    # DEBUG: Verify Data[3] using the "Peek" method
+    # This checks the memory without running MUL
+    val_at_3 = peek_data(3)
+    print(f"  [DEBUG] Data[3] read as: {val_at_3} (Expected 2)")
+    
+    # RESTORE Program[3] to MUL (because peek_data changed it to LOAD)
+    write_prog(3, OP_MUL)
+    
+    # Restore REG to 2 (Peek corrupted it)
+    write_data(15, 2) # scratchpad
+    write_prog(15, OP_LOAD)
+    send_packet(15, MODE_SETRUNPT, 0, 1)
+    send_packet(0, MODE_RUNPROG, 0, 1) # Reg is now 2
+    
+    # Now set PC to 3 and Run MUL
+    send_packet(3, MODE_SETRUNPT, 0, 1) 
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    check("MUL 2 (2*2=4)", 4)
+
+def test_logic():
+    print("\n--- Test 2: Logic & Bitwise ---")
+    write_data(0, 5)
+    write_data(1, 3)
+    
+    write_prog(0, OP_LOAD)
+    write_prog(1, OP_BITAND)
+    
+    send_packet(0, MODE_SETRUNPT, 0, 1)
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    check("BITAND (5 & 3 = 1)", 1)
+    
+    # BITOR
+    write_prog(0, OP_LOAD)
+    write_prog(1, OP_BITOR)
+    send_packet(0, MODE_SETRUNPT, 0, 1)
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    check("BITOR (5 | 3 = 7)", 7)
+
+def test_shifts():
+    print("\n--- Test 3: Bit Shifts ---")
+    write_data(0, 1)
+    write_data(1, 2)
+    write_prog(0, OP_LOAD)
+    write_prog(1, OP_SHIFTL)
+    
+    send_packet(0, MODE_SETRUNPT, 0, 1)
+    send_packet(0, MODE_RUNPROG, 0, 1)
+    send_packet(0, MODE_RUNPROG, 0, 1)
+    check("SHIFTL (1 << 2 = 4)", 4)
+
+def test_memory():
+    print("\n--- Test 4: Memory (STORE) ---")
+    write_data(0, 9)
+    write_data(1, 5)
+    write_data(2, 0)
+    
+    write_prog(0, OP_LOAD)   
+    write_prog(1, OP_STORE) 
+    write_prog(2, OP_LOAD)   
+    write_prog(5, OP_LOAD)   
+    
+    send_packet(0, MODE_SETRUNPT, 0, 1)
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    
+    send_packet(5, MODE_SETRUNPT, 0, 1)
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    
+    check("STORE/LOAD Roundtrip", 9)
+
+def test_jump():
+    print("\n--- Test 5: Branching (JUMPTOIF) ---")
+    
+    # 1. CLEANUP
+    write_data(15, 0)       
+    write_prog(15, OP_LOAD) 
+    send_packet(15, MODE_SETRUNPT, 0, 1)
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+
+    # 2. SETUP JUMP TEST
+    write_data(0, 5) 
+    write_prog(0, OP_JUMPTOIF)
+    
+    # CASE A: Jump NOT taken
+    send_packet(0, MODE_SETRUNPT, 0, 1)
+    send_packet(0, MODE_RUNPROG, 0, 1) 
+    check("Jump Not Taken (PC->1)", 0, expected_pc=1)
+    
+    # CASE B: Jump TAKEN
+    send_packet(0, MODE_SETRUNPT, 0, 1)
+    send_packet(8, MODE_RUNPROG, 0, 1) 
+    check("Jump Taken (PC->5)", 0, expected_pc=5)
+
+# --- RUN ---
+hard_reset()
+test_arithmetic()
+test_logic()
+test_shifts()
+test_memory()
+test_jump()
+print("\n=== All Tests Completed ===")