Magma-lang

3.0.2 · active · verified Fri Apr 17

Magma-lang is an embedded domain-specific language (eDSL) in Python for designing and generating hardware circuits. It enables hierarchical and compositional circuit design, targeting various hardware description languages like Verilog. The current version is 3.0.2, with active development incorporating community feedback and feature enhancements.

Common errors

```
AttributeError: module 'magma' has no attribute 'DeclareCircuit'
```
cause Attempting to use the Magma v2 syntax `magma.DeclareCircuit()` with a Magma v3 installation.

fix Rewrite your circuit definition using the Magma v3 class-based approach (e.g., `class MyCircuit(Circuit): ...`).
```
AttributeError: module 'magma' has no attribute 'wire'
```
cause Attempting to use the Magma v2 wiring function `magma.wire()` with a Magma v3 installation.

fix Replace `magma.wire(source, sink)` with the v3 wiring operator `sink @= source` (or `source <<= sink`).
```
TypeError: Can't connect Bit to Bits(N)
```
cause An attempt was made to connect a single-bit signal (`magma.Bit`) to a multi-bit signal (`magma.Bits(N)`), or vice-versa, without proper type handling.

fix Ensure the bit widths of the signals being connected are compatible. Use slicing (e.g., `array_of_bits[0]`) or explicit type conversions like `magma.bits()` to match the widths.

Warnings

breaking Magma v3 introduced significant breaking changes from v2, including a shift from functional `DeclareCircuit` to class-based `Circuit` definitions, and a new `@=` operator for wiring instead of `magma.wire()`.
Fix: Consult the 'V2 to V3 Migration Guide' in the official Magma documentation. Redefine circuits as classes inheriting `magma.Circuit` and use the `@=` or `<<=` operators for connections.
gotcha The wiring operator `@=` connects the left-hand side to the right-hand side. It's crucial to understand the data flow direction in hardware. E.g., `a @= b` means 'a is driven by b'.
Fix: Always ensure the source (driver) is on the right-hand side and the destination (driven) is on the left-hand side of `@=`. For multiple drivers, ensure the correct priority or avoid conflicts.
gotcha Distinction between single bits (`magma.Bit`) and arrays of bits (`magma.Bits(n)` or `magma.Array[n, Bit]`). Type mismatches during wiring (e.g., connecting a `Bit` to `Bits(4)`) are a common source of errors.
Fix: Explicitly define the correct type for each port. Use type conversion functions like `magma.bits()` or slicing (`[idx]`) to match types when connecting signals of different widths.

Install

pip install magma-lang Install latest version

Imports

Circuit
```
from magma import Circuit
```
Bit, In, Out
```
from magma import Bit, In, Out
```
PythonSimulator
wrong:
```
import magma.simulator
```
correct:
```
from magma.simulator import PythonSimulator
```
Import specific classes or functions, not just the module.
DeclareCircuit
wrong:
```
from magma import DeclareCircuit
```
correct:
```
from magma import Circuit
```
DeclareCircuit was used in Magma v2; v3 uses class-based Circuit definitions.

Quickstart

This example defines a basic 2-input AND gate using Magma's class-based circuit definition and then simulates its behavior using the PythonSimulator.

import magma
from magma import Circuit, In, Out, Bit
from magma.simulator import PythonSimulator

# Define a simple 2-input AND gate circuit
class And2(Circuit):
    name = "And2"
    io = In(a=Bit, b=Bit), Out(o=Bit)
    def definition(self):
        # Use the @= operator for wiring
        self.o @= self.a & self.b

# Instantiate the circuit
and_gate = And2()

# Print a representation of the circuit
print(f"Defined circuit: {and_gate.name}")

# Simulate the circuit
simulator = PythonSimulator(and_gate)

# Test case: 1 AND 0
simulator.set_value(and_gate.a, 1)
simulator.set_value(and_gate.b, 0)
simulator.evaluate()
result_1_0 = simulator.get_value(and_gate.o)
print(f"1 AND 0 = {result_1_0}") # Expected: 0

# Test case: 1 AND 1
simulator.set_value(and_gate.a, 1)
simulator.set_value(and_gate.b, 1)
simulator.evaluate()
result_1_1 = simulator.get_value(and_gate.o)
print(f"1 AND 1 = {result_1_1}") # Expected: 1

view raw JSON →