% Manual that describes how to create/edit/configure the .cpu and .set files 
% used by the simulator (en).

\documentclass[11pt,a4paper,twoside,titlepage]{report}

\usepackage[utf8x]{inputenc}
\usepackage[english]{babel}
\usepackage[T1]{fontenc}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{color}
\usepackage{siunitx}

\newcommand{\Author}{Bruno Nova}
\newcommand{\Title}{DrMIPS -- Configuration Manual}

\author{Bruno Nova}
\title{\Title}
\hypersetup{pdfauthor={Bruno Nova},pdftitle={\Title}}
\definecolor{cloudwhite}{cmyk}{0,0,0,0.025}
\graphicspath{{figures/}}

\lstset{
	extendedchars=\true,
	inputencoding=utf8x,
	literate={ç}{{\c{c}}}1,
	basicstyle=\footnotesize\ttfamily,
	keywordstyle=\bfseries,
	numbers=left,
	numberstyle=\scriptsize\texttt,
	stepnumber=1,
	numbersep=8pt,
	frame=tblr,
	float=htb,
	aboveskip=8mm,
	belowskip=4mm,
	backgroundcolor=\color{cloudwhite},
	showspaces=false,
	showstringspaces=false,
	showtabs=false,
	tabsize=2,	
	captionpos=b,
	breaklines=true,
	breakatwhitespace=false,
	escapeinside={\%*}{*)},
	morekeywords={*,var,template,new}
}



\begin{document}

\maketitle
\tableofcontents


\chapter{Introduction}

DrMIPS provides several unicycle and pipeline MIPS datapaths.
These datapaths are defined in JSON (\url{http://json.org/}) files, and
have the \verb+.cpu+ extension.
These CPU files can be modified, and new ones can be created.

The instruction sets used by the datapaths are also defined in JSON files,
having the \verb+.set+ extension.
These can also be created and modified.

This manual explains, with some detail, the syntax of both of these files.
Chapter~\ref{ch:cpu} explains the syntax of the CPU files while
Chapter~\ref{ch:set} explains the syntax of the instruction set files.


\chapter{CPU file} \label{ch:cpu}

The different versions of the MIPS CPU are defined in CPU files.
These can be edited/configured and additional ones can be created.
This chapter explains the syntax of these files.

The CPU files are formatted in JSON.
A partial example of a CPU file is shown below:

\lstinputlisting{listings/cpu.cpu}

The various sections that compose the CPU files are detailed in the
following sections of this chapter.


\section{components}

This section defines all the components of the CPU and their properties.
An example of the definition of a component is shown below:

\lstinputlisting{listings/component.txt}

Each component is identified by a unique ID (\verb+MUX_DST+ in this example).
The properties of the component are defined between curly braces as a JSON
object. Many properties are specific to each type of component, but some exist
for all components. These are:

\begin{itemize}
	\item \textbf{type}: The type of the component. The component of the example
		is a multiplexer. The different types of components are explained next.
	\item \textbf{latency}: Optional. An integer with the latency of the component
		in \SI{}{\pico\second}. The default latency is \SI{0}{\pico\second}.
	\item \textbf{x}: The x-coordinate of the top-left corner of the component in 
		the graphical datapath. The minimum value is 0 and corresponds to the left
		border of the datapath. There is no maximum value.
	\item \textbf{y}: The y-coordinate of the top-left corner of the component in 
		the graphical datapath. The minimum value is 0 and corresponds to the top
		border of the datapath. There is no maximum value.
	\item \textbf{desc}: Optional. Component specific description, in each language, 
		shown in the tooltip of the component.
		The value is a JSON object where the description for each language is defined
		in the form \verb+"language_code": "Description."+. The \verb+language_code+
		identifier is the code of the language, like \verb+pt+ or \verb+pt_BR+.
		The special language code \verb+default+ should define the default description
		in English that is used when the language-specific description is not available.
\end{itemize}

The following subsections explain the different types of components available
and their specific properties. 
The titles of the subsections are the values that should be written in the
\verb+type+ property of the components. This property is case-insensitive.

\subsection{Add}

An adder that sums the values of the inputs. The specific properties are:
\begin{itemize}
	\item \textbf{in1}: Identifier of the first input.
	\item \textbf{in2}: Identifier of the second input.
	\item \textbf{out}: Identifier of the output.
\end{itemize}

\subsection{ALU}

The basic ALU. Only one ALU or Extended ALU can be present. The specific properties are:
\begin{itemize}
	\item \textbf{in1}: Identifier of the first input.
	\item \textbf{in2}: Identifier of the second input.
	\item \textbf{control}: Identifier of the control input (that selects the operation
		to perform).
	\item \textbf{out}: Identifier of the result output.
	\item \textbf{zero}: Identifier of the 1 bit \emph{zero} output.
\end{itemize}

\subsection{ALU\_Control}

The component that controls the ALU. Only one can be present.
The specific properties are:
\begin{itemize}
	\item \textbf{aluop}: Identifier of the \emph{ALUOp} input.
	\item \textbf{func}: Identifier of the \emph{func} input (from the function field
		of the instruction).
\end{itemize}

\subsection{And}

A logical \emph{AND} port. The specific properties are:
\begin{itemize}
	\item \textbf{in1}: Identifier of the first input.
	\item \textbf{in2}: Identifier of the second input.
	\item \textbf{out}: Identifier of the output.
\end{itemize}

\subsection{Concat}

A ``concatenator'' that concatenates the values of the two inputs into a single output.
The value of the output is the concatenation of the value of the first input (as higher
order bits) with the value of the second input (as lower order bits).
The size of the output is equal to the sum of the sizes of the inputs.
The specific properties are:
\begin{itemize}
	\item \textbf{in1}: Properties of the first input.
	\item \textbf{in2}: Properties of the second input.
	\item \textbf{out}: Identifier of the output.
\end{itemize}

The properties of both inputs are defined as JSON objects. The properties of these
objects are:
\begin{itemize}
	\item \textbf{id}: Identifier of the input.
	\item \textbf{size}: Size of the input (in bits).
\end{itemize}

\subsection{Const}

A component that outputs a constant value. The specific properties are:
\begin{itemize}
	\item \textbf{out}: Identifier of the output.
	\item \textbf{val}: The constant value.
	\item \textbf{size}: Size of the output (in bits).
\end{itemize}

\subsection{Control}

The control unit. The datapath must have one control unit.
This component has only one specific property: \textbf{in}, which is
the identifier of the input.

\subsection{Dist}

This component distributes the bits of the input through several outputs.
The specific properties are:
\begin{itemize}
	\item \textbf{in}: Properties of the input as a JSON object.
		The properties of the object are:
		\begin{itemize}
			\item \textbf{id}: Identifier of the input.
			\item \textbf{size}: Size of the input (in bits).
		\end{itemize}
	\item \textbf{out}: Properties of the outputs as a JSON array.
		Each element of the array defines the properties of an output as a
		JSON object. The properties of the objects of the array are:
		\begin{itemize}
			\item \textbf{msb}: The index of the most significant bit from the input.
			\item \textbf{lsb}: The index of the less significant bit from the input.
			\item \textbf{id}: Optional. Identifier of the output. If omitted,
				the identifier corresponds to ``\verb+<msb>-<lsb>+''.
		\end{itemize}
\end{itemize}

\subsection{DMem}

The data memory. Only one can be present. The specific properties are:
\begin{itemize}
	\item \textbf{size}: Size of the memory (number of 32 bits memory positions).
	\item \textbf{address}: Identifier of the \emph{Address} input.
	\item \textbf{write\_data}: Identifier of the \emph{WriteData} input.
	\item \textbf{out}: Identifier of the output.
	\item \textbf{mem\_read}: Identifier of the \emph{MemRead} control input.
	\item \textbf{mem\_write}: Identifier of the \emph{MemWrite} control input.
\end{itemize}

\subsection{Ext\_ALU}

An extended ALU. This ALU stores the \verb+hi+ and \verb+lo+ registers and is
capable of calculating multiplications and divisions.
Only one ALU or Extended ALU can be present. The specific properties are the same
as the basic ALU:
\begin{itemize}
	\item \textbf{in1}: Identifier of the first input.
	\item \textbf{in2}: Identifier of the second input.
	\item \textbf{control}: Identifier of the control input (that selects the operation
		to perform).
	\item \textbf{out}: Identifier of the result output.
	\item \textbf{zero}: Identifier of the 1 bit \emph{zero} output.
\end{itemize}

\subsection{Fork}

This component forks a wire into several other wires with the same size.
The specific properties are:
\begin{itemize}
	\item \textbf{in}: Identifier of the input.
	\item \textbf{size}: Size of the input and outputs (in bits).
	\item \textbf{out}: Array with the identifiers of the outputs.
\end{itemize}

\subsection{Fwd\_Unit}

The pipeline forwarding unit. Only one can be present.
The specific properties are:
\begin{itemize}
	\item \textbf{ex\_mem\_reg\_write}: Identifier of the \emph{EX/MEM.RegWrite} input.
	\item \textbf{mem\_wb\_reg\_write}: Identifier of the \emph{MEM/WB.RegWrite} input.
	\item \textbf{ex\_mem\_rd}: Identifier of the \emph{EX/MEM.Rd} input.
	\item \textbf{mem\_wb\_rd}: Identifier of the \emph{MEM/WB.Rd} input.
	\item \textbf{id\_ex\_rs}: Identifier of the \emph{ID/EX.Rs} input.
	\item \textbf{id\_ex\_rt}: Identifier of the \emph{ID/EX.Rt} input.
	\item \textbf{fwd\_a}: Identifier of the \emph{ForwardA} output.
	\item \textbf{fwd\_b}: Identifier of the \emph{ForwardB} output.
\end{itemize}

\subsection{Hzd\_Unit}

The pipeline hazard detection unit. Only one can be present.
The specific properties are:
\begin{itemize}
	\item \textbf{id\_ex\_mem\_read}: Identifier of the \emph{ID/EX.MemRead} input.
	\item \textbf{id\_ex\_rt}: Identifier of the \emph{ID/EX.Rt} input.
	\item \textbf{if\_id\_rs}: Identifier of the \emph{IF/ID.Rs} input.
	\item \textbf{if\_id\_rt}: Identifier of the \emph{IF/ID.Rt} input.
	\item \textbf{stall}: Identifier of the output.
\end{itemize}

\subsection{IMem}

The instruction memory. The datapath must have one instruction memory.
The specific properties are:
\begin{itemize}
	\item \textbf{in}: Identifier of the input.
	\item \textbf{out}: Identifier of the output.
\end{itemize}

\subsection{Mux}

A multiplexer. The specific properties are:
\begin{itemize}
	\item \textbf{size}: The size of the inputs and output (in bits).
	\item \textbf{sel}: Identifier of the selector input.
	\item \textbf{out}: Identifier of the output.
	\item \textbf{in}: Array with the identifiers of the inputs.
\end{itemize}

\subsection{Not}

A logical \emph{NOT} port. The specific properties are:
\begin{itemize}
	\item \textbf{in}: Identifier of the input.
	\item \textbf{out}: Identifier of the output.
\end{itemize}

\subsection{Or}

A logical \emph{OR} port. The specific properties are:
\begin{itemize}
	\item \textbf{in1}: Identifier of the first input.
	\item \textbf{in2}: Identifier of the second input.
	\item \textbf{out}: Identifier of the output.
\end{itemize}

\subsection{PipeReg}

A pipeline register that separates two stages of the pipeline.
A pipelined datapath must have exactly 4 of these registers (corresponding to a
5-stage pipeline). Additionally, the identifiers of these components must be:
\verb+IF/ID+, \verb+ID/EX+, \verb+EX/MEM+ and \verb+MEM/WB+.
The specific properties are:
\begin{itemize}
	\item \textbf{regs}: Definition of the registers recorded. The value is a
		JSON object where each property defines a register: the identifier is
		the identifier of the register and corresponding input and output, and
		the value is the size of the register (in bits).
	\item \textbf{flush}: Optional. Identifier of the \emph{Flush} control input.
	\item \textbf{write}: Optional. Identifier of the \emph{Write} control input.
\end{itemize}

\subsection{PC}

The program counter. The datapath must have one program counter.
The specific properties are:
\begin{itemize}
	\item \textbf{in}: Identifier of the input.
	\item \textbf{out}: Identifier of the output.
	\item \textbf{write}: Optional. Identifier of the \emph{Write} control input.
\end{itemize}

\subsection{RegBank}

The register bank. The datapath must have one register bank.
The specific properties are:
\begin{itemize}
	\item \textbf{num\_regs}: The number of registers. Must be greater than 1 and
		a power of 2.
	\item \textbf{read\_reg1}: Identifier of the \emph{ReadReg1} input.
	\item \textbf{read\_reg2}: Identifier of the \emph{ReadReg2} input.
	\item \textbf{read\_data1}: Identifier of the \emph{ReadData1} output.
	\item \textbf{read\_data2}: Identifier of the \emph{ReadData2} output.
	\item \textbf{write\_reg}: Identifier of the \emph{WriteReg} input.
	\item \textbf{write\_data}: Identifier of the \emph{WriteData} input.
	\item \textbf{reg\_write}: Identifier of the \emph{RegWrite} control input.
	\item \textbf{forwarding}: Optional. If \verb+true+, the register bank will use 
		internal forwarding (for pipelined datapaths).
	\item \textbf{const\_regs}: Optional. JSON array that defines the constant 
		registers. Each element can be either the index of the register or a JSON 
		object with the following properties:
		\begin{itemize}
			\item \textbf{reg}: Index of the register.
			\item \textbf{val}: The constant value of the register.
		\end{itemize}
\end{itemize}

\subsection{SExt}

A sign extender. The specific properties are:
\begin{itemize}
	\item \textbf{in}: Properties of the input.
	\item \textbf{out}: Properties of the output.
\end{itemize}

The properties of both the input and output are defined as JSON objects. 
The properties of these objects are:
\begin{itemize}
	\item \textbf{id}: Identifier of the input/output.
	\item \textbf{size}: Size of the input/output (in bits).
\end{itemize}

\subsection{SLL}

A shift-left logical. The specific properties are:
\begin{itemize}
	\item \textbf{in}: Properties of the input.
	\item \textbf{out}: Properties of the output.
	\item \textbf{amount}: Number of bits to shift left.
\end{itemize}

The properties of both the input and output are defined as JSON objects. 
The properties of these objects are:
\begin{itemize}
	\item \textbf{id}: Identifier of the input/output.
	\item \textbf{size}: Size of the input/output (in bits).
\end{itemize}

\subsection{Xor}

A logical \emph{XOR} port. The specific properties are:
\begin{itemize}
	\item \textbf{in1}: Identifier of the first input.
	\item \textbf{in2}: Identifier of the second input.
	\item \textbf{out}: Identifier of the output.
\end{itemize}

\subsection{ZExt}

A zero extender. The specific properties are:
\begin{itemize}
	\item \textbf{in}: Properties of the input.
	\item \textbf{out}: Properties of the output.
\end{itemize}

The properties of both the input and output are defined as JSON objects. 
The properties of these objects are:
\begin{itemize}
	\item \textbf{id}: Identifier of the input/output.
	\item \textbf{size}: Size of the input/output (in bits).
\end{itemize}


\section{wires}

This section defines all the wires that connect the components of the CPU.
An example of the definition of a wire is shown below:

\lstinputlisting{listings/wire.txt}

Each wire connects an output of a component to an input of another component.
A wire is defined as a JSON object with several properties.
These are:

\begin{itemize}
	\item \textbf{from}: The ID of the component that the wire connects from (origin).
	\item \textbf{out}: The ID of output of the origin component that the wire
		connects from.
	\item \textbf{to}: The ID of the component that the wire connects to (destination).
	\item \textbf{in}: The ID of input of the destination component that the wire
		connects to.
	\item \textbf{start}: Optional. A JSON object that defines the start position of
		the wire in the graphical datapath, if the default one is unsuitable.
	\item \textbf{points}: Optional. An array of JSON objects that define the
		positions of the intermediate points of the wire, if desired.
	\item \textbf{end}: Optional. A JSON object that defines the end position of
		the wire in the graphical datapath, if the default one is unsuitable.
\end{itemize}

The positions used in the \verb+start+, \verb+points+ and \verb+end+ properties
above are JSON objects with two integer properties: \verb+x+ and \verb+y+.
Each input and output of each component is, by default, ``attached'' to one of
the four sides of the component.
The positions of the inputs and outputs in the datapath and, thus, the start and
end positions of the connected wires, are calculated automatically\footnote{The
inputs and outputs on each side of a component are, by default, ordered 
alphabetically by their IDs.} but can be overwritten by the \verb+start+ and 
\verb+end+ properties.


\section{reg\_names}

This \textbf{optional} section defines the ``friendly'' names of the registers (i.e.
\verb+$zero+, \verb+$t0+, etc.).
The value is an array of strings that defines the names of the registers, from
register \verb+$0+ to the last one, \textbf{without the leading dollar sign}.
The registers can always be referred by their indexes (\verb+$0+, \verb+$1+, etc.) 
in the simulator.


\section{instructions}

This section declares the instruction set that the CPU uses.
The value is the \textbf{relative} path to the desired instruction set file.
These files are explained in the next chapter.


\chapter{Instruction set file} \label{ch:set}

The instruction sets used by the different versions of the MIPS CPU
are defined in instruction set files.
These can be edited/configured and additional ones can be created.
This chapter explains the syntax of these files.

Like the CPU files, the instruction set files are formatted in JSON.
A partial example of an instruction set file is shown below:

\lstinputlisting{listings/set.set}

The various sections that compose the instruction set files are detailed in 
the following sections of this chapter.


\section{types}

This section defines the existing types of instructions and their fields.
All instruction are 32 bits in size.
An example of the definition of an instruction type is shown below:

\lstinputlisting{listings/type.txt}

Each instruction type is identified by its identifier (\verb+R+ in this example).
The fields of an instruction are defined in a JSON array. Each individual field is 
a JSON object and defines the field's identifier and size in bits. The first field
in this example is the \verb+op+ field with a size of 6 bits.
The first field of the instructions is considered the \emph{opcode} and must
have the same size in all types.


\section{instructions}

This section defines the available instructions and how they are encoded.
An example of the definition of an instruction is shown below:

\lstinputlisting{listings/instruction.txt}

Each instruction is identified by its unique mnemonic (\verb+add+ in this example).
An instruction is defined as a JSON object with several properties. These are:

\begin{itemize}
	\item \textbf{type}: The type of the instruction.
	\item \textbf{args}: An array with the types of each argument (may be omitted if
		the instruction has no arguments).
		The different types of arguments are:
		\begin{itemize}
			\item \textbf{reg}: A register.
			\item \textbf{int}: An integer value. Can also be a label (allowed because 
				of the \verb+la+ pseudo-instruction).
			\item \textbf{target}: A label in the code or direct instruction index for 
				a jump.
			\item \textbf{offset}: A label in the code or direct instruction offset 
				for a branch.
			\item \textbf{label}: A label in the code or data segment or direct 
				address/index.
			\item \textbf{data}: A label in the data segment or direct address plus
				an offset register for a load or store instruction (an argument like
				\verb+label($t0)+). The user may omit the offset register.
		\end{itemize}
	\item \textbf{fields}: A JSON object that defines the values of the fields
		(the fields defined in the instruction's type). The value of each field
		can either be a constant integer or come from an argument (specified as
		\verb+"#1"+, \verb+"#2"+, etc.).
		For values that come from a \verb+data+ argument it is necessary to
		specify if they come from the base address or from the offset register.
		This is done by appending \verb+.base+ or \verb+.offset+ to the reference
		to the argument (\verb+#1+, \verb+#2+, etc.).
		
		In this example: \verb+op+ has the constant value \verb+0+, \verb+rs+
		has the value from the 2nd argument, \verb+rt+ has the value from the 3rd
		argument, etc.
	\item \textbf{desc}: Optional. A string that should contain a short symbolic
		description of what the instruction does for the user to see.
\end{itemize}


\section{pseudo}

This section defines the available pseudo-instructions.
An example of the definition of a pseudo-instruction is shown below:

\lstinputlisting{listings/pseudo.txt}

Each pseudo-instruction is identified by its unique mnemonic (\verb+subi+ 
in this example). Each mnemonic can only identify either an instruction or a
pseudo-instruction, not both.
A pseudo-instruction is defined as a JSON object with several properties. 
These are:

\begin{itemize}
	\item \textbf{args}: An array with the types of each argument (may be omitted if
		the pseudo-instruction has no arguments). These types are the same ones that are
		available for instructions, explained in the previous section.
	\item \textbf{to}: An array that lists the real instructions that the
		pseudo-instruction is converted to when assembled. The values of the arguments
		specified by the user can be referenced by using \verb+#1+ for the 1st argument,
		\verb+#2+ for the 2nd, and so on.
	\item \textbf{desc}: Optional. A string that should contain a short symbolic
		description of what the pseudo-instruction does for the user to see.
\end{itemize}


\section{control}

This section defines how the control unit works. More specifically, it
defines the values of the outputs (control signals) for each possible value at
the input (the \emph{opcode}).
An example of the definition of the values of the control signals for one
\emph{opcode} is shown below:

\lstinputlisting{listings/control.txt}

The values of the control signals for a specified \emph{opcode} are defined as
a JSON object. The values are in decimal format and the sizes (in bits) of the 
control signals are determined automatically.
Control signals that have the value \verb+0+ can be omitted.


\section{alu}

This section defines how the ALU and ALU control work.
A partial example of this section is shown below:

\lstinputlisting{listings/alu.txt}

The \verb+aluop_size+, \verb+func_size+ and \verb+control_size+ properties
define the sizes (in bits) of the \verb+ALUOp+ and \verb+func+ inputs of the
ALU control and of the control input of the ALU, respectively.

The \verb+control+ subsection defines how the ALU control works (in a JSON array).
Each element in the array defines (as a JSON object) the values of the outputs
for the specified values of the inputs.
The \verb+aluop+ and \verb+func+ properties correspond to the values of the
inputs for the correspondence. If the value of the \verb+func+ input is not relevant
for the correspondence (\emph{don't care}, can be any value), the property 
should be omitted.
The \verb+out+ property defines the values of the outputs for the correspondence.
The values are specified as a JSON object and the sizes (in bits) of the outputs
are determined automatically.
All values are in decimal format.

The \verb+operations+ subsection defines (as a JSON object) the correspondence 
between the values of the control input of the ALU and the arithmetic operation 
it performs.
The available operations are: \textbf{add}, \textbf{sub}, \textbf{and}, \textbf{or},
\textbf{slt}, \textbf{xor}, \textbf{sll}, \textbf{srl}, \textbf{sra}, \textbf{nor},
\textbf{mult}, \textbf{div}, \textbf{mfhi}, \textbf{mflo}.
Note that the last four operations require an ``extended'' ALU in the CPU, instead 
of a ``normal'' ALU.


\end{document}
