doc/verilog_integration.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "lines_to_next_cell": 0
   },
   "source": [
    "# Integration with External Verilog\n",
    "This guide is targeted towards users working with existing Verilog designs (as\n",
    "opposed to Python/Magma circuits).\n",
    "\n",
    "The approach relies on Magma's external Verilog integration features to\n",
    "construct a Magma circuit representation that can then be used with a\n",
    "`fault.Tester` object. This approach enables the use of most of fault's\n",
    "features, except for logic that relies on descending into a design hierarchy\n",
    "(e.g. peeking and poking sub-instance ports).\n",
    "\n",
    "The first, simplest approach is to use `m.define_from_verilog` (which\n",
    "takes a string containing verilog code) or\n",
    "`m.define_from_verilog_file` (which takes a path to a file that contains verilog code)\n",
    "to import a verilog design into Magma.  \n",
    "\n",
    "Here's an example using `m.define_from_verilog`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Imported as magma circuit: foo(I: In(Bit), O: Out(Bit))\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:root:Running tester...\n",
      "INFO:root:Success!\n"
     ]
    }
   ],
   "source": [
    "import magma as m\n",
    "import logging\n",
    "logging.basicConfig(level=logging.INFO)\n",
    "import fault\n",
    "\n",
    "# NOTE: define_from_verilog returns a list of modules \n",
    "# (since there could be multiple), so in this case we \n",
    "# simply index the first and only module with `[0]`\n",
    "foo = m.define_from_verilog(\"\"\"\\\n",
    "module foo(input I, output O);\n",
    "assign O = I;\n",
    "endmodule\n",
    "\"\"\", target_modules=[\"foo\"])[0]\n",
    "\n",
    "print(f\"Imported as magma circuit: {foo}\")\n",
    "\n",
    "tester = fault.Tester(foo)\n",
    "tester.circuit.I = 1\n",
    "tester.eval()\n",
    "tester.circuit.O.expect(1)\n",
    "tester.compile_and_run(\"verilator\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's an example using `m.define_from_verilog_file`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Imported as magma circuit: foo(I: In(Bit), O: Out(Bit))\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:root:Running tester...\n",
      "INFO:root:Success!\n"
     ]
    }
   ],
   "source": [
    "# write verilog string to a file\n",
    "with open(\"foo.v\", \"w\") as f:\n",
    "    f.write(\"\"\"\\\n",
    "module foo(input I, output O);\n",
    "assign O = I;\n",
    "endmodule\n",
    "\"\"\")\n",
    "    \n",
    "foo = m.define_from_verilog_file(\"foo.v\", target_modules=[\"foo\"])[0]\n",
    "print(f\"Imported as magma circuit: {foo}\")\n",
    "\n",
    "tester = fault.Tester(foo)\n",
    "tester.circuit.I = 1\n",
    "tester.eval()\n",
    "tester.circuit.O.expect(1)\n",
    "tester.compile_and_run(\"verilator\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An alternative to using `define_from_verilog` is to use `declare_from_verilog` to import a module interface, and provide the implementation to the simulator by copying the source verilog file into the simulation directory.  This is useful when the source file contains code that is not supported by Magma's Verilog parser (e.g. advanced system verilog features), or when parsing takes a long time (e.g. a post-synthesis netlist file)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:root:Running tester...\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Imported as magma circuit: foo(I: In(Bit), O: Out(Bit))\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:root:Success!\n"
     ]
    }
   ],
   "source": [
    "with open(\"foo_stub.v\", \"w\") as f:\n",
    "    f.write(\"\"\"\\\n",
    "module foo(input I, output O);\n",
    "endmodule\n",
    "\"\"\")\n",
    "\n",
    "# You can similarly use declare_from_verilog with a Verilog string\n",
    "foo = m.declare_from_verilog_file(\"foo_stub.v\", target_modules=[\"foo\"])[0]\n",
    "print(f\"Imported as magma circuit: {foo}\")\n",
    "\n",
    "\n",
    "tester = fault.Tester(foo)\n",
    "tester.circuit.I = 1\n",
    "tester.eval()\n",
    "tester.circuit.O.expect(1)\n",
    "\n",
    "import tempfile\n",
    "import shutil\n",
    "\n",
    "with tempfile.TemporaryDirectory() as dir_:\n",
    "    # Copy actual implementation to test directory\n",
    "    shutil.copy(\"foo.v\", dir_)\n",
    "    # Set test directory with directory= kwarg\n",
    "    # Note: we also tell magma to skip compilation (skip_compile=True)\n",
    "    # since the verilog file is already present in the test directory \n",
    "    # (copied in the previous line)\n",
    "    tester.compile_and_run(\"verilator\", directory=dir_, skip_compile=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A similar approach is to declare the interface using magma. This has the advantage of providing the capability of writing a sophisticated interface generator for your external module (e.g. if you're integrating with an external generator framework).  In doing this, you may find it useful to first define/declare a Circuit for the verilog module (as done above) and use the basic corresponding types.  Then, in a magma circuiat wrapper, you can use more complex types and wire them up to the underlying verilog ports."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:root:Running tester...\n",
      "INFO:root:Success!\n"
     ]
    }
   ],
   "source": [
    "# Declare magma circuit with the same name and equivalent interface\n",
    "# to a verilog circuit\n",
    "class foo(m.Circuit):\n",
    "    io = m.IO(I=m.In(m.Bit), O=m.Out(m.Bit))\n",
    "\n",
    "tester = fault.Tester(foo)\n",
    "tester.circuit.I = 1\n",
    "tester.eval()\n",
    "tester.circuit.O.expect(1)\n",
    "\n",
    "import tempfile\n",
    "import shutil\n",
    "\n",
    "with tempfile.TemporaryDirectory() as dir_:\n",
    "    # Copy actual implementation to test directory\n",
    "    shutil.copy(\"foo.v\", dir_)\n",
    "    # Set test directory with directory= kwarg\n",
    "    tester.compile_and_run(\"verilator\", directory=dir_, skip_compile=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "jupytext": {
   "cell_metadata_filter": "-all",
   "main_language": "python",
   "notebook_metadata_filter": "-all"
  },
  "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.8.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}