{
"cells": [
{
"cell_type": "markdown",
"id": "12978dc8-fa90-4a29-aaea-a2df6e16dfd4",
"metadata": {},
"source": [
"# Conditional coding style issues\n",
"\n",
"This is specific to RTLIL conversion and does not necessarily apply to HDL targets.\n",
"\n",
"There are a number of programming caveats involved with conditional statements, arising from the fact that we need to create hardware elements from a sequential programming style construct.\n",
"Statements that perform without warning in Python might therefore throw warnings or even errors when inferring to a RTLIL description.\n",
"\n",
"Plus, implicit behaviour is in place: When a signal is not explicitely assigned to a new value during a process flow graph cycle, it is assumed that it's unaltered, or implicitely: assigned to its previous value. This is tolerated style for synchronous process descriptions.\n",
"\n",
"However, asynchronous processes would infer a Multiplexer logic with its output fed back to an input, i.e. a *Latch*. Inferring a latch in a clock synchronous design is normally a bad choice alias design flaw."
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "6e858f92-878b-4db1-8584-28d09ae452a3",
"metadata": {},
"outputs": [],
"source": [
"from cyhdl import *"
]
},
{
"cell_type": "markdown",
"id": "37863bc8-1687-4c42-abaf-7b76d4712990",
"metadata": {},
"source": [
"First, we create a generator auxiliary for conversion of a unit with a 'standard' interface:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "9e37207e-a32f-41be-ab79-9e7227b44411",
"metadata": {},
"outputs": [],
"source": [
"from yosys import display\n",
"from myirl.targets import pyosys\n",
"\n",
"def convert(unit, name = \"test\", optimize = False, ignorefail = False):\n",
" tgt = pyosys.RTLIL(name)\n",
" if ignorefail:\n",
" tgt.warn_combloop = 'warn'\n",
" \n",
" clk = ClkSignal()\n",
" reset = ResetSignal(0, 1)\n",
" a, q = [ Signal(intbv()[8:]) for _ in range(2) ]\n",
" \n",
" inst = unit(clk, reset, q, a)\n",
" \n",
" d = inst.elab(tgt)\n",
" if optimize:\n",
" d[0].run(\"opt; opt_clean\")\n",
"\n",
" d[0].display_rtl(unit, fmt='dot')\n",
" return display.display_dot(d[0].name)"
]
},
{
"cell_type": "markdown",
"id": "a6e43de6-091d-40d4-b62d-c1fac2ed7a7b",
"metadata": {},
"source": [
"### Implicit default assignment\n",
"\n",
"The code below increments `w` every clock cycle only when bit 0 of `a` is set. Otherwise, it leaves it as it is. This can be seen as implicit assignment to its current value: `w.next = w`.\n",
"\n",
"This generates sane hardware, because Flipflops are created. Without a synchronous clock event, a latch would be created."
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "b4ee312d-5e8c-4b85-a57b-84203f8f954d",
"metadata": {},
"outputs": [],
"source": [
"@block\n",
"def implicit_defaults_unit(clk : ClkSignal, r : ResetSignal,\n",
" q : Signal.Output, a : Signal):\n",
"\n",
" w = Signal(intbv(0xaa)[8:])\n",
"\n",
" @always_seq(clk.posedge, r)\n",
" def proceed():\n",
" if a[0]:\n",
" w.next = w + 1\n",
" \n",
" wires = [\n",
" q.wireup(w)\n",
" ]\n",
"\n",
" return instances()\n"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "9ceaeea7-719d-4ca0-87ac-ec6671ed8020",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" DEBUG components ['implicit_defaults_unitu_1u_1u_8u_8'] (EmulationModule 'implicit_defaults_unit') \n",
"\u001b[32m Adding module with name `implicit_defaults_unit` \u001b[0m\n",
"\u001b[7;34m FINALIZE implementation `implicit_defaults_unit` of `implicit_defaults_unit` \u001b[0m\n"
]
},
{
"data": {
"text/html": [
"\n",
"
\n",
" \n",
" \n",
" \n",
" \n",
"
\n",
" "
],
"text/plain": [
""
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"convert(implicit_defaults_unit, optimize = False)"
]
},
{
"cell_type": "markdown",
"id": "ae4146fa-d2f8-4383-8b35-f08d08251484",
"metadata": {},
"source": [
"## Asynchronous implicit assignment: Latches and combinatorial loops\n",
"\n",
"This may turn up when an `@always` decorator argument lacks the `.posedge` attribute, i.e. is sensitive to anything else than a clock edge. Hence, an asynchronous process is created and the implicit default creates a feedback from the Muxer output to its input.\n",
"If `w` is assigned to a combination of its elements, a combinatorial loop would be created that could cause oscillation or excessive power consumption. If the case below would assign a constant, this would not cause oscillation but creation of a latch."
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "c1e37196-adee-4475-993a-326518e48be3",
"metadata": {},
"outputs": [],
"source": [
"@block\n",
"def latch_unit(clk : ClkSignal, r : ResetSignal,\n",
" q : Signal.Output, a : Signal):\n",
"\n",
" z = Signal(intbv(0xaa)[8:])\n",
"\n",
" @always(clk)\n",
" def proceed():\n",
" if a[0]:\n",
" z.next = z + 1\n",
" \n",
" wires = [\n",
" q.wireup(z)\n",
" ]\n",
"\n",
" return instances()\n"
]
},
{
"cell_type": "markdown",
"id": "12a96ce9-f20e-48fc-b023-6cf9186efd3f",
"metadata": {},
"source": [
"To turn the combinatorial loop failure into a warning, we pass `ignorefail = True`:"
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "305dac08-2782-4684-b4e0-430e3519b75e",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" DEBUG components ['latch_unitu_1u_1u_8u_8'] (EmulationModule 'latch_unit') \n",
"\u001b[32m Adding module with name `latch_unit` \u001b[0m\n",
"\u001b[7;31m LOOP_ERROR: z_343545826.py::proceed:10: Combinatorial loop for 'z' \u001b[0m\n",
"\u001b[7;31m LATCH_WARNING: Incomplete default assignments, latch created for 'z' \u001b[0m\n",
"\u001b[7;34m FINALIZE implementation `latch_unit` of `latch_unit` \u001b[0m\n"
]
},
{
"data": {
"text/html": [
"\n",
"
\n",
" \n",
" \n",
" \n",
" \n",
"
\n",
" "
],
"text/plain": [
""
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"convert(latch_unit, optimize = False, ignorefail = True)"
]
},
{
"cell_type": "markdown",
"id": "4aaab28a-0e4f-4e28-a5c7-866e57448082",
"metadata": {},
"source": [
"### Bad style #1: redundant logic\n",
"\n",
"The example below would create redundant logic, as the `else` clause is commented out. Creation of the Multiplexer for Line `15` is skipped, however you can see in the RTL display below that a comparator with a dangling output signal is left. During synthesis, this will be optimized away."
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "94cdb37e-3662-4220-8c4b-2e7973777897",
"metadata": {
"tags": []
},
"outputs": [],
"source": [
"@block\n",
"def pass_clause_unit(clk : ClkSignal, r : ResetSignal,\n",
" q : Signal.Output, a : Signal):\n",
"\n",
" w = Signal(intbv(0xaa)[8:])\n",
" b = Signal(bool())\n",
"\n",
" @always_seq(clk.posedge, r)\n",
" def proceed():\n",
" if a[0]:\n",
" w.next = 12\n",
" elif a[1]:\n",
" b.next = True\n",
" if a[5:2] == 4:\n",
" w.next = 4\n",
" elif a[5:2] == 2:\n",
" pass\n",
" # else: # Add an else clause\n",
" # w.next = 1\n",
" else:\n",
" b.next = False\n",
" w.next = 99\n",
"\n",
" wires = [\n",
" q.wireup(w)\n",
" ]\n",
"\n",
" return instances()\n"
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "3148bfaa-fade-4601-a22e-9dd036603f6f",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" DEBUG components ['pass_clause_unitu_1u_1u_8u_8'] (EmulationModule 'pass_clause_unit') \n",
"\u001b[32m Adding module with name `pass_clause_unit` \u001b[0m\n",
"\u001b[7;34m FINALIZE implementation `pass_clause_unit` of `pass_clause_unit` \u001b[0m\n"
]
},
{
"data": {
"text/html": [
"\n",
"
\n",
" \n",
" \n",
" \n",
" \n",
"
\n",
" "
],
"text/plain": [
""
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"convert(pass_clause_unit)"
]
},
{
"cell_type": "markdown",
"id": "4cca1924-50dc-4ce3-b79f-2b83e9361409",
"metadata": {},
"source": [
"With the `else` clause effective, the statements make sense and complete into multiplexers, although it's not considered the best style."
]
}
],
"metadata": {
"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.10.0"
}
},
"nbformat": 4,
"nbformat_minor": 5
}