\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}