examples/4_blockram/block_ram_party.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       "@import url('http://fonts.googleapis.com/css?family=Source+Code+Pro');\n",
       "@import url('http://fonts.googleapis.com/css?family=Lora');\n",
       "\n",
       "//@import url('http://fonts.googleapis.com/css?family=Open+Sans');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Vollkorn');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Karla');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Poppins');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Arimo');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Roboto');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Lato');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Domine');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Chivo');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Cardo');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Arvo');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Crimson+Text');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Ubuntu');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Fontin');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Raleway');\n",
       "//@import url('http://fonts.googleapis.com/css?family=Merriweather');\n",
       "\n",
       "\n",
       ".CodeMirror pre {\n",
       "    font-family: 'Source Code Pro', Consolas, monocco, monospace;\n",
       "}\n",
       "    div.cell{\n",
       "        //width: 950px;\n",
       "        margin-left: 0% !important;\n",
       "        margin-right: auto;\n",
       "    }\n",
       "    div.text_cell_render{\n",
       "        font-family: 'Lora';\n",
       "        //font-family: 'Open Sans';\n",
       "        //font-family: 'Karla',verdana,arial,sans-serif;\n",
       "        //font-family: 'Roboto',verdana,arial,sans-serif;\n",
       "        //font-family: 'Lato',verdana,arial,sans-serif;\n",
       "        //font-family: 'Domine',verdana,arial,sans-serif;\n",
       "        //font-family: 'Chivo',verdana,arial,sans-serif;\n",
       "        //font-family: 'Cardo',verdana,arial,sans-serif;\n",
       "        //font-family: 'Arvo',verdana,arial,sans-serif;\n",
       "        //font-family: 'Poppins',verdana,arial,sans-serif;\n",
       "        //font-family: 'Ubuntu',verdana,arial,sans-serif;\n",
       "        //font-family: 'Fontin',verdana,arial,sans-serif;\n",
       "        //font-family: 'Raleway',verdana,arial,sans-serif;\n",
       "        //font-family: 'Merriweather',verdana,arial,sans-serif;\n",
       "        //font-family: 'Crimson Text', verdana,arial,sans-serif;\n",
       "        //font-family: verdana,arial,sans-serif;\n",
       "        //font-family: arial,sans-serif;\n",
       "        line-height: 125%;\n",
       "        font-size: 130%;\n",
       "        text-align: justify;\n",
       "        text-justify:inter-word;\n",
       "    }\n",
       "    div.text_cell code {\n",
       "        background: transparent;\n",
       "        color: #000000;\n",
       "        font-weight: 400;\n",
       "        font-size: 12pt;\n",
       "        //font-style: bold;\n",
       "        font-family:  'Source Code Pro', Consolas, monocco, monospace;\n",
       "   }\n",
       "    h1 {\n",
       "        font-family: 'Open sans',verdana,arial,sans-serif;\n",
       "\t}\n",
       "\n",
       "    div.input_area {\n",
       "        background: #F6F6F9;\n",
       "        border: 1px solid #586e75;\n",
       "    }\n",
       "\n",
       "    .text_cell_render h1 {\n",
       "        font-weight: 400;\n",
       "        font-size: 30pt;\n",
       "        line-height: 100%;\n",
       "        color:#c76c0c;\n",
       "        margin-bottom: 0.5em;\n",
       "        margin-top: 1em;\n",
       "        display: block;\n",
       "        white-space: wrap;\n",
       "        text-align: left;\n",
       "    }\n",
       "    h2 {\n",
       "        font-family: 'Open sans',verdana,arial,sans-serif;\n",
       "        text-align: left;\n",
       "    }\n",
       "    .text_cell_render h2 {\n",
       "        font-weight: 500;\n",
       "        font-size: 16pt;\n",
       "        font-style: italic;\n",
       "        line-height: 100%;\n",
       "        color:#c76c0c;\n",
       "        margin-bottom: 0.5em;\n",
       "        margin-top: 1.5em;\n",
       "        display: block;\n",
       "        white-space: wrap;\n",
       "        text-align: left;\n",
       "    }\n",
       "    h3 {\n",
       "        font-family: 'Open sans',verdana,arial,sans-serif;\n",
       "    }\n",
       "    .text_cell_render h3 {\n",
       "        font-weight: 500;\n",
       "        font-size: 14pt;\n",
       "        line-height: 100%;\n",
       "        color:#d77c0c;\n",
       "        margin-bottom: 0.5em;\n",
       "        margin-top: 2em;\n",
       "        display: block;\n",
       "        white-space: wrap;\n",
       "        text-align: left;\n",
       "    }\n",
       "    h4 {\n",
       "        font-family: 'Open sans',verdana,arial,sans-serif;\n",
       "    }\n",
       "    .text_cell_render h4 {\n",
       "        font-weight: 100;\n",
       "        font-size: 14pt;\n",
       "        color:#d77c0c;\n",
       "        margin-bottom: 0.5em;\n",
       "        margin-top: 0.5em;\n",
       "        display: block;\n",
       "        white-space: nowrap;\n",
       "    }\n",
       "    h5 {\n",
       "        font-family: 'Open sans',verdana,arial,sans-serif;\n",
       "    }\n",
       "\n",
       "    .text_cell_render h5 {\n",
       "        font-weight: 200;\n",
       "        font-style: normal;\n",
       "        color: #1d3b84;\n",
       "        font-size: 16pt;\n",
       "        margin-bottom: 0em;\n",
       "        margin-top: 0.5em;\n",
       "        display: block;\n",
       "        white-space: nowrap;\n",
       "    }\n",
       "    div.output_subarea.output_text.output_pyout {\n",
       "        overflow-x: auto;\n",
       "        overflow-y: scroll;\n",
       "        max-height: 50000px;\n",
       "    }\n",
       "    div.output_subarea.output_stream.output_stdout.output_text {\n",
       "        overflow-x: auto;\n",
       "        overflow-y: scroll;\n",
       "        max-height: 50000px;\n",
       "    }\n",
       "    div.output_wrapper{\n",
       "        margin-top:0.2em;\n",
       "        margin-bottom:0.2em;\n",
       "}\n",
       "\n",
       "    .rendered_html table {\n",
       "        font-size: 100%;\n",
       "    }\n",
       "\n",
       "    code{\n",
       "        font-size: 6pt;\n",
       "\n",
       "    }\n",
       "    .rendered_html code{\n",
       "    background-color: transparent;\n",
       "    }\n",
       "    ul{\n",
       "        margin: 2em;\n",
       "    }\n",
       "    ul li{\n",
       "        padding-left: 0.5em;\n",
       "        margin-bottom: 0.5em;\n",
       "        margin-top: 0.5em;\n",
       "    }\n",
       "    ul li li{\n",
       "        padding-left: 0.2em;\n",
       "        margin-bottom: 0.2em;\n",
       "        margin-top: 0.2em;\n",
       "    }\n",
       "    ol{\n",
       "        margin: 2em;\n",
       "    }\n",
       "    ol li{\n",
       "        padding-left: 0.5em;\n",
       "        margin-bottom: 0.5em;\n",
       "        margin-top: 0.5em;\n",
       "    }\n",
       "    ul li{\n",
       "        padding-left: 0.5em;\n",
       "        margin-bottom: 0.5em;\n",
       "        margin-top: 0.2em;\n",
       "    }\n",
       "    a:link{\n",
       "       color:#447adb;\n",
       "    }\n",
       "    a:visited{\n",
       "       color: #1d3b84;\n",
       "    }\n",
       "    a:hover{\n",
       "       color: #1d3b84;\n",
       "    }\n",
       "    a:focus{\n",
       "       color:#447adb;\n",
       "    }\n",
       "    a:active{\n",
       "       font-weight: bold;\n",
       "       color:#447adb;\n",
       "    }\n",
       "    .rendered_html :link {\n",
       "       text-decoration: underline;\n",
       "    }\n",
       "    .rendered_html :hover {\n",
       "       text-decoration: none;\n",
       "    }\n",
       "    .rendered_html :visited {\n",
       "      text-decoration: none;\n",
       "    }\n",
       "    .rendered_html :focus {\n",
       "      text-decoration: none;\n",
       "    }\n",
       "    .rendered_html :active {\n",
       "      text-decoration: none;\n",
       "    }\n",
       "    .warning{\n",
       "        color: rgb( 240, 20, 20 )\n",
       "    }\n",
       "    hr {\n",
       "      color: #f3f3f3;\n",
       "      background-color: #f3f3f3;\n",
       "      height: 1px;\n",
       "    }\n",
       "    blockquote{\n",
       "      display:block;\n",
       "      background: #fcfcfc;\n",
       "      border-left: 5px solid #c76c0c;\n",
       "      font-family: 'Open sans',verdana,arial,sans-serif;\n",
       "      width:680px;\n",
       "      padding: 10px 10px 10px 10px;\n",
       "      text-align:justify;\n",
       "      text-justify:inter-word;\n",
       "      }\n",
       "      blockquote p {\n",
       "        margin-bottom: 0;\n",
       "        line-height: 125%;\n",
       "        font-size: 100%;\n",
       "      }\n",
       "</style>\n",
       "<script>\n",
       "    MathJax.Hub.Config({\n",
       "                        TeX: {\n",
       "                           extensions: [\"AMSmath.js\"],\n",
       "                           equationNumbers: { autoNumber: \"AMS\", useLabelIds: true}\n",
       "                           },\n",
       "                tex2jax: {\n",
       "                    inlineMath: [ ['$','$'], [\"\\\\(\",\"\\\\)\"] ],\n",
       "                    displayMath: [ ['$$','$$'], [\"\\\\[\",\"\\\\]\"] ]\n",
       "                },\n",
       "                displayAlign: 'center', // Change this to 'center' to center equations.\n",
       "                \"HTML-CSS\": {\n",
       "                    scale:95,\n",
       "                        availableFonts: [],\n",
       "                        preferredFont:null,\n",
       "                        webFont: \"TeX\",\n",
       "                    styles: {'.MathJax_Display': {\"margin\": 4}}\n",
       "                }\n",
       "        });\n",
       "</script>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.core.display import HTML\n",
    "HTML(open('../css/custom.css', 'r').read())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# A function I'll use later to extract FPGA resource usage stats from Yosys log output.\n",
    "def print_stats(yosys_log):\n",
    "    stat_start_line = yosys_log.grep(r'^2\\.27\\. ')\n",
    "    stat_end_line = yosys_log.grep(r'^2\\.28\\. ')\n",
    "    start_index = yosys_log.index(stat_start_line[0])\n",
    "    end_index = yosys_log.index(stat_end_line[0])\n",
    "    print('\\n'.join(yosys_log[start_index+2:end_index-1]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**_Note_**: If you're reading this as a static HTML page, you can also get it as an\n",
    "executable Jupyter notebook [here](https://github.com/xesscorp/pygmyhdl/tree/master/examples)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Block (RAM) Party!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I've already presented some simple combinational and sequential circuits using the FPGA's LUTs and D flip-flops.\n",
    "But the iCE40 has even more to offer: *block RAMs!*\n",
    "These are specialized blocks (hence the name) of high density [RAM](https://en.wikipedia.org/wiki/Random-access_memory)\n",
    "embedded within the FPGA fabric.\n",
    "These *BRAMs* provide a place to store lots of bits without using up all the DFFs in the FPGA.\n",
    "Now I'll show you how to use them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inferring Block RAMs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you look at the\n",
    "[iCE40 technology library docs](http://www.latticesemi.com/~/media/LatticeSemi/Documents/TechnicalBriefs/iCE201404TechnologyLibrary.pdf?document_id=50524),\n",
    "you'll see how to instantiate a BRAM using Verilog or VHDL.\n",
    "But that doesn't do us much good since we're using MyHDL.\n",
    "So I'm going to demonstrate how to describe a RAM using MyHDL such that Yosys will *infer* that a BRAM is what I want.\n",
    "\n",
    "As a first cut, here's a description of a simple RAM:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from pygmyhdl import *\n",
    "\n",
    "@chunk\n",
    "def ram(clk_i, en_i, wr_i, addr_i, data_i, data_o):\n",
    "    '''\n",
    "    Inputs:\n",
    "      clk_i:  Data is read/written on the rising edge of this clock input.\n",
    "      en_i:   When high, the RAM is enabled for read/write operations.\n",
    "      wr_i:   When high, data is written to the RAM; when low, data is read from the RAM.\n",
    "      addr_i: Address bus for selecting which RAM location is being read/written.\n",
    "      data_i: Data bus for writing data into the RAM.\n",
    "    Outputs:\n",
    "      data_o: Data bus for reading data from the RAM.\n",
    "    '''\n",
    "    \n",
    "    # Create an array of words to act as RAM locations for storing data.\n",
    "    # The number of bits in each word is set by the width of the data input bus.\n",
    "    # The number of words is determined by the width of the address bus so,\n",
    "    # for example, a 4-bit address would create 2**4 = 16 RAM locations.\n",
    "    mem = [Bus(len(data_i)) for _ in range(2**len(addr_i))]\n",
    "    \n",
    "    # Perform read/write operations on the rising edge of the clock.\n",
    "    @seq_logic(clk_i.posedge)\n",
    "    def logic():\n",
    "        if en_i:\n",
    "            # The read/write operations only get executed if the enable input is high.\n",
    "            if wr_i:\n",
    "                # If the write-control is high, write the value on the input data bus\n",
    "                # into the array of words at the given address value.\n",
    "                mem[addr_i.val].next = data_i\n",
    "            else:\n",
    "                # If the write-control is low, read data from the word at the\n",
    "                # given address value and send it to the output data bus.\n",
    "                data_o.next = mem[addr_i.val]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To verify this actually works as a RAM, I'll run a little simulation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  Time    en    clk    wr    addr    data_i    data_o\n",
      "------  ----  -----  ----  ------  --------  --------\n",
      "     0     1      0     1       0         1         0\n",
      "     1     1      1     1       0         1         0\n",
      "     2     1      0     1       1         4         0\n",
      "     3     1      1     1       1         4         0\n",
      "     4     1      0     1       2         7         0\n",
      "     5     1      1     1       2         7         0\n",
      "     6     1      0     1       3        10         0\n",
      "     7     1      1     1       3        10         0\n",
      "     8     1      0     1       4        13         0\n",
      "     9     1      1     1       4        13         0\n",
      "    10     1      0     1       5        16         0\n",
      "    11     1      1     1       5        16         0\n",
      "    12     1      0     1       6        19         0\n",
      "    13     1      1     1       6        19         0\n",
      "    14     1      0     1       7        22         0\n",
      "    15     1      1     1       7        22         0\n",
      "    16     1      0     1       8        25         0\n",
      "    17     1      1     1       8        25         0\n",
      "    18     1      0     1       9        28         0\n",
      "    19     1      1     1       9        28         0\n",
      "    20     1      0     0       0        28         0\n",
      "    21     1      1     0       0        28         1\n",
      "    22     1      0     0       1        28         1\n",
      "    23     1      1     0       1        28         4\n",
      "    24     1      0     0       2        28         4\n",
      "    25     1      1     0       2        28         7\n",
      "    26     1      0     0       3        28         7\n",
      "    27     1      1     0       3        28        10\n",
      "    28     1      0     0       4        28        10\n",
      "    29     1      1     0       4        28        13\n",
      "    30     1      0     0       5        28        13\n",
      "    31     1      1     0       5        28        16\n",
      "    32     1      0     0       6        28        16\n",
      "    33     1      1     0       6        28        19\n",
      "    34     1      0     0       7        28        19\n",
      "    35     1      1     0       7        28        22\n",
      "    36     1      0     0       8        28        22\n",
      "    37     1      1     0       8        28        25\n",
      "    38     1      0     0       9        28        25\n",
      "    39     1      1     0       9        28        28\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "<class 'myhdl.StopSimulation'>: No more events\n"
     ]
    }
   ],
   "source": [
    "initialize()  # Yeah, yeah, get things ready for simulation...\n",
    "\n",
    "# Create wires and buses to connect to the RAM.\n",
    "clk = Wire(name='clk')\n",
    "en = Wire(name='en')\n",
    "wr = Wire(name='wr')\n",
    "addr = Bus(8, name='addr')\n",
    "data_i = Bus(8, name='data_i')\n",
    "data_o = Bus(8, name='data_o')\n",
    "\n",
    "# Instantiate the RAM.\n",
    "ram(clk_i=clk, en_i=en, wr_i=wr, addr_i=addr, data_i=data_i, data_o=data_o)\n",
    "\n",
    "def ram_test_bench():\n",
    "    '''RAM test bench: write 10 values to RAM, then read them back.'''\n",
    "    \n",
    "    en.next = 1  # Enable the RAM.\n",
    "    \n",
    "    # Write data to the first 10 locations in the RAM.\n",
    "    wr.next = 1  # Enable writes to RAM.\n",
    "    for i in range(10):\n",
    "        addr.next = i            # Select RAM location to be written.\n",
    "        data_i.next = 3 * i + 1  # Generate a value to write to the location.\n",
    "        \n",
    "        # Pulse the clock to write the data to RAM.\n",
    "        clk.next = 0\n",
    "        yield delay(1)\n",
    "        clk.next = 1\n",
    "        yield delay(1)\n",
    "\n",
    "    # Read data from the 10 locations that were written.\n",
    "    wr.next = 0  # Disable writes to RAM == enable reads from RAM.\n",
    "    for i in range(10):\n",
    "        addr.next = i   # Select the RAM location to be read.\n",
    "        \n",
    "        # Pulse the clock to read the data from RAM.\n",
    "        clk.next = 0\n",
    "        yield delay(1)\n",
    "        clk.next = 1\n",
    "        yield delay(1)\n",
    "\n",
    "# Simulate the RAM using the test bench.\n",
    "simulate(ram_test_bench())\n",
    "\n",
    "# Look at the RAM inputs and outputs as the simulation was executed.\n",
    "show_text_table('en clk wr addr data_i data_o')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The simulation results show the values [1, 4, 7, 10, 13, 16, 19, 22, 25, 28] entering on the data input bus\n",
    "and being stored in the first ten RAM locations\n",
    "during the interval $t =$ [0, 19] when the write control input is high.\n",
    "Then the same set of data appears on the data output bus during $t =$ [20, 39] when the \n",
    "first ten locations of the RAM are read back.\n",
    "So the RAM passes this simple simulation.\n",
    "\n",
    "Now let's see how Yosys interprets this RAM description.\n",
    "First, I'll generate the Verilog code for a RAM with an eight-bit address bus ($2^8$ = 256 locations) with\n",
    "each word able to store an eight-bit byte.\n",
    "This works out to a total storage of 256&nbsp;$\\times$&nbsp;8&nbsp;bits&nbsp;$=$&nbsp;2048&nbsp;bits.\n",
    "That should fit comfortably in a single, 4096-bit BRAM."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "c:\\python35-32\\lib\\site-packages\\ipykernel_launcher.py:1: UserWarning: \n",
      "    toVerilog(): Deprecated usage: See http://dev.myhdl.org/meps/mep-114.html\n",
      "  \"\"\"Entry point for launching an IPython kernel.\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "[<myhdl._always_seq._AlwaysSeq at 0x55a66d0>]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "toVerilog(ram, clk_i=Wire(), en_i=Wire(), wr_i=Wire(), addr_i=Bus(8), data_i=Bus(8), data_o=Bus(8))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, I'll pass the Verilog code to Yosys and see what FPGA resources it uses:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "=== ram ===\n",
      "\n",
      "   Number of wires:               2307\n",
      "   Number of wire bits:           4127\n",
      "   Number of public wires:         262\n",
      "   Number of public wire bits:    2075\n",
      "   Number of memories:               0\n",
      "   Number of memory bits:            0\n",
      "   Number of processes:              0\n",
      "   Number of cells:               4108\n",
      "     SB_DFFE                      2056\n",
      "     SB_LUT4                      2052\n"
     ]
    }
   ],
   "source": [
    "log = !yosys -p \"synth_ice40\" ram.v\n",
    "print_stats(log)                     # Just print the FPGA resource usage stats from the log output."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Yowsa! It looks like Yosys is building the RAM from individual flip-flops -- 2056 of 'em.\n",
    "That's definitely not what we want.\n",
    "\n",
    "The reason for the lousy implementation is that I haven't given Yosys a description that will\n",
    "trigger its RAM inference procedure.\n",
    "I searched and\n",
    "[found the following Verilog code](https://stackoverflow.com/questions/41499494/how-can-i-use-ice40-4k-block-ram-in-512x8-read-mode-with-icestorm)\n",
    "that *does* trigger Yosys:\n",
    "\n",
    "```\n",
    "module test(input clk, wen, input [8:0] addr, input [7:0] wdata, output reg [7:0] rdata);\n",
    "  reg [7:0] mem [0:511];\n",
    "  initial mem[0] = 255;\n",
    "  always @(posedge clk) begin\n",
    "        if (wen) mem[addr] <= wdata;\n",
    "        rdata <= mem[addr];\n",
    "  end\n",
    "endmodule\n",
    "```\n",
    "\n",
    "Then I just fiddled with my code until it produced something like that.\n",
    "It turns out the culprit is the presence of the enable input (`en_i`).\n",
    "Here's what happens if I take that out and leave the RAM enabled all the time:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "c:\\python35-32\\lib\\site-packages\\ipykernel_launcher.py:22: UserWarning: \n",
      "    toVerilog(): Deprecated usage: See http://dev.myhdl.org/meps/mep-114.html\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "=== ram ===\n",
      "\n",
      "   Number of wires:                  7\n",
      "   Number of wire bits:             43\n",
      "   Number of public wires:           5\n",
      "   Number of public wire bits:      26\n",
      "   Number of memories:               0\n",
      "   Number of memory bits:            0\n",
      "   Number of processes:              0\n",
      "   Number of cells:                  2\n",
      "     SB_LUT4                         1\n",
      "     SB_RAM40_4K                     1\n"
     ]
    }
   ],
   "source": [
    "@chunk\n",
    "def ram(clk_i,wr_i, addr_i, data_i, data_o):\n",
    "    '''\n",
    "    Inputs:\n",
    "      clk_i:  Data is read/written on the rising edge of this clock input.\n",
    "      wr_i:   When high, data is written to the RAM; when low, data is read from the RAM.\n",
    "      addr_i: Address bus for selecting which RAM location is being read/written.\n",
    "      data_i: Data bus for writing data into the RAM.\n",
    "    Outputs:\n",
    "      data_o: Data bus for reading data from the RAM.\n",
    "    '''\n",
    "    \n",
    "    mem = [Bus(len(data_i)) for _ in range(2**len(addr_i))]\n",
    "    \n",
    "    @seq_logic(clk_i.posedge)\n",
    "    def logic():\n",
    "        if wr_i:\n",
    "            mem[addr_i.val].next = data_i\n",
    "        else:\n",
    "            data_o.next = mem[addr_i.val]\n",
    "                \n",
    "toVerilog(ram, clk_i=Wire(), wr_i=Wire(), addr_i=Bus(8), data_i=Bus(8), data_o=Bus(8))\n",
    "\n",
    "log = !yosys -p \"synth_ice40\" ram.v\n",
    "print_stats(log)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now the statistics are much more reasonable: only a single block RAM is used."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can even remove the `else` clause and continually read out the RAM location at the current address:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "c:\\python35-32\\lib\\site-packages\\ipykernel_launcher.py:21: UserWarning: \n",
      "    toVerilog(): Deprecated usage: See http://dev.myhdl.org/meps/mep-114.html\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "=== simpler_ram ===\n",
      "\n",
      "   Number of wires:                  6\n",
      "   Number of wire bits:             42\n",
      "   Number of public wires:           5\n",
      "   Number of public wire bits:      26\n",
      "   Number of memories:               0\n",
      "   Number of memory bits:            0\n",
      "   Number of processes:              0\n",
      "   Number of cells:                  1\n",
      "     SB_RAM40_4K                     1\n"
     ]
    }
   ],
   "source": [
    "@chunk\n",
    "def simpler_ram(clk_i,wr_i, addr_i, data_i, data_o):\n",
    "    '''\n",
    "    Inputs:\n",
    "      clk_i:  Data is read/written on the rising edge of this clock input.\n",
    "      wr_i:   When high, data is written to the RAM; when low, data is read from the RAM.\n",
    "      addr_i: Address bus for selecting which RAM location is being read/written.\n",
    "      data_i: Data bus for writing data into the RAM.\n",
    "    Outputs:\n",
    "      data_o: Data bus for reading data from the RAM.\n",
    "    '''\n",
    "    \n",
    "    mem = [Bus(len(data_i)) for _ in range(2**len(addr_i))]\n",
    "    \n",
    "    @seq_logic(clk_i.posedge)\n",
    "    def logic():\n",
    "        if wr_i:\n",
    "            mem[addr_i.val].next = data_i\n",
    "        data_o.next = mem[addr_i.val]  # RAM address is always read out!\n",
    "                \n",
    "toVerilog(simpler_ram, clk_i=Wire(), wr_i=Wire(), addr_i=Bus(8), data_i=Bus(8), data_o=Bus(8))\n",
    "\n",
    "log = !yosys -p \"synth_ice40\" simpler_ram.v\n",
    "print_stats(log)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This reduces the resource usage by a single LUT:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The iCE40 BRAMs even allow a *dual-port* mode:\n",
    "a value can be written to one address while data is read from a second, independent address.\n",
    "(This is useful for building things like\n",
    "[FIFOs](https://en.wikipedia.org/wiki/FIFO_%28computing_and_electronics%29#Electronics).)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@chunk\n",
    "def dualport_ram(clk_i, wr_i, wr_addr_i, rd_addr_i, data_i, data_o):\n",
    "    '''\n",
    "    Inputs:\n",
    "      clk_i:     Data is read/written on the rising edge of this clock input.\n",
    "      wr_i:      When high, data is written to the RAM; when low, data is read from the RAM.\n",
    "      wr_addr_i: Address bus for selecting which RAM location is being written.\n",
    "      rd_addr_i: Address bus for selecting which RAM location is being read.\n",
    "      data_i:    Data bus for writing data into the RAM.\n",
    "    Outputs:\n",
    "      data_o:    Data bus for reading data from the RAM.\n",
    "    '''\n",
    "    \n",
    "    mem = [Bus(len(data_i)) for _ in range(2**len(wr_addr_i))]\n",
    "    \n",
    "    @seq_logic(clk_i.posedge)\n",
    "    def logic():\n",
    "        if wr_i:\n",
    "            mem[wr_addr_i.val].next = data_i\n",
    "        data_o.next = mem[rd_addr_i.val]  # Read from a different location than write."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I'll run a simulation of the dual-port RAM similar to the one I did above,\n",
    "but here I'll start reading from the RAM before I finish writing data to it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  Time    clk    wr    wr_addr    data_i    rd_addr    data_o\n",
      "------  -----  ----  ---------  --------  ---------  --------\n",
      "     0      0     1          0         1        253         0\n",
      "     1      1     1          0         1        253         0\n",
      "     2      0     1          1         4        254         0\n",
      "     3      1     1          1         4        254         0\n",
      "     4      0     1          2         7        255         0\n",
      "     5      1     1          2         7        255         0\n",
      "     6      0     1          3        10          0         0\n",
      "     7      1     1          3        10          0         1\n",
      "     8      0     1          4        13          1         1\n",
      "     9      1     1          4        13          1         4\n",
      "    10      0     1          5        16          2         4\n",
      "    11      1     1          5        16          2         7\n",
      "    12      0     1          6        19          3         7\n",
      "    13      1     1          6        19          3        10\n",
      "    14      0     1          7        22          4        10\n",
      "    15      1     1          7        22          4        13\n",
      "    16      0     1          8        25          5        13\n",
      "    17      1     1          8        25          5        16\n",
      "    18      0     1          9        28          6        16\n",
      "    19      1     1          9        28          6        19\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "<class 'myhdl.StopSimulation'>: No more events\n"
     ]
    }
   ],
   "source": [
    "initialize()\n",
    "\n",
    "# Create wires and buses to connect to the dual-port RAM.\n",
    "clk = Wire(name='clk')\n",
    "wr = Wire(name='wr')\n",
    "wr_addr = Bus(8, name='wr_addr')  # Address bus for writes.\n",
    "rd_addr = Bus(8, name='rd_addr')  # Second address bus for reads.\n",
    "data_i = Bus(8, name='data_i')\n",
    "data_o = Bus(8, name='data_o')\n",
    "\n",
    "# Instantiate the RAM.\n",
    "dualport_ram(clk_i=clk, wr_i=wr, wr_addr_i=wr_addr, rd_addr_i=rd_addr, data_i=data_i, data_o=data_o)\n",
    "\n",
    "def ram_test_bench():\n",
    "    for i in range(10):  # Perform 10 RAM writes and reads.\n",
    "        \n",
    "        # Write data to address i.\n",
    "        wr_addr.next = i\n",
    "        data_i.next = 3 * i + 1\n",
    "        wr.next = 1\n",
    "        \n",
    "        # Read data from address i-3. After three clocks, the data that entered\n",
    "        # on the data_i bus will start to appear on the data_o bus.\n",
    "        rd_addr.next = i - 3\n",
    "        \n",
    "        # Pulse the clock to trigger the write and read operations.\n",
    "        clk.next = 0\n",
    "        yield delay(1)\n",
    "        clk.next = 1\n",
    "        yield delay(1)\n",
    "\n",
    "# Simulate the RAM using the test bench.\n",
    "simulate(ram_test_bench())\n",
    "\n",
    "# Look at the RAM inputs and outputs as the simulation was executed.\n",
    "show_text_table('clk wr wr_addr data_i rd_addr data_o')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the simulation output, you can see the value that entered the RAM through the `data_i` bus\n",
    "on the rising clock edge at time $t$ then exited on the `data_o` bus three clock cycles\n",
    "later at time $t + 6$.\n",
    "In this example, the dual-port RAM is acting as a simple [delay line](https://en.wikipedia.org/wiki/Digital_delay_line)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Skinny RAM, Fat RAM"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the previous section, I built a 256-byte RAM. Is that it? Is that *all* you can do with the block RAM?\n",
    "\n",
    "Obviously not or else why would I even bring this up?\n",
    "Since block RAMs first appeared in FPGAs, the designers have allowed you to select the width of\n",
    "the data locations.\n",
    "While the number of data bits in the RAM is constant, you can clump them into different\n",
    "word sizes.\n",
    "Naturally, you'll get more addressable RAM locations if you use a narrow word width (\"skinny\" RAM)\n",
    "as compared to using wider words (\"fat\" RAM).\n",
    "Here are the allowable widths and the corresponding number of addressable locations \n",
    "for the 4K BRAMs in the iCE40 FPGA:\n",
    "\n",
    "| Data Width | # of Locations | Address Width |\n",
    "|:----------:|---------------:|:-------------:|\n",
    "| 2          | 2048           | 11            |\n",
    "| 4          | 1024           | 10            |\n",
    "| 8          | 512            |  9            |\n",
    "| 16         | 256            |  8            |\n",
    "\n",
    "So how do you set the RAM width?\n",
    "Easy, just set the number of data bus bits and Yosys will select the smallest\n",
    "width that will hold it.\n",
    "For example, specifying a data width of seven bits will make Yosys choose a BRAM width of eight bits.\n",
    "Of course, that means you'll waste one bit of every memory location, but *c'est la vie*.\n",
    "\n",
    "Specifying the number of addressable locations in the RAM is done similarly by setting the\n",
    "width of the address bus.\n",
    "To illustrate, an eleven-bit address bus would translate to $2^{11} =$ 2048 addressable locations.\n",
    "\n",
    "Let's try some various word and address widths and see what Yosys does with them.\n",
    "First, here's a RAM with 512 ($2^9$) ten-bit words:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "c:\\python35-32\\lib\\site-packages\\ipykernel_launcher.py:1: UserWarning: \n",
      "    toVerilog(): Deprecated usage: See http://dev.myhdl.org/meps/mep-114.html\n",
      "  \"\"\"Entry point for launching an IPython kernel.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "=== ram ===\n",
      "\n",
      "   Number of wires:                  9\n",
      "   Number of wire bits:             72\n",
      "   Number of public wires:           5\n",
      "   Number of public wire bits:      31\n",
      "   Number of memories:               0\n",
      "   Number of memory bits:            0\n",
      "   Number of processes:              0\n",
      "   Number of cells:                  3\n",
      "     SB_LUT4                         1\n",
      "     SB_RAM40_4K                     2\n"
     ]
    }
   ],
   "source": [
    "toVerilog(ram, clk_i=Wire(), wr_i=Wire(), addr_i=Bus(9), data_i=Bus(10), data_o=Bus(10))\n",
    "log = !yosys -p \"synth_ice40\" ram.v\n",
    "print_stats(log)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Two BRAMs are used because a data width of sixteen bits is needed to hold the ten-bit words and a single 4K&nbsp;BRAM\n",
    "can only hold 256 of those.\n",
    "\n",
    "What about a wide RAM with 128 ($2^7$) 24-bit words? That requires 3072 total bits so you would think that should fit\n",
    "into a single 4K BRAM, right?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "c:\\python35-32\\lib\\site-packages\\ipykernel_launcher.py:1: UserWarning: \n",
      "    toVerilog(): Deprecated usage: See http://dev.myhdl.org/meps/mep-114.html\n",
      "  \"\"\"Entry point for launching an IPython kernel.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "=== ram ===\n",
      "\n",
      "   Number of wires:                  7\n",
      "   Number of wire bits:             74\n",
      "   Number of public wires:           5\n",
      "   Number of public wire bits:      57\n",
      "   Number of memories:               0\n",
      "   Number of memory bits:            0\n",
      "   Number of processes:              0\n",
      "   Number of cells:                  3\n",
      "     SB_LUT4                         1\n",
      "     SB_RAM40_4K                     2\n"
     ]
    }
   ],
   "source": [
    "toVerilog(ram, clk_i=Wire(), wr_i=Wire(), addr_i=Bus(7), data_i=Bus(24), data_o=Bus(24))\n",
    "log = !yosys -p \"synth_ice40\" ram.v\n",
    "print_stats(log)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since the maximum width of a single BRAM is sixteen bits,\n",
    "Yosys employs *two* BRAMs in parallel to get the entire 24-bit word width and then only uses half the\n",
    "addressable locations in each BRAM.\n",
    "Thus, a total of 8192 bits of BRAM is used to store the 3072 bits that were requested.\n",
    "\n",
    "How about a 24-bit wide RAM with 512 words?\n",
    "That's 4$\\times$ bigger than the previous one, so will it take 4$\\times$ the number of BRAMs?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "c:\\python35-32\\lib\\site-packages\\ipykernel_launcher.py:1: UserWarning: \n",
      "    toVerilog(): Deprecated usage: See http://dev.myhdl.org/meps/mep-114.html\n",
      "  \"\"\"Entry point for launching an IPython kernel.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "=== ram ===\n",
      "\n",
      "   Number of wires:                  9\n",
      "   Number of wire bits:            108\n",
      "   Number of public wires:           5\n",
      "   Number of public wire bits:      59\n",
      "   Number of memories:               0\n",
      "   Number of memory bits:            0\n",
      "   Number of processes:              0\n",
      "   Number of cells:                  4\n",
      "     SB_LUT4                         1\n",
      "     SB_RAM40_4K                     3\n"
     ]
    }
   ],
   "source": [
    "toVerilog(ram, clk_i=Wire(), wr_i=Wire(), addr_i=Bus(9), data_i=Bus(24), data_o=Bus(24))\n",
    "log = !yosys -p \"synth_ice40\" ram.v\n",
    "print_stats(log)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Actually, it only takes *three* BRAMs instead of eight.\n",
    "Why is that?\n",
    "Because Yosys was able to stack two 256$\\times$16 BRAMs to create a 512$\\times$16 RAM, and then\n",
    "put this in parallel with a single 512$\\times$8 BRAM to create a total 512$\\times$24 RAM.\n",
    "\n",
    "From these examples, you can see the efficiency with which you use BRAM resources\n",
    "is very dependent upon the RAM aspect-ratio (#locations $\\times$ data width) that you specify,\n",
    "sometimes in unexpected ways."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Demo Time!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As I've said before, it would be a shame to do all this work and then not do something fun with it.\n",
    "So I'll show how to use a BRAM to record an on-off sequence of button presses and then play\n",
    "it back by lighting the iCEstick LEDs.\n",
    "(OK, maybe it's not *that* fun.)\n",
    "\n",
    "Here's the basics of how the circuit operates:\n",
    "\n",
    "1. When button A is pressed and released, set the RAM address to 0 and start recording.\n",
    "2. Every 0.01 seconds, sample the on-off value of button B, store it in RAM at the current address,\n",
    "   and increment the address.\n",
    "3. If button A is not pressed, return to step 2 and take another sample.\n",
    "   Otherwise, store the current address to mark the end of the recording,\n",
    "   and halt here until button A is released.\n",
    "4. When button A is released, reset the address to 0 (the start of the recording).\n",
    "6. Every 0.01 seconds, read a button sample from the RAM and turn an LED on or off depending upon its value.\n",
    "7. If the current address equals the end-of-recording address, reset the address to the beginning of the recording (address 0).\n",
    "   Otherwise, increment the current address.\n",
    "8. If button A is not pressed, return to step 5 and display another sample.\n",
    "   Otherwise, loop back to step 1 and to start a new recording.\n",
    "   \n",
    "The iCEstick board already had the LEDs I needed, but no buttons.\n",
    "To fix that, I wired some external buttons to the board as shown in this schematic:\n",
    "\n",
    "<img src=\"record_play_circuit.png\" alt=\"Record/playback schematic.\" width=\"600px\" />\n",
    "\n",
    "Next, I broke the record/playback logic into four pieces:\n",
    "\n",
    "1. A RAM for storing the button samples (already coded above).\n",
    "2. A counter that generates a *sampling pulse* every 0.01 seconds.\n",
    "3. A controller that manages the recording/playback process.\n",
    "4. A reset circuit that generates a single pulse to initialize the controller's state.\n",
    "\n",
    "The MyHDL code for the circuit is shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@chunk\n",
    "def gen_reset(clk_i, reset_o):\n",
    "    '''\n",
    "    Generate a reset pulse to initialize everything.\n",
    "    Inputs:\n",
    "        clk_i:   Input clock.\n",
    "    Outputs:\n",
    "        reset_o: Active-high reset pulse.\n",
    "    '''\n",
    "    cntr = Bus(1)  # Reset counter.\n",
    "    \n",
    "    @seq_logic(clk_i.posedge)\n",
    "    def logic():\n",
    "        if cntr < 1:\n",
    "            # Generate a reset while the counter is less than some threshold\n",
    "            # and increment the counter.\n",
    "            cntr.next = cntr.next + 1\n",
    "            reset_o.next = 1\n",
    "        else:\n",
    "            # Release the reset once the counter passes the threshold and\n",
    "            # stop incrementing the counter.\n",
    "            reset_o.next = 0\n",
    "\n",
    "@chunk\n",
    "def sample_en(clk_i, do_sample_o, frq_in=12e6, frq_sample=100):\n",
    "    '''\n",
    "    Send out a pulse every so often to trigger a sampling operation.\n",
    "    Inputs:\n",
    "        clk_i:      Input clock.\n",
    "        frq_in:     Frequency of the input clock (defaults to 12 MHz).\n",
    "        frq_sample: Frequency of the sample clock (defaults to 100 Hz).\n",
    "    Outputs:\n",
    "        do_sample_o: Sends out a single-cycle pulse every 1/frq_sample seconds.\n",
    "    '''\n",
    "    # Compute the width of the counter and when it should roll-over based\n",
    "    # on the master clock frequency and the desired sampling frequency.\n",
    "    from math import ceil, log2\n",
    "    rollover = int(ceil(frq_in / frq_sample)) - 1\n",
    "    cntr = Bus(int(ceil(log2(frq_in/frq_sample))))\n",
    "    \n",
    "    # Sequential logic for generating the sampling pulse.\n",
    "    @seq_logic(clk_i.posedge)\n",
    "    def counter():\n",
    "        cntr.next = cntr + 1         # Increment the counter.\n",
    "        do_sample_o.next = 0         # Clear the sampling pulse output except...\n",
    "        if cntr == rollover:\n",
    "            do_sample_o.next = 1     # ...when the counter rolls over.\n",
    "            cntr.next = 0 \n",
    "\n",
    "@chunk\n",
    "def record_play(clk_i, button_a, button_b, leds_o):\n",
    "    '''\n",
    "    Sample value on button B input, store in RAM, and playback by turning LEDs on/off.\n",
    "    Inputs:\n",
    "        clk_i:    Clock input.\n",
    "        button_a: Button A input. High when pressed. Controls record/play operation.\n",
    "        button_b: Button B input. High when pressed. Used to input samples for controlling LEDs.\n",
    "    Outputs:\n",
    "        leds_o:   LED outputs.\n",
    "    '''\n",
    "    \n",
    "    # Instantiate the reset generator.\n",
    "    reset = Wire()\n",
    "    gen_reset(clk_i, reset)\n",
    "    \n",
    "    # Instantiate the sampling pulse generator.\n",
    "    do_sample = Wire()\n",
    "    sample_en(clk_i, do_sample)\n",
    "    \n",
    "    # Instantiate a RAM for holding the samples.\n",
    "    wr = Wire()\n",
    "    addr = Bus(11)\n",
    "    end_addr = Bus(len(addr)) # Holds the last address of the recorded samples.\n",
    "    data_i = Bus(1)\n",
    "    data_o = Bus(1)\n",
    "    ram(clk_i, wr, addr, data_i, data_o)\n",
    "    \n",
    "    # States of the record/playback controller.\n",
    "    state = Bus(3)         # Holds the current state of the controller.\n",
    "    INIT = 0               # Initialize. The reset pulse sends us here.\n",
    "    WAITING_TO_RECORD = 1  # Getting read to record samples.\n",
    "    RECORDING = 2          # Actually storing samples in RAM.\n",
    "    WAITING_TO_PLAY = 3    # Getting ready to play back samples.\n",
    "    PLAYING = 4            # Actually playing back samples.\n",
    "\n",
    "    # Sequential logic for the record/playback controller.\n",
    "    @seq_logic(clk_i.posedge)\n",
    "    def fsm():\n",
    "        \n",
    "        wr.next = 0        # Keep the RAM write-control off by default.\n",
    "        \n",
    "        if reset:  # Initialize the controller using the pulse from the reset generator.\n",
    "            state.next = INIT  # Go to the INIT state after the reset is released.\n",
    "            \n",
    "        elif do_sample:  # Process a sample whenever the sampling pulse arrives.\n",
    "        \n",
    "            if state == INIT:  # Initialize the controller.\n",
    "                leds_o.next = 0b10101  # Light LEDs to indicate the INIT state.\n",
    "                if button_a == 1:\n",
    "                    # Get ready to start recording when button A is pressed.\n",
    "                    state.next = WAITING_TO_RECORD  # Go to record setup state.\n",
    "                    \n",
    "            elif state == WAITING_TO_RECORD:  # Setup for recording.\n",
    "                leds_o.next = 0b11010  # Light LEDs to indicate this state.\n",
    "                if button_a == 0:\n",
    "                    # Start recording once button A is released.\n",
    "                    addr.next = 0           # Start recording from beginning of RAM.\n",
    "                    data_i.next = button_b  # Record the state of button B.\n",
    "                    wr.next = 1             # Write button B state to RAM.\n",
    "                    state.next = RECORDING  # Go to recording state.\n",
    "                    \n",
    "            elif state == RECORDING:  # Record samples of button B to RAM.\n",
    "                addr.next = addr + 1    # Next location for storing sample.\n",
    "                data_i.next = button_b  # Sample state of button B.\n",
    "                wr.next = 1             # Write button B state to RAM.\n",
    "                # For feedback to the user, display the state of button B on the LEDs.\n",
    "                leds_o.next = concat(1,button_b, button_b, button_b, button_b)\n",
    "                if button_a == 1:\n",
    "                    # If button A pressed, then get ready to play back the stored samples.\n",
    "                    end_addr.next = addr+1  # Store the last sample address.\n",
    "                    state.next = WAITING_TO_PLAY  # Go to playback setup state.\n",
    "                    \n",
    "            elif state == WAITING_TO_PLAY:  # Setup for playback.\n",
    "                leds_o.next = 0b10000  # Light LEDs to indicate this state.\n",
    "                if button_a == 0:\n",
    "                    # Start playback once button A is released.\n",
    "                    addr.next = 0         # Start playback from beginning of RAM.\n",
    "                    state.next = PLAYING  # Go to playback state.\n",
    "                    \n",
    "            elif state == PLAYING:  # Show recorded state of button B on the LEDs.\n",
    "                leds_o.next = concat(1,data_o[0],data_o[0],data_o[0],data_o[0])\n",
    "                addr.next = addr + 1  # Advance to the next sample.\n",
    "                if addr == end_addr:\n",
    "                    # Loop back to the start of RAM if this is the last sample.\n",
    "                    addr.next = 0\n",
    "                if button_a == 1:\n",
    "                    # Record a new sample if button A is pressed.\n",
    "                    state.next = WAITING_TO_RECORD"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After converting the MyHDL to Verilog, I wrote the pin assignments for the LEDs and buttons to a file.\n",
    "I'm using all five LEDs on the iCEstick along with the\n",
    "two pushbuttons I connected to pins 114 and 118 of the FPGA through the iCEstick I/O header."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "c:\\python35-32\\lib\\site-packages\\ipykernel_launcher.py:1: UserWarning: \n",
      "    toVerilog(): Deprecated usage: See http://dev.myhdl.org/meps/mep-114.html\n",
      "  \"\"\"Entry point for launching an IPython kernel.\n"
     ]
    }
   ],
   "source": [
    "toVerilog(record_play, clk_i=Wire(), button_a=Wire(), button_b=Wire(), leds_o=Bus(5))\n",
    "\n",
    "with open('record_play.pcf', 'w') as pcf:\n",
    "    pcf.write(\n",
    "'''\n",
    "set_io clk_i 21\n",
    "set_io leds_o[0] 99\n",
    "set_io leds_o[1] 98\n",
    "set_io leds_o[2] 97\n",
    "set_io leds_o[3] 96\n",
    "set_io leds_o[4] 95\n",
    "set_io button_a 118\n",
    "set_io button_b 114\n",
    "'''\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, I synthesized, compiled, and downloaded the FPGA bitstream using the\n",
    "(by now) familiar sequence of commands:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "init..\n",
      "cdone: high\n",
      "reset..\n",
      "cdone: low\n",
      "flash ID: 0x20 0xBA 0x16 0x10 0x00 0x00 0x23 0x12 0x67 0x21 0x13 0x00 0x49 0x00 0x34 0x04 0x11 0x11 0x20 0x31\n",
      "file size: 32220\n",
      "erase 64kB sector at 0x000000..\n",
      "programming..\n",
      "reading..\n",
      "VERIFY OK\n",
      "cdone: high\n",
      "Bye.\n"
     ]
    }
   ],
   "source": [
    "!yosys -q -p \"synth_ice40 -blif record_play.blif\" record_play.v\n",
    "!arachne-pnr -q -d 1k -p record_play.pcf record_play.blif -o record_play.asc\n",
    "!icepack record_play.asc record_play.bin\n",
    "!iceprog record_play.bin"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once the bitstream was downloaded, I could store and playback a sequence of button pushes.\n",
    "It's difficult to describe using text or images, so here's a nice video of how it works:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"padding-bottom:50.000%;\"><iframe src=\"https://streamable.com/s/ihqg4/eqmlzq\" frameborder=\"0\" width=\"100%\" height=\"100%\" allowfullscreen style=\"width:640px;position:absolute;\"></iframe></div>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "HTML('<div style=\"padding-bottom:50.000%;\"><iframe src=\"https://streamable.com/s/ihqg4/eqmlzq\" frameborder=\"0\" width=\"100%\" height=\"100%\" allowfullscreen style=\"width:640px;position:absolute;\"></iframe></div>')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "Once again, you've made it to the end of another ~~beating~~ tutorial.\n",
    "While battle-scarred and weary, your labors have earned you these treasures:\n",
    "\n",
    "* How to write MyHDL that Yosys can recognize as a block RAM.\n",
    "\n",
    "* How to read from and write to a RAM.\n",
    "\n",
    "* How to create RAMs with various word widths and number of memory locations.\n",
    "\n",
    "* How RAMs of different sizes are mapped into the fixed-size iCE40 BRAMs."
   ]
  }
 ],
 "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.5.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}