example1-combologic.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Example 1:  A simple combination logic block example."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This example declares a block of hardware with **three one-bit inputs,\n",
    "(a,b,c)** and **two one-bit outputs (sum, cout)**.  The logic declared is a\n",
    "simple one-bit adder and the definition uses some of the most common\n",
    "parts of PyRTL. The adder is then simulated on random data, the\n",
    "wave form is printed to the screen, and the resulting trace is\n",
    "compared to a \"correct\" addition.  **If the result is correct then a 0\n",
    "is returned, else 1**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The basic idea of PyRTL is to specify the component of a some hardware block\n",
    "through the declaration of wires and operations on those wires.  The current\n",
    "working block, an instance of a class devilishly named **Block**, is implicit\n",
    "in all of the below code -- it is easiest to start with the way wires work."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import random\n",
    "import pyrtl"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "pyrtl.reset_working_block()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 1: Define Logic\n",
    "\n",
    "One of the most fundamental types in PyRTL is the **WireVector** which is acts\n",
    "very much like a python list of 1-bit wires.  Unlike a normal list though the\n",
    "number of bits is explicitly declared."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "temp1 = pyrtl.WireVector(bitwidth=1, name='temp1')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Both arguments are in fact optional and default to a bitwidth of 1 and a unique\n",
    "name generated by pyrtl starting with 'tmp'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "temp2 = pyrtl.WireVector()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Two special types of WireVectors are **Input** and **Output**, which are used to specify\n",
    "an interface to the hardware block."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "a, b, c = pyrtl.Input(1, 'a'), pyrtl.Input(1, 'b'), pyrtl.Input(1, 'c')\n",
    "sum, carry_out = pyrtl.Output(1, 'sum'), pyrtl.Output(1, 'carry_out')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Okay, let's build a **one-bit adder**.  To do this we need to use the assignment\n",
    "operator, which is **<<=**.  This takes an already declared wire and *connects*\n",
    "it to some other already declared wire.  Let's start with the **sum bit**, which is\n",
    "of course just the xor of the three inputs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "sum <<= a ^ b ^ c"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The **carry_out bit** would just be * **carry_out <<= a & b | a & c | b & c** * but let's break\n",
    "than down a bit to see what is really happening.  What if we want to give names\n",
    "to the partial signals in the middle of that computation.  When you take\n",
    "*a & b* in PyRTL what that really means is **make an AND gate, connect one input\n",
    "to 'a' and the other to 'b' and return the result of the gate**.  The result of\n",
    "that AND gate can then be assigned to temp1 or it can be used like any other\n",
    "python variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "temp1 <<= a & b  # connect the result of a & b to the pre-allocated wirevector\n",
    "temp2 <<= a & c\n",
    "temp3 = b & c  # temp3 IS the result of b & c (this is the first mention of temp3)\n",
    "carry_out <<= temp1 | temp2 | temp3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can access the working block through **pyrtl.working_block()**, and for most\n",
    "things one block is all you will need.  Example 2 discusses this in more detail,\n",
    "but for now we can just bring the block to see that in fact it looks like the\n",
    "hardware we described.  The format is a bit weird, but roughly translates to\n",
    "a list of gates (the 'w' gates are just wires).  The ins and outs of the gates\n",
    "are printed **name'/'bitwidth''WireVectorType'**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "print('--- One Bit Adder Implementation ---')\n",
    "print(pyrtl.working_block())\n",
    "print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2: Simulate Design\n",
    "\n",
    "Okay, let's get simulate our one-bit adder.  To keep track of the output of\n",
    "the simulation we need to make a new **SimulationTrace** and a **Simulation**\n",
    "that then uses that trace."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "sim_trace = pyrtl.SimulationTrace()\n",
    "sim = pyrtl.Simulation(tracer=sim_trace)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now all we need to do is call **sim.step** to **simulate each clock cycle** of our\n",
    "design.  We just need to pass in some input each cycle which is a dictionary\n",
    "mapping inputs (the *names* of the inputs, not the actual Input instances)\n",
    "and a value for that signal each cycle.  In this simple example we\n",
    "can just specify a random value of 0 or 1 with python's random module.  We\n",
    "call step 15 times to simulate 15 cycles."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "for cycle in range(15):\n",
    "    sim.step({\n",
    "        'a': random.choice([0, 1]),\n",
    "        'b': random.choice([0, 1]),\n",
    "        'c': random.choice([0, 1])\n",
    "        })"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now all we need to do is **print the trace results** to the screen. Here we use\n",
    "**render_trace** with some size information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "print('--- One Bit Adder Simulation ---')\n",
    "sim_trace.render_trace(symbol_len=5, segment_size=5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "a_value = sim.inspect(a)\n",
    "print(\"The latest value of a was: \" + str(a_value))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Verification of Simulated Design\n",
    "\n",
    "Now finally, let's **check the trace** to make sure that sum and carry_out are actually\n",
    "the right values when compared to a python's addition operation.  Note that\n",
    "**all the simulation is done at this point** and we are just checking the wave form\n",
    "but there is no reason you could not do this at simulation time if you had a\n",
    "really long running design."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "for cycle in range(15):\n",
    "    # Note that we are doing all arithmetic on values NOT wirevectors here.\n",
    "    # We can add the inputs together to get a value for the result\n",
    "    add_result = (sim_trace.trace['a'][cycle] +\n",
    "                  sim_trace.trace['b'][cycle] +\n",
    "                  sim_trace.trace['c'][cycle])\n",
    "    # We can select off the bits and compare\n",
    "    python_sum = add_result & 0x1\n",
    "    python_cout = (add_result >> 1) & 0x1\n",
    "    if (python_sum != sim_trace.trace['sum'][cycle] or\n",
    "       python_cout != sim_trace.trace['carry_out'][cycle]):\n",
    "        print('This Example is Broken!!!')"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}