doc/main.tex

@@ -0,0 +1,248 @@
+\documentclass[a4paper,12pt]{article}
+\usepackage[utf8]{inputenc}
+\usepackage{amsmath}
+\usepackage{hyperref}
+
+\title{Documentation of 1-Bit Full Adder in Verilog}
+\author{Class 1i}
+\date{}
+
+\begin{document}
+
+\maketitle
+
+\tableofcontents
+\newpage
+
+\section{Introduction}
+This document provides a detailed description of the 1-bit full adder module implemented in Verilog. A full adder is a digital circuit that performs the addition of binary numbers. In this design, the module takes three inputs: two single-bit binary values, \texttt{a} and \texttt{b}, and a carry-in bit, \texttt{carry\_in}. It produces two outputs: the sum (\texttt{sum}) and a carry-out bit (\texttt{carry\_out}).
+
+\section*{Installing Yosys and nextpnr from Source}
+
+Yosys and nextpnr are open-source tools for digital synthesis and place-and-route. The following steps guide you through building and installing these tools from source.
+
+\subsection*{Yosys Installation}
+
+\begin{enumerate}
+    \item \textbf{Clone the Yosys repository:} Begin by cloning the Yosys repository from GitHub.
+    \begin{verbatim}
+    git clone https://github.com/YosysHQ/yosys.git
+    \end{verbatim}
+
+    \item \textbf{Install dependencies:} Ensure all necessary dependencies are installed by running:
+    \begin{verbatim}
+    sudo apt-get install build-essential clang lld bison flex \
+    libreadline-dev gawk tcl-dev libffi-dev git \
+    graphviz xdot pkg-config python3 libboost-system-dev \
+    libboost-python-dev libboost-filesystem-dev zlib1g-dev
+    \end{verbatim}
+
+    \item \textbf{Configure Yosys to use Clang:} In the Yosys directory, configure it to use the Clang compiler.
+    \begin{verbatim}
+    make config-clang
+    \end{verbatim}
+
+    \item \textbf{Initialize submodules:} Ensure all Git submodules are up to date.
+    \begin{verbatim}
+    git submodule update --init
+    \end{verbatim}
+
+    \item \textbf{Build Yosys:} Compile Yosys using multiple threads.
+    \begin{verbatim}
+    make -j32
+    \end{verbatim}
+
+    \item \textbf{Install Yosys:} After the build is complete, install Yosys system-wide.
+    \begin{verbatim}
+    sudo make install
+    \end{verbatim}
+\end{enumerate}
+
+\subsection*{icestorm Installation}
+
+\begin{enumerate}
+    \item \textbf{Clone the icestorm repository:} Download the icestorm repository from GitHub.
+    \begin{verbatim}
+    git clone https://github.com/YosysHQ/icestorm
+    \end{verbatim}
+
+    \item \textbf{Build icestorm:} Navigate to the icestorm directory and compile the project using all available processor cores.
+    \begin{verbatim}
+    cd icestorm/
+    make -j$(nproc)
+    \end{verbatim}
+
+    \item \textbf{Install icestorm:} After the build is complete, install icestorm system-wide.
+    \begin{verbatim}
+    sudo make install
+    \end{verbatim}
+\end{enumerate}
+
+\subsection*{nextpnr Installation}
+
+\begin{enumerate}
+    \item \textbf{Navigate back to the parent directory:}
+    \begin{verbatim}
+    cd ../
+    \end{verbatim}
+
+    \item \textbf{Clone the nextpnr repository:} Download the nextpnr repository from GitHub.
+    \begin{verbatim}
+    git clone https://github.com/YosysHQ/nextpnr
+    \end{verbatim}
+
+    \item \textbf{Install dependencies:} Install additional libraries needed for nextpnr.
+    \begin{verbatim}
+    sudo apt install cmake libeigen3-dev libftdi-dev
+    \end{verbatim}
+
+    \item \textbf{Configure nextpnr for the iCE40 architecture:} In the nextpnr directory, run cmake with the iCE40 architecture option. This will also integrate Icestorm.
+    \begin{verbatim}
+    cd nextpnr/
+    cmake . -DARCH=ice40
+    \end{verbatim}
+
+    \item \textbf{Build nextpnr:} Compile nextpnr using all available processor cores.
+    \begin{verbatim}
+    make -j$(nproc)
+    \end{verbatim}
+
+    \item \textbf{Install nextpnr:} Once the build completes, install nextpnr system-wide.
+    \begin{verbatim}
+    sudo make install
+    \end{verbatim}
+\end{enumerate}
+
+\subsection*{Verification}
+
+After installing Yosys and nextpnr, verify the installation by running:
+\begin{verbatim}
+yosys -V
+nextpnr-ice40 --help
+\end{verbatim}
+These commands should display version or help information, confirming that the tools are correctly installed.
+
+
+\section{Module Description}
+The 1-bit full adder module is defined in Verilog using the following interface:
+
+\begin{verbatim}
+module full_adder (
+    input wire a,         // Input A
+    input wire b,         // Input B
+    input wire carry_in,  // Carry-in
+    output wire sum,      // Sum output
+    output wire carry_out // Carry-out
+);
+\end{verbatim}
+
+\subsection{Inputs and Outputs}
+\begin{itemize}
+    \item \textbf{Input a}: The first binary input (single bit).
+    \item \textbf{Input b}: The second binary input (single bit).
+    \item \textbf{Input carry\_in}: The carry-in bit, representing any carry from the previous addition stage.
+    \item \textbf{Output sum}: The sum result of inputs \texttt{a}, \texttt{b}, and \texttt{carry\_in}.
+    \item \textbf{Output carry\_out}: The carry-out result, which is passed to the next stage if multiple bits are added.
+\end{itemize}
+
+\section{Operation}
+The 1-bit full adder performs binary addition using the logic operations XOR, AND, and OR. The outputs are calculated as follows:
+
+\begin{align*}
+\text{sum} &= a \oplus b \oplus \text{carry\_in} \\
+\text{carry\_out} &= (a \land b) \lor (\text{carry\_in} \land (a \oplus b))
+\end{align*}
+
+\subsection{Truth Table}
+The truth table for the 1-bit full adder is shown below:
+
+\begin{center}
+\begin{tabular}{|c|c|c|c|c|}
+\hline
+\textbf{a} & \textbf{b} & \textbf{carry\_in} & \textbf{sum} & \textbf{carry\_out} \\
+\hline
+0 & 0 & 0 & 0 & 0 \\
+0 & 0 & 1 & 1 & 0 \\
+0 & 1 & 0 & 1 & 0 \\
+0 & 1 & 1 & 0 & 1 \\
+1 & 0 & 0 & 1 & 0 \\
+1 & 0 & 1 & 0 & 1 \\
+1 & 1 & 0 & 0 & 1 \\
+1 & 1 & 1 & 1 & 1 \\
+\hline
+\end{tabular}
+\end{center}
+
+\section{Implementation}
+The Verilog implementation of the full adder uses logical operations to compute the sum and carry-out as shown below:
+
+\begin{verbatim}
+module full_adder (
+    input wire a,
+    input wire b,
+    input wire carry_in,
+    output wire sum,
+    output wire carry_out
+);
+    assign sum = a ^ b ^ carry_in;
+    assign carry_out = (a & b) | (carry_in & (a ^ b));
+endmodule
+\end{verbatim}
+
+\section{Parameterization}
+To make this module more versatile, we can parameterize it to allow the user to define different bit widths. Here is an example of a parameterized full adder that allows for a multi-bit input:
+
+\begin{verbatim}
+module full_adder #(
+    parameter WIDTH = 1
+) (
+    input wire [WIDTH-1:0] a,
+    input wire [WIDTH-1:0] b,
+    input wire carry_in,
+    output wire [WIDTH-1:0] sum,
+    output wire carry_out
+);
+    assign {carry_out, sum} = a + b + carry_in;
+endmodule
+\end{verbatim}
+
+In this parameterized version, \texttt{WIDTH} is a parameter that specifies the number of bits. The module can handle inputs of any width by changing the \texttt{WIDTH} value when instantiating the module.
+
+\section{Compilation and Synthesis Instructions}
+To compile and synthesize the Verilog code for the iCEBreaker FPGA, follow these steps:
+
+\begin{enumerate}
+    \item **Save the Verilog file**: Save the Verilog code as \texttt{sum.v} and the pin configuration as \texttt{sum.pcf}.
+    \item **Synthesize with Yosys**:
+    \begin{verbatim}
+    yosys -p "synth_ice40 -top full_adder -json sum.json" sum.v
+    \end{verbatim}
+    This command synthesizes the Verilog code for the iCE40 FPGA architecture and outputs a JSON netlist.
+    
+    \item **Place and route with nextpnr**:
+    \begin{verbatim}
+    nextpnr-ice40 --up5k --package sg48 --pcf sum.pcf --json sum.json --asc sum.asc
+    \end{verbatim}
+    This command places and routes the design for the UP5K model of the iCE40 FPGA.
+
+    \item **Generate a binary file with icepack**:
+    \begin{verbatim}
+    icepack sum.asc sum.bin
+    \end{verbatim}
+    This converts the ASCII file (\texttt{.asc}) to a binary file (\texttt{.bin}) for programming the FPGA.
+
+    \item **Program the FPGA with iceprog**:
+    \begin{verbatim}
+    iceprog sum.bin
+    \end{verbatim}
+    This command uploads the binary file to the iCEBreaker FPGA board.
+\end{enumerate}
+
+\section{Testing}
+To verify the correctness of the full adder, the module can be tested with all combinations of inputs (as shown in the truth table) to ensure that the sum and carry-out values are produced correctly. A testbench in Verilog can be created to apply these inputs and observe the outputs.
+
+\section{Conclusion}
+This document provides a detailed overview of the 1-bit full adder module implemented in Verilog, including its interface, operation, and logic. This module is fundamental in digital systems, especially for implementing multi-bit adders and arithmetic operations in larger circuits.
+
+\end{document}
+

sum.pcf

@@ -0,0 +1,10 @@
+set_io a 12         # Przycisk A (Button 3)
+set_io b 11         # Przycisk B (Button 2)
+set_io carry_in 10  # Przycisk Carry-in (Button 1)
+
+set_io sum 39       # Wyjście suma na diodzie L1
+set_io carry_out 40 # Wyjście carry-out na diodzie L2
+set_io l3 41        # Dioda L3 dla wejścia B
+set_io l4 42        # Dioda L4 dla carry_in
+set_io l5 37        # Dioda L5 dla wejścia A
+

sum.v

@@ -0,0 +1,19 @@
+module full_adder (
+    input wire a,         // Wejście A (przycisk)
+    input wire b,         // Wejście B (przycisk)
+    input wire carry_in,  // Wejście przeniesienia (przycisk)
+    output wire sum,      // Wyjście suma (dioda)
+    output wire carry_out, // Wyjście przeniesienia (dioda)
+    output wire l3,        // L3 dla B
+    output wire l4,        // L4 dla carry_in
+    output wire l5         // L5 dla A
+);
+
+    assign sum = a ^ b ^ carry_in;             // Obliczenie sumy
+    assign carry_out = (a & b) | (carry_in & (a ^ b)); // Obliczenie przeniesienia
+    assign l5 = a;                             // L5 pokazuje stan A
+    assign l3 = b;                             // L3 pokazuje stan B
+    assign l4 = carry_in;                      // L4 pokazuje stan carry_in
+
+endmodule
+