In this notebook we will discuss the combinational and sequential syntaxes in more detail. See https://magma.readthedocs.io/en/latest/circuit_definitions/ for the full documentation
In [1]:
import magma as m
import inspect
import fault
from hwtypes import BitVector
In [2]:
@m.circuit.combinational
def basic_if(I: m.Bits[2], S: m.Bit) -> m.Bit:
if S:
x = I[0]
else:
x = I[1]
return x
print(repr(basic_if.circuit_definition))
Magma implements this syntax by converting the function to SSA form, and using the mux circuit to implement the phi nodes. We can inspect the intermediate Python code used by magma.
In [3]:
m.compile("build/basic_if", basic_if)
with open('.magma/basic_if.py', 'r') as f:
print(f.read())
Let's test our function using fault
In [4]:
tester = fault.PythonTester(basic_if)
assert tester(BitVector[2]([0, 1]), 0) == 1
assert tester(BitVector[2]([0, 1]), 1) == 0
In [5]:
tester = fault.Tester(basic_if)
tester(BitVector[2]([0, 1]), 0).expect(1)
tester(BitVector[2]([0, 1]), 1).expect(0)
tester.compile_and_run("verilator")
You can insert code to instance magma circuits inside combinational.
In [6]:
from mantle import Not
@m.circuit.combinational
def invert(a: m.Bit) -> m.Bit:
return Not()(a)
print(repr(invert.circuit_definition))
In [7]:
tester = fault.PythonTester(invert)
assert tester(0) == 1
assert tester(1) == 0
In [8]:
tester = fault.Tester(invert)
tester(1).expect(0)
tester(0).expect(1)
# Need coreir commonlib since we are compiling multiple circuits so the namespace already has references to mux
tester.compile_and_run("verilator", magma_opts={"coreir_libs": {"commonlib"}})
We can return multiple values as Python tuples. These will create output ports named O{i} where i is the index in the tuple
In [9]:
@m.circuit.combinational
def return_py_tuple(I: m.Bits[2]) -> (m.Bit, m.Bit):
return I[0], I[1]
print(repr(return_py_tuple.circuit_definition))
You can also return a magma tuple (this will only create one output)
In [10]:
@m.circuit.combinational
def return_magma_tuple(I: m.Bits[2]) -> m.Tuple[m.Bit, m.Bit]:
return m.tuple_([I[0], I[1]])
print(repr(return_magma_tuple.circuit_definition))
You can also return a magmas product (useful if you'd like to name the outputs)
In [11]:
@m.circuit.combinational
def return_magma_named_tuple(I: m.Bits[2]) -> m.Product.from_fields("anon", {"x": m.Bit, "y": m.Bit}):
return m.product(x=I[0], y=I[1])
print(repr(return_magma_named_tuple.circuit_definition))
Statically elaborated for loops are supported using the ast_tools loop unrolling macro. Here's an example:
In [12]:
import ast_tools
from ast_tools.passes import begin_rewrite, loop_unroll, end_rewrite
n = 4
@m.circuit.combinational
@end_rewrite()
@loop_unroll()
@begin_rewrite()
def logic(a: m.Bits[n]) -> m.Bits[n]:
O = []
for i in ast_tools.macros.unroll(range(n)):
O.append(a[n - 1 - i])
return m.bits(O, n)
print(repr(logic.circuit_definition))
The @m.circuit.sequential decorator extends the @m.circuit.combinational syntax with the ability to use Python's class system to describe stateful circuits.
The basic pattern uses the __init__ method to declare state, and a __call__ function that uses @m.circuit.combinational syntax to describe the transition function from the current state to the next state, as well as a function from the inputs to the outputs. State is referenced using the first argument self and is implicitly updated by writing to attributes of self (e.g. self.x = 3).
Here's an example of a Counter with an enable input inc.
In [13]:
@m.circuit.sequential(async_reset=True)
class Counter:
def __init__(self):
self.count : m.UInt[16] = 0
def __call__(self, inc : m.Bit) -> m.UInt[16]:
if inc:
self.count = self.count + 1
O = self.count
return O
m.compile("Counter", Counter, inline=True)
!coreir -i Counter.json -p instancecount -l commonlib
In the __init__ method, the circuit declares a statement self.count with an annotated type m.UInt[16] and an initial value 0. The __call__ method accepts an input inc of type Bit which acts as an enable on the counter logic. The __call__ method updates the counter state if the enable is high, and returns the next value of the counter (so when enable is high, it will output the state value plus one). Writes to state elements use Python semantics (Verilog blocking). Notice that the input and output of the __call__ method have type annotations just like m.circuit.combinational functions. The __call__ method should be treated as a standard @m.circuit.combinational function, with the special parameter self that provides access to the state.
In [14]:
tester = fault.PythonTester(Counter, Counter.CLK)
tester.poke(Counter.inc, True)
tester.eval()
for i in range(4):
print(tester.peek(Counter.O))
assert tester.peek(Counter.O) == i + 1
tester.step(2)
tester.poke(Counter.inc, False)
tester.eval()
for i in range(4):
print(tester.peek(Counter.O))
assert tester.peek(Counter.O) == 4
tester.step(2)
tester.poke(Counter.ASYNCRESET, 1)
tester.eval()
print(tester.peek(Counter.O))
assert tester.peek(Counter.O) == 0
Sequential supports hierarchical composition
In [15]:
@m.circuit.sequential(async_reset=True)
class Register:
def __init__(self):
self.value: m.Bits[2] = m.bits(0, 2)
def __call__(self, I: m.Bits[2]) -> m.Bits[2]:
O = self.value
self.value = I
return O
@m.circuit.sequential(async_reset=True)
class TestShiftRegister:
def __init__(self):
self.x: Register = Register()
self.y: Register = Register()
def __call__(self, I: m.Bits[2]) -> m.Bits[2]:
x_prev = self.x(I)
y_prev = self.y(x_prev)
return y_prev
print(repr(TestShiftRegister))
# Need coreir commonlib since we are compiling multiple circuits so the namespace already has references to mux
m.compile("build/TestShiftRegister", TestShiftRegister, inline=True, coreir_libs={"commonlib"})
!cat build/TestShiftRegister.v
NOTE Currently it is required that every sub sequential circuit element receive an explicit invocation in the __call__ method. For example, if you have a sub sequential circuit self.x that you would like to keep constant, you must still call it with self.x(...) to ensure that some input value is provided every cycle (the sub sequential circuit must similarly be designed in such a way that the logic expects inputs every cycle, so enable logic must be explicitly defined).
In [ ]: