documentation

doc/docker.md

@@ -86,12 +86,6 @@ Plug in your FPGA into the USB slot. Then run
 Install py3tftp (`pip3 install --user py3tftp`). Then run `make tftp` to
 launch the TFTP server. Keep this terminal open.
 
-## Launch FPGA Shell
-
-Run `litex_term /dev/ttyUSB1`. You should get messages in the window with
-the TFTP server that the FPGA has connected to the server. Eventually you
-will get a login prompt: you have sucessfully loaded Upsilon onto your FPGA.
-
 ## SSH Access
 
 Add the following to your SSH config:
@@ -105,3 +99,14 @@ Add the following to your SSH config:
 
 When the FPGA is connected you can access it with `ssh upsilon` (password
 `upsilon`).
+
+Wait about a minute for Linux to boot.
+
+## Launch FPGA Shell (Optional)
+
+If you cannot access the FPGA through SSH, you can launch a shell through
+UART.
+
+Run `litex_term /dev/ttyUSB1`. You should get messages in the window with
+the TFTP server that the FPGA has connected to the server. Eventually you
+will get a login prompt: you have sucessfully loaded Upsilon onto your FPGA.

doc/user_manual.md

@@ -0,0 +1,27 @@
+Copyright 2023 (C) Peter McGoron.
+
+This file is a part of Upsilon, a free and open source software project.
+For license terms, refer to the files in `doc/copying` in the Upsilon 
+source distribution.
+
+__________________________________________________________________________
+
+The User Manual is targeted towards non-programmers using Upsilon.
+
+# Preqreuisites
+
+You will need to know the basics of Git. Git is the system used to track
+changes and update Upsilon. you will need to know the wwhat a git repository is,
+how to pull changes from a repository, what commit hashes are and how to make
+branches.
+
+You must know basic Linux shell (change directories, edit files with `vi`)
+and basic SSH usage (sftp, ssh).
+
+Knowledge of Micropython (a subset of Python) is required for scripting.
+
+
+# Building and Booting
+
+Follow `docs/docker.md` to setup the build environment, build Upsilon, and
+boot Upsilon.

doc/verilog_manual.md

@@ -6,7 +6,7 @@ source distribution.
 
 __________________________________________________________________________
 
-The Hardware Maintenance Manu is an overview of the hardware (non-software)
+The Hardware Maintenance Manual is an overview of the hardware (non-software)
 parts of Upsilon.
 
 # Crash Course in FPGAs
@@ -120,6 +120,28 @@ See also [Dan Gisselquist][1]'s rules for FPGA development.
 * Always initialize registers.
 * Rerun tests after every change to the module.
 
+## Conventions
+
+### Wires
+
+* When specfying widths, include the total bit width and subtract 1 from it,
+  even in cases where the bit width is constant. For example, to declare an
+  8-bit register, write `reg [8-1:0] r1`.
+* If a wire is active low, append `_L` to the end of the name.
+
+### Parameters
+
+* Parameters are always in all caps.
+* Parameters ending in `_WID` are bit widths that do not have an associated
+  number (eg DAC widths, input register sizes).
+* Parameters ending in `_SIZ` are the amount of bits required to store a
+  certain number. These parameters can be calculated using `floor(log2(number) + 1)`.
+  For example,
+    * `255` has a `SIZ` of 8 (8 bits are required to store 255).
+    * `256` has a `SIZ` of 9
+    * `254`, `253`, etc. have a `SIZ` of 8
+    * `127` has a `SIZ` of 7
+
 ## Design Testing Process
 
 ### Simulation

gateware/rtl/base/base.v.m4

@@ -3,19 +3,24 @@ m4_changecom(⟨/*⟩, ⟨*/⟩)
 m4_define(generate_macro, ⟨m4_define(M4_$1, $2)⟩)
 m4_include(../control_loop/control_loop_cmds.m4)
 /*
-# Copyright 2023 (C) Peter McGoron
+Copyright 2023 (C) Peter McGoron
-#
-# This file is a part of Upsilon, a free and open source software project.
-# For license terms, refer to the files in `doc/copying` in the Upsilon
-# source distribution.
-*/
 
-/* Since yosys only allows for standard Verilog (no system verilog),
+This file is a part of Upsilon, a free and open source software project.
- * arrays (which would make everything much cleaner) cannot be used.
+For license terms, refer to the files in `doc/copying` in the Upsilon
- * A preprocessor is used instead, and M4 is used because it is much
+source distribution.
- * cleaner than the Verilog preprocessor (which is bad).
+_____________________________________________________________________
- * TODO: individual RST pins
+
- */
+This is the module that collects all Verilog and exports a single interface
+that is connected to the CPU by LiteX.
+
+In this future, this module should be written into soc.py
+
+Since yosys only allows for standard Verilog (no system verilog),
+arrays (which would make everything much cleaner) cannot be used.
+A preprocessor is used instead, and M4 is used because it is much
+cleaner than the Verilog preprocessor (which is bad).
+TODO: individual RST pins
+*/
 
 /*********************************************************/
 /********************** M4 macros ************************/
@@ -208,12 +213,12 @@ module base #(
 	parameter DAC_PORTS = 1,
 m4_define(DAC_PORTS_CONTROL_LOOP, (DAC_PORTS + 1))
 
-	parameter DAC_NUM = 8,
+	parameter DAC_NUM = 8, // Number of DACs
-	parameter DAC_WID = 24,
+	parameter DAC_WID = 24, // Bit width of DAC command
-	parameter DAC_DATA_WID = 20,
+	parameter DAC_DATA_WID = 20, //  Bit with of DAC register
-	parameter DAC_WID_SIZ = 5,
+	parameter DAC_WID_SIZ = 5, // number of bits required to store DAC_DATA_WID
-	parameter DAC_POLARITY = 0,
+	parameter DAC_POLARITY = 0, // DAC SCK polarity
-	parameter DAC_PHASE = 1,
+	parameter DAC_PHASE = 1, // DAC SCK phase
 	parameter DAC_CYCLE_HALF_WAIT = 10,
 	parameter DAC_CYCLE_HALF_WAIT_SIZ = 4,
 	parameter DAC_SS_WAIT = 5,
@@ -236,14 +241,14 @@ m4_define(ADC_PORTS_CONTROL_LOOP, (ADC_PORTS + 1))
 	parameter ADC_TYPE2_WID = 16,
 	parameter ADC_TYPE3_WID = 24,
 	parameter ADC_WID_SIZ = 5,
-	parameter ADC_CYCLE_HALF_WAIT = 60,
+	parameter ADC_CYCLE_HALF_WAIT = 5,
-	parameter ADC_CYCLE_HALF_WAIT_SIZ = 7,
+	parameter ADC_CYCLE_HALF_WAIT_SIZ = 3,
 	parameter ADC_POLARITY = 1,
 	parameter ADC_PHASE = 0,
 	/* The ADC takes maximum 527 ns to capture a value.
 	 * The clock ticks at 10 ns. Change for different clocks!
 	 */
-	parameter ADC_CONV_WAIT = 53,
+	parameter ADC_CONV_WAIT = 60,
 	parameter ADC_CONV_WAIT_SIZ = 6,
 
 	parameter CL_CONSTS_WHOLE = 21,