freechips/semicustom/semicustom-inverter.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "uINjDJNf39eD"
   },
   "source": [
    "# Semicustom digital design demo using OpenROAD\n",
    "\n",
    "## Sources\n",
    "\n",
    "### RTL description (Verilog)\n",
    "\n",
    "The OpenROAD workflow takes the circuit's RTL description as an input. For instance, it can be a three bits XOR gate.\n",
    "\n",
    "\n",
    "<blockquote><details>\n",
    "\n",
    "<summary>\n",
    "    \n",
    "#### ↕️ Types in Verilog\n",
    "\n",
    "</summary>\n",
    "    \n",
    "```verilog\n",
    "// Three scalar nets\n",
    "wire op_b, op_a, result;\n",
    "// One 16-bit net\n",
    "wire [15:0] word_bus;\n",
    "// 1K-array of 8-bit nets\n",
    "wire [7:0] byte_array [0:1023];\n",
    "```\n",
    "    \n",
    "</details></blockquote>\n",
    "\n",
    "<blockquote><details>\n",
    "\n",
    "<summary>\n",
    "    \n",
    "#### ↕️ Assignation (non-blocking) in Verilog\n",
    "\n",
    "</summary>\n",
    "    \n",
    "```verilog\n",
    "// 16-bit, hexadecimal constant\n",
    "assign address = 16'hCAFE;\n",
    "// Unsized, decimal constant\n",
    "assign counter = 'd42;\n",
    "// 1-bit, binary constant\n",
    "assign answer = 1'b1;\n",
    "\n",
    "// Ternary assignation\n",
    "assign muxed = which ? source_1 : source_2;\n",
    "\n",
    "// Concatenation\n",
    "assign padded_packet = {5'b00000,body,suffix};\n",
    "// Replication\n",
    "assign odd_mask = {10{2'b10}};\n",
    "\n",
    "// Indexing\n",
    "assign one_bit = bus[4];\n",
    "assign bits = bus[15:12];\n",
    "```\n",
    "    \n",
    "</details></blockquote>\n",
    "\n",
    "<blockquote><details>\n",
    "\n",
    "<summary>\n",
    "    \n",
    "#### ↕️ Operators in Verilog\n",
    "\n",
    "</summary>\n",
    "    \n",
    "```verilog\n",
    "// Addition, substraction, negation\n",
    "assign sum = op_a + op_b; assign sub = op_a + op_b; assign opp = -op_a\n",
    "// Multiplication, division, modulo\n",
    "assign prod = op_a * op_b; assign div = op_a / op_b; assign rem = op_a & op_b\n",
    "    \n",
    "// Bitwise not, or, and, xor\n",
    "assign n = ~m; assign a = b | c; assign d = e & f; assign x = y ^ z\n",
    "\n",
    "// Logical not, and, or\n",
    "assign ans = !v; assign ans = v || w; assign ans = v && w;\n",
    "// Logical equality, difference\n",
    "assign ans = v == w; assign ans = v != w;\n",
    "// Relations (strictly) greater, (strictly) lower than\n",
    "assign sg = a > b; assign gt = a >= b; assign sl = a < b; assign lt = a <= b;\n",
    "    \n",
    "// Left, right shift by n bits\n",
    "assign l << n; assign r >> n;\n",
    "// Left, right arithmetic shift by n bits\n",
    "assign l <<< n; assign r >>> n;\n",
    "```\n",
    "    \n",
    "</details></blockquote>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "id": "gpgkIYB739Ii"
   },
   "outputs": [],
   "source": [
    "%%writefile v/xor3.v\n",
    "module xor3(\n",
    "    input wire a,\n",
    "    input wire b,\n",
    "    input wire c,\n",
    "    output wire out\n",
    ");\n",
    "    assign out = a ^ b ^ c;\n",
    "endmodule"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "hp8h5vH8TUXr"
   },
   "source": [
    "### Configuration file (JSON)\n",
    "\n",
    "A configuration file should be provided. It describes constraints and strategies applied during synthesis and implementation of the circuit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "id": "rbT-vP0h0enK"
   },
   "outputs": [],
   "source": [
    "%%writefile config.json\n",
    "{\n",
    "    \"DESIGN_NAME\": \"xor3\",\n",
    "    \"VERILOG_FILES\": \"dir::v/xor3.v\",\n",
    "    \"CLOCK_TREE_SYNTH\": false,\n",
    "    \"CLOCK_PORT\": null,\n",
    "    \"PL_RANDOM_GLB_PLACEMENT\": true,\n",
    "    \"FP_SIZING\": \"absolute\",\n",
    "    \"DIE_AREA\": \"0 0 40 40\",\n",
    "    \"PL_TARGET_DENSITY\": 0.8,\n",
    "    \"FP_PDN_AUTO_ADJUST\": false,\n",
    "    \"FP_PDN_VPITCH\": 10,\n",
    "    \"FP_PDN_HPITCH\": 10,\n",
    "    \"FP_PDN_VOFFSET\": 5,\n",
    "    \"FP_PDN_HOFFSET\": 5,\n",
    "    \"DIODE_INSERTION_STRATEGY\": 3\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Workflow\n",
    "The provided `flow.tcl` is a script describing the OpenROAD workflow. A _GDS_ file will be generated using the RTL circuit description, the PDK and the configuration file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "VP60fdObiP15",
    "outputId": "41aa85e4-c663-4778-d448-928dbe474b11"
   },
   "outputs": [],
   "source": [
    "%env PDK=sky130A\n",
    "!flow.tcl -design ."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "luguFgZ43AeL"
   },
   "source": [
    "## Output products\n",
    "\n",
    "### Display layout\n",
    "\n",
    "The implemented layout can be retrieved as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 650
    },
    "id": "WOnhdtp3ivRi",
    "outputId": "b4bd26f8-d3da-47b7-e321-99272b0591ef",
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "import glob\n",
    "import gdstk\n",
    "import IPython.display\n",
    "\n",
    "gdsii = sorted(glob.glob(\"./runs/*/results/final/gds/*.gds\"))[-1]\n",
    "top = gdstk.read_gds(gdsii).top_level()\n",
    "top[0].write_svg('svg/inverter.svg')\n",
    "IPython.display.SVG('svg/inverter.svg')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "NW_7YdgTZYQK"
   },
   "source": [
    "### Reporting\n",
    "\n",
    "Many reports are available under:\n",
    "\n",
    "```\n",
    "freeechips/semicustom/runs/RUN_YYYY.MM.DD_HH.MM.SS/reports/.\n",
    "```\n",
    "\n",
    "An overview of the main figures can be retrieved as well:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 1000
    },
    "id": "OWAwQI3fZC4W",
    "outputId": "d50dcf9f-30cd-42a3-dab5-12992bc9dca2",
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "import glob\n",
    "import pandas as pd\n",
    "\n",
    "metrics = pd.read_csv(sorted(glob.glob(\"./runs/*/reports/metrics.csv\"))[-1])\n",
    "\n",
    "print(f\"tritonRoute_violations  {metrics['tritonRoute_violations'][0]}\")\n",
    "print(f\"Short_violations        {metrics['Short_violations'][0]}\")\n",
    "print(f\"OffGrid_violations      {metrics['OffGrid_violations'][0]}\")\n",
    "print(f\"MinHole_violations      {metrics['MinHole_violations'][0]}\")\n",
    "print(f\"Other_violations        {metrics['Other_violations'][0]}\")\n",
    "print(f\"Magic_violations        {metrics['Magic_violations'][0]}\")\n",
    "print(f\"pin_antenna_violations  {metrics['pin_antenna_violations'][0]}\")\n",
    "print(f\"net_antenna_violations  {metrics['net_antenna_violations'][0]}\")\n",
    "print(f\"lvs_total_errors        {metrics['lvs_total_errors'][0]}\")\n",
    "print(f\"cvc_total_errors        {metrics['cvc_total_errors'][0]}\")\n",
    "print(f\"klayout_violations      {metrics['klayout_violations'][0]}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# To have fun going further...\n",
    "\n",
    "## Sequential circuits in Verilog\n",
    "\n",
    "The tutorial above focuses on combinational circuits. Sequential circuits can obviously be described in Verilog as well. Sequential blocks feature an `always` block. Refer to the vendor's reference to get the sensitivity list's syntax (e.g. to determine if reset is synchronous or asynchronous).\n",
    "\n",
    "<blockquote><details>\n",
    "\n",
    "<summary>\n",
    "    \n",
    "#### ↕️ Sequential structures in Verilog\n",
    "\n",
    "</summary>\n",
    "\n",
    "```verilog\n",
    "always @(posedge clk or negedge rst) begin\n",
    "  if (rst) begin \n",
    "    counter <= 0;\n",
    "  end else begin\n",
    "    counter <= counter + 1;\n",
    "  end\n",
    "end\n",
    "```\n",
    "    \n",
    "</details></blockquote>\n",
    "\n",
    "Advanced structures like the `case` structure can be used to describe finite state machines. FSM decoders can be described in an abstract way using `always` blocks in a fully combinational way:\n",
    "\n",
    "<blockquote><details>\n",
    "\n",
    "<summary>\n",
    "    \n",
    "#### ↕️ Advanced structures in Verilog\n",
    "\n",
    "</summary>\n",
    "\n",
    "```verilog\n",
    "    \n",
    "/*\n",
    " *   Case structure\n",
    " */\n",
    "    \n",
    "case (state)\n",
    "\n",
    "  3'b000: idle_led <= 1'b1;\n",
    "  \n",
    "  3'b001,\n",
    "  3'b010: work_led <= 1'b1;\n",
    "  \n",
    "  3'b011: begin\n",
    "    muxed <= spi_1;\n",
    "    work_led <= 1'b1;\n",
    "  end\n",
    "  \n",
    "  default: begin\n",
    "    muxed <= 0;\n",
    "    work_led <= 1'b0; \n",
    "    idle_led <= 1'b1;\n",
    "  end\n",
    "\n",
    "endcase\n",
    "\n",
    "/*\n",
    " *   Combinational always structure\n",
    " *     To describe priorities in a procedural fashion,\n",
    " *     use blocking `<=` assignations instead of\n",
    " *     non-blocking `=` assignations.\n",
    " */\n",
    "                \n",
    "always @( * ) begin\n",
    "  flag <= 1'b0;\n",
    "  if (error) begin \n",
    "    flag <= 1'b1;\n",
    "  end\n",
    "end\n",
    "```\n",
    "\n",
    "</details></blockquote>\n",
    "\n",
    "## High-Level Synthesis (HLS)\n",
    "\n",
    "RTL description of circuits does not follow an imperative programming paradigm. It is a description language that produces highly parallelized designs.\n",
    "\n",
    "High-Level Synthesis provides an imperative language and a compiler that synthesizes the imperative instructions into RTL. For instance, _XLS_ provides a _Rust_-like language:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%writefile xls/x/adder.x\n",
    "pub fn adder(in1: u1, in2: u1) -> u2 {\n",
    "  let sum: u2 = in1 as u2 + in2 as u2;\n",
    "  sum\n",
    "}\n",
    "\n",
    "#[test]\n",
    "fn adder_test() {\n",
    "  let _= assert_eq(adder(u1:0, u1:0), u2:0b00);\n",
    "  let _= assert_eq(adder(u1:0, u1:1), u2:0b01);\n",
    "  let _= assert_eq(adder(u1:1, u1:1), u2:0b10);\n",
    "  _\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Testing, parsing and linting can be performed prior to RTL synhesis:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "!interpreter_main xls/x/adder.x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that the imperative instructions are tested, the RTL design can be synthesized by _XLS_:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "XLS_DESIGN_NAME = 'adder'\n",
    "!ir_converter_main --top={XLS_DESIGN_NAME} xls/x/{XLS_DESIGN_NAME}.x > xls/ir/{XLS_DESIGN_NAME}.ir\n",
    "!opt_main xls/ir/{XLS_DESIGN_NAME}.ir > xls/ir/{XLS_DESIGN_NAME}_opt.ir\n",
    "!codegen_main --generator=combinational xls/ir/{XLS_DESIGN_NAME}_opt.ir > v/{XLS_DESIGN_NAME}.v\n",
    "!cat v/{XLS_DESIGN_NAME}.v"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# References\n",
    "Inspired from:\n",
    "“Silicon Notebooks.” CHIPS Alliance, Apr. 08, 2023. Accessed: Apr. 10, 2023. [Online]. Available: https://github.com/chipsalliance/silicon-notebooks/blob/b65134a43b01ae31423f7ee87110740b2257ac42/digital-inverter-openlane.ipynb (Apache License 2.0)"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "name": "digital-inverter-openlane.ipynb",
   "provenance": []
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}