moved architecture documentation to new file

jupyter_example.ipynb

@@ -70,7 +70,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 39,
+   "execution_count": 30,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -87,7 +87,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 40,
+   "execution_count": 31,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -104,16 +104,16 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 41,
+   "execution_count": 35,
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "256"
+       "0"
       ]
      },
-     "execution_count": 41,
+     "execution_count": 35,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -135,7 +135,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 23,
+   "execution_count": 33,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -177,7 +177,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now open the file \"OpenFPGA/tutorial/example_arch.xml\" in a text editor. Go to line 51 and change:\n",
+    "Now open the file \"OpenFPGA/tutorial/example_arch.xml\" in a text editor. Go to line 5 and change:\n",
     "\n",
     "<pb_type name=\"io\" capacity=\"1\">\n",
     "\n",
@@ -221,52 +221,109 @@
     "The simple change to the number of inputs or outputs per I/O block let the placement and routing tool use less space on the FPGA for the circuit."
    ]
   },
+  
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# The Architecture format\n",
+    "# Changing the Architecture\n",
-    "An FPGA architecture is specified in an XML file and is wrapped in an `<architecture>` tag. `example_arch.xml` defines a simple FPGA.\n",
+    "We'll make some changes to the architecture file and see how the output changes. To begin, set up the location of the vpr executable, the input files, and the vpr options. Then run the tool:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 45,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "0"
+      ]
+     },
+     "execution_count": 45,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# set this to the location of the vpr executable file\n",
+    "vpr = \"~/vtr-verilog-to-routing/vpr/vpr\"\n",
+    "arch = \"~/OpenFPGA/tutorial/v8_example_arch.xml\"\n",
+    "circuit = \"~/OpenFPGA/tutorial/example_circuit.blif\"\n",
+    "# turn on the graphic display\n",
+    "options = \"--disp on\"\n",
+    "# set up the command line\n",
+    "command_line = vpr + \" \" + arch + \" \" + circuit + \" \" + options\n",
     "\n",
-    "Line 18 has the `<models>` tag which would describe `BLIF` circuit model names that the FPGA accepts. This architecture is simple enough to not need any additional models beyond the default `.names .latch .input .output`.\n",
+    "import os\n",
-    "\n",
+    "os.system(command_line)\n"
-    "## Layout and Routing\n",
-    "\n",
-    "Line 23 has the `<layout>` tag which specifies how the FPGA grid will be laid out. For this example: `<layout auto=\"1.000000\"/>` specifies an automatic grid with an aspect ratio of 1.0. A specific width and heigh could be specified instead of the automatic layout. Th rest of the `<layout>` section specifies that the perimeter will hav `io` blocks, the corners will be `EMPTY` and the rest of the FPGA will be filled with `clb` blocks. `io` and `clb` blocks are defined in the `<complexblocklist>` section.\n",
-    "\n",
-    "Line 32 begins the `<device>` tag which characterizes the transistors and connections of the FPGA. `<sizing>` specifies the resistance of the minimum-width nmos and pmos transistors. `<area grid_logic_tile_area>` is used as an estimate of the size of one grid tile.\n",
-    "\n",
-    "Line 35 the `<chan_width_distr>` section sets the relative widths of the routing channels in various parts of the FPGA. Here, all channels are set to be distributed uniformly. Distribution options are `gaussian`, `pulse`, or `delta`.\n",
-    "\n",
-    "Line 42 is the `<switchlist>` section which specifies the switches used to connect wires and pins together. Resistance, in/out capacitance, delay through the switch, and component size.\n",
-    "\n",
-    "## redo segmentlist\n"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Line 55 begins the `<complexblocklist>` section which is where the I/O and logic blocks are defined.\n",
+    "That will bring up a display of the FPGA and how the circuit was laid out. Press `Proceed` twice to step through the complete tool cycle, or just press `Exit` to quit.\n",
     "\n",
-    "# Skip I/O for now...\n",
+    "You can see that there are I/O blocks around the perimeter of the layout and a 2x2 grid of complex logic blocks (clb) in the center. Currently, each I/O block only allows for one connection in or out. Our circuit `example_circuit.blif` specifies 3 inputs and 4 outputs, so we should be able to reduce the number of I/O blocks by enabling more that one input or output on each block.\n",
     "\n",
-    "\n",
+    "Open the architecture file `~/OpenFPGA/tutorial/v8_example_arch.xml`, go to line 58 and change `capacity=1` to `capacity=3`. Run the tool again."
-    "## Logic Blocks\n",
-    "\n",
-    "Line 115 is where the general purpuse *complex logic block* or *clb* definition begins. `<pb_type>` is the tag to define a physical block on the FPGA. Next, the inputs and outputs to the block are defined; here there are 10 inputs, 4 outputs, and 1 clock input. The inputs and outputs have `equivalent=true` attributes, which means that they are logically equivalent and so order doesn't matter when routing.\n",
-    "\n",
-    "Line 121 defines the *basic logic element* or *BLE* that makes up the clb. The `<pb_type name=\"fle\" num_pb=\"4\">` attribute indicates that 4 of these BLEs called `fle` are contained in the surrounding `clb`. The next lines define 4 inputs, one output, and one clock line.\n",
-    "\n",
-    "Skipping down to line 134, the core lookup-table of the BLE is defined: `<pb_type name=\"lut4\" blif_model=\".names\" num_pb=\"1\" class=\"lut\">`.  This indicates 1 lookup-table named `lut4`; `.names` is the BLIF keyword for lookup-table. The next two lines show 4 inputs and 1 output to the LUT. The `<delay_matrix>` attribute specifies the propogation delay through the LUT's inputs to output.\n",
-    "\n",
-    "Line 147 defines the flip-flop in the BLE: `<pb_type name=\"ff\" blif_model=\".latch\" num_pb=\"1\" class=\"flipflop\">`: 1 flip-flop named `ff`; `.latch` is the BLIF keyword for flip-flop. The next lines specify the I/Os and timing parameters.\n",
-    "\n",
-    "Skipping back up to line 126, a mode named `n1_lut4` for the block named `fle` is defined. A block can have multiple modes specified, but a block can only use one mode at a time. This particular block only defines one mode. The mode defines a block on line 128 named `ble4` which contains the LUT `lut4` and flip-flop `ff`.\n",
-    "\n",
-    "Moving back down to line 155, `<interconnect>` indicates how the blocks are connected. The `<direct>` element means to simply wire the nets together. Line 156 wires the input of `ble4` to the input of `lut4`, line 157 wires the output of `lut4` to the D-input of `ff`. Line 161 wires the clk inputs together. Line 162 defines a mux to set the output of `ble4` to be either the direct output of `lut4` or the latched output of `ff`."
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "os.system(command_line)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now the I/O blocks around the perimeter have 3 slots for an input or 3 slots for an output. \n",
+    "\n",
+    "Currently, the architecture only has one basic logic element (ble) in each clb. Let's change the architecture to put four bles in a clb. Go to line 111 and change `<output name=\"O\" num_pins=\"1\"/>` to `<output name=\"O\" num_pins=\"4\"/>`. That will change the number of ouput pins in the clb.\n",
+    "\n",
+    "At line 117 change `<pb_type name=\"ble4\" num_pb=\"1\">` to `<pb_type name=\"ble4\" num_pb=\"4\">`. That puts 4 bles in the clb. Note that the ble is named `ble4` and continue to the `<interconnect>` section on lines 162-168.\n",
+    "\n",
+    "In the `<interconnect>` on lines 161-167 change all instances of `ble4[0:0]` to `ble4[3:0]`. That wires up all four of the bles inside the clb.\n",
+    "\n",
+    "Run the tool again."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 42,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "0"
+      ]
+     },
+     "execution_count": 42,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "import os\n",
+    "os.system(command_line)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
   {
    "cell_type": "code",
    "execution_count": null,