TARA CPU on the Basys 3

1. Running TARA on Basys 3

The Basys 3 is small enough for a student lab bench, inexpensive compared with larger FPGA development boards, and still has exactly the I/O TARA needs to feel like a real computer rather than a hidden simulation: slide switches for mode control, pushbuttons for stepping and input, LEDs for fast visual feedback, a four-digit seven-segment display for register inspection, VGA for graphics, a USB keyboard port for games, and a USB-UART link back to the computer.

That combination makes the board a useful bridge between simulation and physical hardware. You can load a program with TARA Studio, run the same machine code on the FPGA without resynthesizing the hardware, pause the live CPU, read registers directly on the board, inspect memory from TARA Studio, and watch pixels appear on a VGA monitor. The important habit is to treat the board and the monitor as two views of the same machine.

2. Board Orientation

Use the labeled board photo as your first map. The numbered callouts are the standard Digilent Basys 3 references, but the table below translates them into TARA CPU roles. Once those roles are familiar, most lab work becomes a loop of setting switches, pressing a button, reading the LEDs or seven-segment display, and deciding what to inspect next.

4. Runtime Controls

The slide switches, buttons, seven-segment display, and LEDs are wired as a compact hardware debugger. These are live FPGA signals, so they keep working even when TARA Studio is not connected. In single-step mode, the board becomes especially useful because each press advances the machine by one micro-state and the LEDs show which part of the fetch/decode/execute sequence you are looking at.

Switches

Buttons

Seven-segment display

The four digits show one 16-bit value in hexadecimal. Set sw[15:14] first, then use sw[13:11] if you selected a register.

LED dashboard

5. TARA Studio FPGA Tool

The TARA FPGA Tool is organized around how often a control is needed. One-time hardware work lives under Board Setup, target selection lives under Connect Memory, and the main workspace stays focused on reading, changing, and visualizing memory. The program row remains at the bottom because choosing and running .tara files is a normal part of every session.

Connect to FPGA memory

1. Confirm the DONE LED is on. If it is off, return to Board Setup in section 3.
2. Choose Connect Memory from the top menu.
3. Select FPGA USB and press Rescan.
4. Choose the Basys 3 UART serial endpoint, then press Connect.
5. Wait for a green connected: message. You may close the dialog; the connection remains active.

When two Digilent ports appear

The Basys 3 USB interface exposes separate JTAG and UART channels. TARA Studio ranks the likely UART channel first and remembers the last port that answered successfully. On the board used for this manual, macOS presented names ending in ...950 and ...951; ...951 was the UART.

Do not memorize that exact name. If Connect reports no response, try the other Digilent endpoint after confirming that DONE is on and the TARA bitstream is current.

Connect to simulator memory

Choose Connect Memory → Simulator Memory → Connect when you want the same memory workflow without hardware. Serial-port controls are disabled because no USB port is used. Switching targets disconnects the old target first, which prevents an edit intended for the simulator from reaching the FPGA or vice versa.

Load and run a TARA program

1. Connect the desired memory target.
2. At the bottom of the main window, press Browse and choose a .tara source file.
3. For deliberate hardware single-stepping, set SW0=0 before loading.
4. Press Load & Run. TARA Studio assembles the source, holds the target while writing its instruction words at 0x000, and then releases it.
5. On hardware, set SW0=1 for continuous execution or leave it at 0 and use BTNU to advance micro-states.

Read and understand memory

Address patterns worth knowing

• 0x000: first instruction and normal load address.
• 0x000–0x5FE: ordinary program, data, and stack space.
• 0x5FF: live button/keyboard/quit input byte.
• 0x600–0x7FF: 512-byte framebuffer consumed by VGA.

The UART protocol transfers 16-bit words in big-endian byte order. For example, word 0x1A00 appears as bytes 1A 00 in adjacent grid cells.

Write and poke memory safely

1. Pause a physical TARA CPU with SW0=0 before changing memory that its program may also write.
2. To change one byte, double-click its grid cell, enter a two-digit hexadecimal value, and accept.
3. To initialize a region, use Fill, Bytes, and the 16-bit value beside the equals sign, then press Write.
4. Select random when testing display or memory patterns instead of repeating one word.
5. Read the range again and confirm the intended bytes changed.

Inspect the framebuffer comfortably

Set Start to 0x600, Bytes to 512, enable Heatmap, and enter full screen. Each row contains sixteen consecutive bytes, so the entire framebuffer is 32 memory rows. Full-screen mode stretches every byte cell horizontally to prevent values from overlapping on a wide display.

Watch the complete array workflow

This 48-second recording uses a physical Basys 3. It programs and verifies tara_top.bit in SPI flash, connects the FPGA USB memory UART, reads 256 bytes at 0x400, enlarges the grid with A+ four times, writes random bytes, runs Bubble Sort in full screen, then runs Reverse Array on the same hardware memory.

6. Fibonacci Walkthrough

This example computes F(10)=55 and leaves the answer in R6=0x0037. It is a good runtime-debugging program because it uses immediate loads, arithmetic, a branch, a jump, a loop counter, and HLT.

; Iterative Fibonacci: F(10) = 55
; R2 = a, R3 = b, R4 = a+b, R5 = counter, R6 = result

        LIL  R2, 0
        LIL  R3, 1
        LIL  R5, 10

loop:   BZ   R5, done
        ADD  R4, R2, R3
        MOV  R2, R3
        MOV  R3, R4
        ADDI R5, -1
        JMP  loop

done:   MOV  R6, R2
        HLT

Load it

1. Open TARA Studio, select the TARA FPGA Tool, and connect to the board as described in Section 5.
2. Use Browse to select python-sim/tara_simulator_fpga/src/examples/progs/Basic/fibonacci.tara, or paste the program above into your own .tara file.
3. Set sw[0]=0 before clicking Load & Run. TARA Studio releases the CPU, but with run disabled the CPU will wait for button-driven steps.
4. Set sw[15:14]=00 to watch PC first.

Expected assembled words

Single-step from reset

1. Press btnC. Wait for the splash to finish. Keep sw[0]=0.
2. Set sw[15:14]=00. The seven-segment display should start at or near 0000.
3. Press btnU repeatedly. Watch led[7:5] move through T-states.
4. After the first instruction completes, PC has advanced to 0002. Since LIL R2,0 writes zero, the register value may not visibly change.
5. Set sw[15:14]=10 and sw[13:11]=011 to view R3. Step until the second instruction completes; the display should read 0001.
6. Set sw[13:11]=101 to view R5. Step until the third instruction completes; the display should read 000A.
7. Leave the board in single-step mode and continue stepping through the loop. R5 counts down, while R2 and R3 walk through Fibonacci values.
8. When R5=0000, the next BZ branches to 0x012. Switch the seven-segment display to PC if you want to see that branch land.
9. Select R6 with sw[13:11]=110. After MOV R6,R2, the display reads 0037.
10. After the final HLT, led[15] turns on. The CPU is halted until reset.

Run, pause, inspect, resume

1. Reset with btnC, then set sw[0]=1 and sw[1]=0 for slow auto-run.
2. Watch the T-state LEDs move quickly and the PC/register display update.
3. Flip sw[0]=0 to pause into single-step mode.
4. Use sw[15:14] and sw[13:11] to inspect PC, IR, R2, R3, R5, and R6.
5. Press btnU for one micro-state at a time, or flip sw[0]=1 to resume auto-run.

Final expected state

8. Troubleshooting

Most failures fall into one of three categories: the board was not configured with the expected bitstream, the CPU is being held or paused, or TARA Studio is connected to the wrong serial device. Work from the outside in: confirm power and programming first, then check switches and LEDs, then check the TARA Studio connection.

Running and connecting

Programming the bitstream

9. Quick Reference

Keep this section nearby once the basic workflow is familiar. It collects the memory map and the board pins that matter to the top-level module.

Configuration, boot, and reset

Memory map

Basys 3 pins used by top-level ports

Appendix A. Source Code Guide

This appendix is the merged source-code guide. Read it when you want to move from operating the board to understanding how the Verilog and simulation model fit together. The main manual explains what the running system does; this appendix explains where that behavior lives in the repository and how to rebuild it with confidence.

A.1 Repository at a glance

The verilog/CPU tree is deliberately split by responsibility. The hardware directory contains everything that becomes logic on the FPGA. The tools directory contains support utilities used by the build and verification flow. User-facing program loading and live memory inspection are handled through TARA Studio, so the hardware source tour stays focused on the synthesizable design and the build resources that support it.

A.2 How to study the source

Read the design top-down. Begin with the board wrapper so you know which external signals exist, descend into the CPU integration file, then open the control unit and the leaf datapath blocks. Keep one organizing idea in view: TARA is microprogrammed. The behavior of each instruction is not scattered through ad hoc control logic; it is encoded in a generated control ROM that is indexed by opcode and T-state.

1. Start with the contract. Skim REQUIREMENTS.md for the ISA, memory map, instruction formats, and 40-bit control word layout.
2. Open the board top level. hardware/rtl/board/tara_top.v connects the CPU to clocking, reset, VGA, buttons, keyboard input, UART, seven-segment display, and LEDs.
3. Read the processor shell. hardware/rtl/cpu/tara_cpu.v shows how the register file, PC, IR, MAR, MDR, ALU, memory, and control unit exchange data.
4. Follow the control path. hardware/rtl/control/ contains the T-state ring counter, ROM lookup, and decoded control signals that steer the datapath.
5. Compare RTL with the control-store support files. The micro-operations for each instruction are kept in the build support area.
6. Finish with the leaves. The reusable pieces in rtl/core/, rtl/alu/, and rtl/mem/ are small enough to read after the system shape is clear.

A.3 Module hierarchy

The tree below is the useful mental map for reading the Verilog. It is not just a file list; it shows where board-level concerns stop and where the processor proper begins.

A.4 Build and data flow

A TARA bitstream is not produced from Verilog alone. Before Vivado builds the design, the support tooling prepares the memory images that the hardware expects for control and boot-time initialization. Vivado then combines those files with the RTL and constraints to produce build/tara_top.bit. After the board is configured, TARA Studio can replace the program in live memory over USB without changing the FPGA configuration.

A.5 Building the bitstream

Prerequisites

One-command flow

Call Vivado from the CPU/ root after the repository has been prepared. With the board attached, the default flow builds and programs; with noprogram, it only writes the bitstream and reports.

vivado -mode batch -source hardware/build.tcl
vivado -mode batch -source hardware/build.tcl -tclargs noprogram

build.tcl reads hardware/rtl/**/*.v and hardware/constraints/tara_basys3.xdc, supplies the required memory initialization resources, and writes outputs under build/. If you use the Vivado GUI instead, create a project for xc7a35tcpg236-1, set tara_top as the top module, and add the XDC file.

A.6 Simulation and verification

The design is checked at two levels. The Python co-simulation compares the microcoded hardware model against the reference simulator, while the RTL benches exercise the actual Verilog blocks where Icarus Verilog is available.

Cycle-accurate co-simulation

python3 tools/model/verify.py

This command lock-steps tools/model/tara_pymodel.py against the golden simulator in ../python-sim. Both decode the same instruction behavior, and the hardware model reads the same prepared control words used by the RTL, so mismatches expose real drift in the microcode or datapath assumptions.

RTL testbenches

cd hardware/sim
make
make cpu
make clean

Use the simulation Makefile for local HDL-level confidence before opening Vivado or when changing shared datapath modules.

A.7 Maintenance notes