{"id":9915,"library":"magma-lang","title":"Magma-lang","description":"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.","status":"active","version":"3.0.2","language":"en","source_language":"en","source_url":"https://github.com/phanrahan/magma","tags":["hardware","HDL","circuit design","FPGA","eDSL"],"install":[{"cmd":"pip install magma-lang","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"Circuit","correct":"from magma import Circuit"},{"symbol":"Bit, In, Out","correct":"from magma import Bit, In, Out"},{"note":"Import specific classes or functions, not just the module.","wrong":"import magma.simulator","symbol":"PythonSimulator","correct":"from magma.simulator import PythonSimulator"},{"note":"DeclareCircuit was used in Magma v2; v3 uses class-based Circuit definitions.","wrong":"from magma import DeclareCircuit","symbol":"DeclareCircuit","correct":"from magma import Circuit"}],"quickstart":{"code":"import magma\nfrom magma import Circuit, In, Out, Bit\nfrom magma.simulator import PythonSimulator\n\n# Define a simple 2-input AND gate circuit\nclass And2(Circuit):\n    name = \"And2\"\n    io = In(a=Bit, b=Bit), Out(o=Bit)\n    def definition(self):\n        # Use the @= operator for wiring\n        self.o @= self.a & self.b\n\n# Instantiate the circuit\nand_gate = And2()\n\n# Print a representation of the circuit\nprint(f\"Defined circuit: {and_gate.name}\")\n\n# Simulate the circuit\nsimulator = PythonSimulator(and_gate)\n\n# Test case: 1 AND 0\nsimulator.set_value(and_gate.a, 1)\nsimulator.set_value(and_gate.b, 0)\nsimulator.evaluate()\nresult_1_0 = simulator.get_value(and_gate.o)\nprint(f\"1 AND 0 = {result_1_0}\") # Expected: 0\n\n# Test case: 1 AND 1\nsimulator.set_value(and_gate.a, 1)\nsimulator.set_value(and_gate.b, 1)\nsimulator.evaluate()\nresult_1_1 = simulator.get_value(and_gate.o)\nprint(f\"1 AND 1 = {result_1_1}\") # Expected: 1\n","lang":"python","description":"This example defines a basic 2-input AND gate using Magma's class-based circuit definition and then simulates its behavior using the PythonSimulator."},"warnings":[{"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.","message":"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()`.","severity":"breaking","affected_versions":"All v3.x versions (compared to v2.x)"},{"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.","message":"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'.","severity":"gotcha","affected_versions":"All v3.x versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All v3.x versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Rewrite your circuit definition using the Magma v3 class-based approach (e.g., `class MyCircuit(Circuit): ...`).","cause":"Attempting to use the Magma v2 syntax `magma.DeclareCircuit()` with a Magma v3 installation.","error":"AttributeError: module 'magma' has no attribute 'DeclareCircuit'"},{"fix":"Replace `magma.wire(source, sink)` with the v3 wiring operator `sink @= source` (or `source <<= sink`).","cause":"Attempting to use the Magma v2 wiring function `magma.wire()` with a Magma v3 installation.","error":"AttributeError: module 'magma' has no attribute 'wire'"},{"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.","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.","error":"TypeError: Can't connect Bit to Bits(N)"}]}