\documentclass{article}

\title{FreeCat design document}
\author{Morgan Thomas}

\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}

\begin{document}

\maketitle

Programming languages can usually be classified as typed or untyped. Untyped languages are usually relatively simple and flexible, but less capable of automatically finding errors in programs. Typed languages are usually more capable of automatically finding errors in programs, but this usually comes at the expense of flexibility and expressive capability. Expressive capability of typed languages can be increased, but this usually comes at the expense of increasing their complexity.

FreeCat is a programming language, a system of logic and computer algebra, and an approach to type theory and the foundations of math. It aims to chart a new programming language design path, where the guiding hope is that we can have automatic error finding, language simplicity, flexibility, and expressive capability, all at the same time, all to a degree which is robust and state of the art. FreeCat is based on the hypothesis that we can do this by following a language design approach based on type theory, when we do not try to rule out logical inconsistency in the core type theory.

By definition, a system is logically inconsistent when it can prove that some statement is both true and false. In the case of type theory based programming languages such as FreeCat, this definition depends on the Curry-Howard correspondence, under which types are considered as statements, and values are considered as proofs of the statements which are their types. The statement that FreeCat is logically inconsistent means in other words that in FreeCat, for any type it is possible to construct a value inhabiting that type.

Programming languages to which FreeCat is similar include Haskell, PureScript, ML, Agda, Coq, Cayenne, and Idris. FreeCat follows a novel variant of a well-established type theory based approach to programming language design.

What's novel (as far as I'm aware) about FreeCat is that it accepts the possibility of logical inconsistency, and it incorporates the assumption that logical inconsistency will be possible, starting from the design of the core type theory. In contrast, similar languages I'm aware of have mechanisms for ruling out inconsistency incorporated into the core type theory, even in cases where the final language is inconsistent. The motivation for designing FreeCat in this way is the hope that the resulting language will be significantly simpler and easier to understand, compared to alternatives, while also being more flexible and expressive.

This document describes FreeCat from a theoretical perspective. There are two main target audiences. First, programming language theorists who want to understand FreeCat's theoretical contributions. Second, people who want to understand the implementation of FreeCat, for example in order to contribute to it.

FreeCat is an open source, non-profit project whose primary aim is to give people a new way to develop software. The hope is that FreeCat will help people reduce their costs for developing software, while achieving higher quality.

A further, related aim of this project is to describe a new approach to understanding the foundations of math. The hope is that people will find this approach simpler, conceptually clearer, and capable of expressing more concepts, compared to alternatives. The capability to express more concepts comes from not imposing restrictions designed to prevent logical inconsistency. This approach is limited in scope to constructive math, and more specifically it is limited to countably infinite objects and (partial) computable functions. These limitations can probably be removed if one gives up the goal of being able to implement the system as a computer programming language.

FreeCat doesn't aim to be the best approach to solving everybody's problem. For now the focus is on making it a good approach to solving some problems.

The current implementation of FreeCat can be considered the reference implementation in progress. This implementation provides the most complete definition and explanation of FreeCat. This implementation doesn't focus on performance optimization. The plan is to keep the reference implementation as simple as possible, optimizing for ease of human comprehension. Once the reference implementation is mature, it would provide a good basis for writing a performance-optimizing implementation.

The conception and justification of FreeCat is rooted in a holistic, interdisciplinary approach to technical analysis. This holistic methodology assumes that there are deep connections between fundamental problems in different technical disciplines. It assumes in essence that we can clarify our thinking about technical problems in general by developing theories which can systematize solutions to technical problems in general.

This design document aims to give a self-contained conceptual explanation of FreeCat. The Context section is not self-contained. The other sections should explain FreeCat in a self-contained way which does not require understanding of the Context section. It's hard to state exact prerequisites for reading this document, but practically necessary prerequisites include some familiarity with functional programming and programming language theory concepts.

Prior experience in any of the following areas is helpful, but not necessarily required, for understanding this document: type theory, foundations of math, mathematical logic, philosophical logic, category theory, abstract/universal algebra, holistic analysis.

\section{Context}

This section gestures at some of the areas of thought which are closely related to FreeCat. The main aim is to give an idea of where FreeCat's intellectual DNA comes from. For people familiar with these fields, hopefully it will help to contextualize FreeCat. None of this section is necessary for understanding FreeCat. It aims to provide perspectives which are useful for understanding FreeCat and its motivations.

TODO: sprinkle some citations

\subsection{Symbolic computation}

Symbolic computation is one conceptual paradigm from which FreeCat is derived. A prototypical example of a symbolic computation system is Lisp. In Lisp, the most fundamental data structures are symbols and conses. These two simple data structures suffice for basic untyped symbolic computation. Typed symbolic computation languages include ML, Haskell, PureScript, and so forth. In these languages the notion of algebraic data types replaces the notions of symbols and conses.

FreeCat is another typed symbolic computation language. The basic and only data structure is the (symbolic) expression. The simplest types of expressions are symbols and function applications. Constructors are functions with no reduction rules. Instead of algebraic data types, users are given the ability to declare symbols to have arbitrary types. They can use this feature to declare types, values belonging to types, and constructors.

\subsection{Type theory and set theory}

Type theory is a field of math and a way of describing the foundations of math. Type theory is closely related to set theory. Set theory is the study of sets. Sets are collections of objects: e.g., the set of all even integers, the set of all unicorns, the set of all sets.

Type theory is basically a theoretical approach to studying sets, which can be distinguished from classical set theory. Classical set theory, as exemplified by ZFC, was originally motivated in essence by the desire to provide theoretical foundations for math. Type theory today is most interesting for its applications to technology. Many computer programming languages and software verification systems are based closely on type theory. Examples include Haskell, ML, Coq, Agda, and Idris. The demonstrated applicability of type theory to technology distinguishes it from classical set theory. The reason for the distinction is that type theory has been formulated in such a way that computers can feasibly process it.

There are other interesting differences between type theory and classical set theory. In classical set theory, every object is an element of infinitely many sets, whereas in many versions of type theory (FreeCat included), every object is an element of at most one set (i.e. type).

Also, classical set theory includes the principle of extensionality, which states that if two sets have exactly the same elements, then they are the same set. Type theory frequently does not include the principle of extensionality. In most computer implementations of type theory, the principle of extensionality is not included, or it's trivially true because no two distinct sets have any elements in common.

Here is a further important difference between type theory and classical set theory. Classical set theory is based on classical logic, most often first-order logic. The classical approach to logic and set theory defines logical rules of inference, such as those of first-order logic, and axioms about sets, such as those of ZFC. When combined they let you do math, once you've defined every mathematical concept in terms of sets. Type theory, on the other hand, simply defines rules for talking about types, and the rules of logic can be derived from these rules via the Curry-Howard isomorphism. Whereas classical set theory is founded on logic, type theory stands alone and can be used as a foundation for logic.

In short, type theory is a way of thinking about sets, which can form the basis of computer programming languages, which often relaxes or trivializes the principle of extensionality, and which unifies logic with set theory via the Curry-Howard isomorphism.

\subsection{Constructive math}

Constructive math is a style of math in which one restricts one's attention to mathematical objects which can be constructed in some suitable sense. For example, if you are doing math which only pertains to a finite number of things which could fit in the universe, then in a robust sense the math you are doing is constructive.

Intuitionism is a subfield or paradigm of constructive math. Speaking generally and simplistically, intuitionists think that math properly concerns objects which can be constructed mentally. Intuitionists think that if an object exists for the purposes of math, then we can mentally construct (conceptualize, visualize) the object to any desired degree of detail. Whether you agree or disagree with intuitionists, their idea of mental construction of mathematical objects provides an accessible way of thinking about constructive math.

Constructive math does not necessarily restrict its attention to finite objects only. There are a wide variety of ways of understanding the notion of constructive math, and the widest variety is in the ways of understanding constructive math which assume that constructive math can study infinite things.

The varieties of type theory which are most relevant to technology are constructive type theories. What it means for a type theory to be constructive is a subtle question to which many answers are possible. For purposes of intuition, I lean on the intuitionist notion of mental construction. Constructive type theory, I'll say, is only concerned with objects which can be mentally constructed to any desired degree of detail, as well as realized in computer implementations. Roughly, constructive type theory (conceived this way) can talk about finite objects, countably infinite types, and infinite objects which can be described by means of (partial) computable functions. For example, constructive type theory can talk about the type of integers, and the type of (partial computable) functions from integers to integers.

The real numbers are an example of something constructive type theory can't talk about. There are uncountably many real numbers. If you had a computer with infinite memory and infinite computation time, such a computer could not represent and do arithmetic on all real numbers. That statement assumes the hypothetical infinite computer is built in something resembling a conventional manner: something like an infinitely large circuit board whose circuits are of uniform density. Actual computers have only finite memory and computation time. Uncountably infinite sets like the real numbers are far beyond what actual computers can fathom. Therefore they are beyond the realm of constructive type theory as I'm conceiving it.

\subsection{Inconsistent math}

FreeCat is a system of inconsistent math. ``Inconsistent math'' refers to any style of math where contradictions can be true, or in other words where the same statement can be both true and false. Inconsistent math is a fairly obscure and unpopular subfield of math, which I believe is mostly studied and practiced by philosophers.

Inconsistent math is unpopular probably in large part because most people assume that it is absurd and impossible for any statement (or at least any statement of math) to be provably both true and false. FreeCat starts by rejecting that assumption, following other scholars including C.E. Mortensen, Mark Colyvan, Zach Weber, Graham Priest, Jc Beall, and David Ripley, to name a few.

\subsection{Functional programming}

FreeCat is a functional programming language. Functional programming is a way of thinking about software engineering. It is a very broad topic which today has increasing importance to practical software engineers.

Functional programming languages can be classified as pure or impure. In pure functional languages, there is no notion of mutable state in the semantics of the core language. Pure functional languages ask the programmer to think about a world in which there is no change. Impure functional languages lack this property.

Functional programming languages can be classified as typed or untyped, depending on whether or not they have a type system as part of the semantics of the core language.

FreeCat is a pure typed functional programming language. This puts it in the same class as programming languages including Agda, Cayenne, Coq, Haskell, Idris, and PureScript.

All of these languages are based on type theory. Type theory provides the underlying mathematical theories which are used to construct the languages mentioned in the previous paragraph. As far as I understand, in every case mentioned, the underlying type theories are constructive. This makes sense because constructive type theories can talk about what computers can talk about, whereas non-constructive type theories more or less by definition (depending on your definition) can talk about some things which computers can't talk about.

Most of the type theory literature is concerned with logically consistent type theories. A logically consistent type theory is one in which it is not possible to prove that the same statement is both true and false. To prove a statement is in other words to construct an inhabitant of the type which is the statement under the Curry-Howard correspondence.

Practical typed functional programming languages tend to be logically inconsistent. This means that in these languages it's possible to prove any statement, or in other words (under the Curry-Howard correspondence), for any type it's possible to construct a value inhabiting it. Haskell, Idris, PureScript, Agda, and Coq all have this property, either by the nature of the type system (as with Haskell), or by importing a module (as with PureScript), or in the case where you make assumptions which are logically inconsistent (as with Agda and Coq).

There are some good reasons to make a practical programming language inconsistent or potentially inconsistent. For example, a language is potentially inconsistent if you are able to tell the implementation to assume that something is true when you haven't proven it. One important reason to want this capability is to be able to compile a program which is missing a proof you don't yet understand how to construct or don't have time to construct.

Another reason to allow a programming language to be inconsistent is that the restrictions which type theorists impose to avoid logical inconsistency tend to prevent some ideas from being expressed.

There is an interesting disconnect here. Type theorists usually study consistent type theories. Designers of practical typed functional programming languages tend to construct inconsistent languages, and there seem to be some good reasons for that. Yet language designers who rely on type theory have tended to base their work on consistent type theories, even when the languages they design are inconsistent in the end. Arguably this leads to a worst of both worlds situation, where you have restrictions on what you can express which are intended to prevent inconsistency, but you also have the potential of inconsistency.

FreeCat is based on the approach of rethinking type theory from the beginning with the assumption that it's not necessary to take steps to prevent the possibility of inconsistency. Of course it will be useful to have tools to try to discover inconsistency, or to rule out inconsistency in cases where this is practical and desirable. But FreeCat's core type theory doesn't contain restrictions designed to prevent paradoxes. This simplifies the core type theory and language design, and the hypothesis is that this will lead to substantial additional simplifications further down the road.

The previous statements locate FreeCat in the space of conceptual paradigms discussed so far. FreeCat is a pure typed functional programming language and an approach to the foundations of math. It is founded on a form of inconsistent constructive type theory.

\subsection{Category theory}

Category theory is a field of math with close connections to logic, type theory, and the foundations of math, among many other fields. Category theory is a valuable tool for interdisciplinary/holistic technical analysis. Category theory provides a useful perspective on the core concepts of FreeCat. FreeCat, in turn, provides a useful perspective on the core concepts of category theory.

FreeCat has the core concepts of types and functions, which correspond to category theory's notions of objects and morphisms. All FreeCat constructions can be considered to occur in a category of all FreeCat types, within which it is possible to construct an infinite variety of categories.

From this perspective, FreeCat defines a form of inconsistent constructive category theory. This form of category theory abandons the usual paradox-avoiding restrictions of category theory, with the consequence that categories such as the category of all categories and the category of all groups can be discussed.

\subsection{Abstract/universal algebra}

Abstract algebra is a field of math which (basically) studies mathematical objects considered as sets of abstract objects with operations defined on them, with the sets and operations usually required to satisfy axioms.

Universal algebra is a field of math which tries to generalize the patterns of abstract algebra in the form of general theories of algebras and concepts which help in studying algebras.

FreeCat is conceptually connected to abstract algebra and universal algebra. FreeCat provides a system for defining sets (types) and operations (functions) on them. FreeCat can be viewed as a general system for constructing algebras. As such, FreeCat provides a way of thinking about abstract/universal algebra, while abstract/universal algebra provides a way of thinking about FreeCat.

\section{Basic Concepts}

The most basic concept in FreeCat is the concept of an object. Everything FreeCat can talk about is an object. ``Object'' is the root node of FreeCat's conceptual taxonomy.

Types are a fundamental class of object. Every object is an instance of some type. There is a type called Type. Every type is an instance of Type. In particular, Type is an instance of itself.

Objects in FreeCat are represented by expressions. For all practical purposes, in FreeCat, objects can be equated with expressions.

Functions are a fundamental class of object. A function maps objects of some type to objects of other types. The type of a function's output can be dependent on the object it receives as input. In other words, FreeCat is a dependently typed language.

Functions are defined by pattern matching equations. These equations express rules stating that expressions of given shapes can be replaced by other, dependent expressions. A function can have different equations defined for it in different contexts. A lambda expression can be thought of as having exactly one pattern matching equation.

A constructor is a function which has no pattern matching equations defined. Whether a function is a constructor or not can be dependent on the context.

FreeCat expressions are evaluated following the rule of eager evaluation, where subexpressions of an expression are completely evaluated, left to right, before performing any evaluation step on the outermost expression. Pattern matching definitions are tried in the order they were declared, with the first match being used.

Every expression has a type, which is intrinsic to it. The type is itself an expression, whose type is Type. The type of an expression of a specific form will depend on the context in which the expression originally occurs. A symbol name, such as ``foo'' or ``Type,'' may denote different symbols in different contexts. As such, syntactically identical expressions may be semantically different expressions.

There is a function digestExpr of type $\text{Context} \to \text{RawExpr} \to \text{FreeCat Expr}$. (Here FreeCat denotes the FreeCat monad, which accounts for error handling and other issues.) A RawExpr or raw expression is the syntax of an expression without any contextual semantic interpretation applied to it. Given a context and a raw expression, digestExpr gives you an expression which is the interpretation of that raw expression in that context (or else it throws an error, etc.) This function, digestExpr, describes the one-to-many, context-dependent correspondence between syntactic or raw expressions, and semantic expressions, i.e. expressions.

There are the following kinds of expressions: symbols, applications, lambdas, and (dependent and non-dependent) function types.

A context can be represented as a sequence of declarations. There are the following kinds of declarations: type declarations and equation declarations.

Type declarations assert that a given symbol has a given type. Whenever you have an expression denoting a type, you can declare a symbol to have that type, as long as you haven't previously declared a type for that symbol in the current context.

Equation declarations, also called pattern matching definitions or reduction rules, assert that during evaluation, expressions following the left hand side pattern should be replaced by the right hand side expression. As usual, the right hand expression may be dependent on variables in the left hand pattern.

Patterns are like expressions, but they're restricted to consist of symbols and applications. The first symbol in the pattern is called the lead symbol. An equation declaration's left hand pattern must have a lead symbol whose type has been declared previously.

\section{Syntax}

TODO

\section{Semantics}

Semantics is the study of meaning. Whereas the syntax of FreeCat tells you what FreeCat expressions and declarations look like, the semantics of FreeCat tells you how to interpret FreeCat expressions and declarations. Specifically, it gives you a computer-implementable theory of how to interpret FreeCat expressions and declarations.

This section gives a high level overview of the semantics of FreeCat. For a complete definition of the semantics of FreeCat, see the code, and in particular the file src/FreeCat/Core.hs.

A context in FreeCat is represented by a sequence of declarations: type declarations and equation declarations.

There are basically two aspects to the semantics of FreeCat: the semantics of contexts, and the semantics of expressions. The semantics of contexts tells you how to interpret a representation of a context (i.e., a series of declarations). The semantics of expressions tells you how to interpret an expression relative to a context.

The semantics of contexts is basically characterized by a function digestContext of type $\text{RawContext} \to \text{FreeCat Context}$. Here RawContext is the type of uninterpreted, syntactic sequences of declarations. Context is the type of contexts, and FreeCat is the FreeCat monad, which deals with error conditions and other things.

The semantics of expressions is basically characterized by two functions: digestExpr and evaluate.

digestExpr has type $\text{Context} \to \text{RawExpr} \to \text{FreeCat Expr}$. It takes as input a context and an uninterpreted syntactic expression, i.e. a RawExpr. It produces as output an interpreted semantic expression, i.e. an Expr (or it throws an error, etc.)

evaluate has type $\text{Context} \to \text{Expr} \to \text{FreeCat Expr}$. It takes as input a context and an expression, and produces as output an expression. The output expression is produced from the input expression by repeatedly reducing all reducible subexpressions, in depth first left to right order, so that in the end there are no reducible subexpressions. A reducible subexpression is either a function application whose head (i.e., left-hand subexpression) is a lambda expression, or a function application matching the left hand pattern of some equation declaration in the current context.

Let's now unpack the types Context and Expr and related types. Both of these types involve the type Symbol, which we'll look at first.

A Symbol basically consists of the following data: its name (a string), its type (an Expr), its native context (the Context in which it first appeared), and its equations (a list of Equation objects representing equation declarations). Symbols are considered to be the same symbol when they have the same name and native context. However, different occurrences in different contexts of the same symbol may have different equations.

An Equation is of the form $a_1 : t_1, ..., a_n : t_n. p \Rightarrow d$, where $a_1,...,a_n$ are symbols, $t_1,...,t_n$ are Expr of type Type, $p$ is a Pattern, and $d$ is an Expr. Each Equation is associated with a Context, called its evaluation context.

TODO

\end{document}


\chapter*{Abstract}

\addcontentsline{toc}{chapter}{Abstract}

This document provides the user with a description of the algebraic
programming system {\REDUCE}.  The capabilities of this system include:
\begin{enumerate}
\item expansion and ordering of polynomials and rational functions,
\item substitutions and pattern matching in a wide variety of forms,
\item automatic and user controlled simplification of expressions,
\item calculations with symbolic matrices,
\item arbitrary precision integer and real arithmetic,
\item facilities for defining new functions and extending program syntax,
\item analytic differentiation and integration,
\item factorization of polynomials,
\item facilities for the solution of a variety of algebraic equations,
\item facilities for the output of expressions in a variety of formats,
\item facilities for generating numerical programs from symbolic input,
\item Dirac matrix calculations of interest to high energy physicists.
\end{enumerate}


\documentclass[letterpaper]{article}
\usepackage[margin=.64in]{geometry}
\usepackage{amsmath}
\usepackage{graphicx}

\title{Goldschmidt Integer Divider User Guide}
\date{2021-09-01}
\author{Jose R. Garcia}

\begin{document}
	\pagenumbering{gobble}
	\maketitle
	\newpage
	\pagenumbering{arabic}

	\tableofcontents
    \newpage

	\section{Abstract}

	The Goldschmidt integer divider written in verilog. Similar to Newton-Raphson but the division step can be pipelined. This document contains and overview of the design and guidance on the usage and integration of this component.

	\section{Syntax and Abbreviations}

	\begin{tabular}{l|l}
		Term & Definition \\
		\hline
		0b0 & Binary number syntax \\
		\hline
		0x0000\_0000 & Hexadecimal number syntax \\
		\hline
		bit & Single binary digit (0 or 1) \\
		\hline
		BYTE & 8-bits wide data unit \\
		\hline
		DWORD & 32-bits wide data unit \\
		\hline
		FPGA & Field Programmable Gate Array \\
		\hline
		GCD & Goldschmidt Convergence Division \\
		\hline
		LSB & Least Significant bit \\
		\hline
		MSB & Most Significant bit \\
		\hline
		WB & Wishbone Interface \\
	\end{tabular}

	\section{Design}
	\paragraph{}
	The Goldschmidt division is an special application of the Newton-Raphson method. This iterative divider computes:
	\begin{equation*}
	d(i) = d[i-1].(2-d[i-1])
	\end{equation*}
	\begin{equation*}
	D(i) = D[i-1].(2-d[i-1])
	\end{equation*}
	were \( d \) is the divisor; \( D \) is the dividend; \( i \) is the step. \( D \) converges toward the quotient and d converges toward 1 at a quadratic rate. For the divisor to converge to 1 it must obviously be less than 2 therefore integers greater than 2 must be multiplied by 10 to the negative powers to shift the decimal point. Consider the following example: $ \dfrac{16}{4} $

	\begin{tabular}{l|l|l|l}
		Step & D & d & 2-d \\ \hline
		inputs & 16 & 4 & - \\
		0 & 1.6 & 0.4 & 1.6 \\
		1 & 2.56 & 0.64 & 1.36 \\
		2 & 3.4816 & 0.8704 & 1.1296 \\
		3 & 3.93281536 & 0.98320384 & 1.01679616 \\
		4 & 3.99887155603702 & 0.999717889009254 & 1.00028211099075 \\
		5 & 3.99999968165356 & 0.999999920413389 & 1.00000007958661 \\
		6 & 3.99999999999997 & 0.999999999999994 & 1.00000000000001 \\
		7 & 4 & 1 & 1 \\
	\end{tabular}

	\paragraph{}The code implementation compares the size of the divisor against $ 2*10^n $ were $ n $ is a natural number. The result of the comparison indicates against which $ 10^m $, were $ m $ is a negative integer, to multiply the divisor. Then the Goldschmidt division is performed until the divisor converges to degree indicated by \textbf{P\_GCD\_ACCURACY}. The quotient returned is the rounded up value to which the dividend converged to. Each Goldschmidt step is performed in to two half steps in order use only half the multipliers and save resources.

	The remainder calculation requires an extra clock which is why the address tag is used to make the decision on whether to do the calculation or skip it. The calculation simply takes the value after the decimal point of the quotient a multiplies it by the divisor.

	\section{Configurable Parameters}

	These are the over-writable parameters.

	\begin{tabular}{l|c|l}
		Parameters & Default State & Description \\ \hline
		P\_GID\_FACTORS\_MSB &  31 & Dividend, divisor and results most significant bit. \\ \hline
		P\_GID\_ACCURACY\_LVL & 12 & Divisor Convergence Threshold. How close to one does it get to\\   & & accept the result. These are the 32bits after the decimal point,\\
		& & 0.XXXXXXXX expressed as an integer. The default value represent\\
		& & the 999 part of a 64bit binary fractional number equal to 0.999. \\ \hline
		P\_GID\_ROUND\_UP\_LVL &  2 & Number of bits to look at after the decimal point to round up. \\
	\end{tabular}

	\section{Clocks and Resets}

	This module only possess one clock domain and a synchronous reset signal.

    \begin{tabular}{l|c|c|l}
        Signals & Initial State & Direction & Definition \\ \hline
		i\_clk &  N/A & In & Input clock. All interfaces are sampled \\
		       &      &    & on the positive edge of this clock signal. \\  \hline
		i\_reset\_sync & N/A & In & Synchronous reset. Used to reset this unit. \\
	\end{tabular}

	\section{Interfaces}
	The divider and divisor are received through i\_master\_div0\_read\_data and i\_master \_div1\_read\_data and qualified by the i\_slave\_stb. The i\_slave\_stb signal could be managed in different ways. It can be a pulse with the width of a singe clock to operate as a pipelined Wishbone interface and the o\_master\_div\_write\_stb can be considered as a Wishbone o\_ack. I can also be operated as a Wishbone standard using those same signals.

	When the division concludes  the o\_master\_div\_write\_stb is asserted and writes the result to the address received through i\_slave\_addr.
	\subsection{WB4 Slave}

	\begin{tabular}{l|c|c|c|l}
		Signals & Initial State & Dimension & Direction & Definition \\ \hline
		i\_wb4\_slave\_stb &  N/A & 1-bit &  Input & Valid data strobe and start\\
		& & & & indicator. \\  \hline
		i\_wb4\_slave\_data & N/A & [(P\_GID\_FACTORS\_MSB*2)+1:0] & Input & Divisor and Dividend. \\  \hline
		i\_wb4\_slave\_tgd & N/A & [1:0] & Input & Indicates the calculation to\\
		& & & & perform.\\
		& & & & bit[1] 0=quotient, 1=remainder;\\
		& & & & bit[0] 0=signed, 1=unsigned \\  \hline
		o\_wb4\_slave\_stall & N/A & 1-bit & Output & Stall, not ready when set to 1. \\
	\end{tabular}

	\subsection{WB4 Master}

	\begin{tabular}{l|c|c|c|l}
		Signals & Initial State & Dimension & Direction & Definition \\ \hline
		o\_wb4\_master\_stb &  N/A & 1-bit &  Input & Valid data strobe and start indicator.\\  \hline
		o\_wb4\_master\_data & N/A & [P\_GID\_FACTORS\_MSB:0] & Output & Operation result.\\  \hline
		i\_wb4\_master\_stall & N/A & 1-bit & Input & Stall, not ready when set to 1. \\
	\end{tabular}

	\section{Test Bench and Simulation}
	Test Bench and Simulation

	\subsection{Test Bench}

	The test bench is written in uvm-python (UVM), it requires cocotb. A Wishbone Slave verification agent stimulates the DUT by sending factors for the DUT to provide the division result. A Wishbone Master verification agent is used as a monitor to capture the result. A predictor sees the Wishbone Slave transactions and consequently generates Wishbone Master transactions to compare against the response generated by the DUT. Figure 1 provides a low detailed description of the test bench components and connections

	\begin{figure}[h]
		\centering
		\includegraphics[width=0.99\linewidth]{../figures/tb_diagram}
		\caption[Test Bench Block Diagram]{Test Bench Block Diagram}
		\label{fig:tbdiagram}
	\end{figure}

	\subsection{Simulation}

	\subsubsection{Prerequisites}

	\begin{tabular}{l}
	    Verilator(version 4.106) \\
	    cocotb \\
	    cocotb-coverage \\
	    uvm-python \\
	    gtkwave(optional)\\
    \end{tabular}

	\paragraph{}To install a simulator follow the instructions in in the verilator website.
	For setting cocotb and uvm-python:

	\begin{tabular}{l}
	    {\tt sudo apt install python3-pip } \\
	    {\tt pip install cocotb } \\
	    {\tt pip install cocotb-coverage } \\
	    {\tt git clone https://github.com/tpoikela/uvm-python.git } \\
	    {\tt cd uvm-python } \\
	    {\tt python -m pip install --user . } \\
    \end{tabular}

	\subsubsection{Execution}

	From the {\tt /Goldschmidt\_Integer\_Divider/sim/ } directory run the command

	{\tt make}\\

	By default the two clocks per step implementation is used for the simulation. To view the wave form open the file \textbf{wave2.gtkw} with \textbf{gtkwave}. If the one clock per step is selected for simulation use \textbf{wave1.gtkw} for the proper set of signals to be loaded into the wave viewer.

	\begin{figure}[h]
		\centering
		\includegraphics[width=0.99\linewidth]{../figures/Screenshot_sim}
		\caption[sim]{Sim successfully completed.}
		\label{fig:screenshotsim}
	\end{figure}

\end{document}