Repository files navigation

CHEAT SHEET

Magma is a hardware design language embedded in python.

The central abstraction in Magma is a circuit.A circuit is a set of functional units that are wired together.Magma circuits are analagous to verilog modules.Thus, all Magma programs are guaranteed to be synthesizable.Although wiring modules together may seem low-level,it encourages hardware designers to build reusable components,similar to how programmers build libraries.

Python is used to to create Magma circuits.This approach to hardware design using scripting languagesis referred to asgenerators in the hardware community.Example hardware generators includearithmetic units,linear feedback shift registers,wallace trees,and sorting networks.Software engineers refer to this technique asmetaprogramming.The scripting language is a metaprogramin the sense that it is a program that creates a hardware program.

In contrast to verilog,Python has powerful metaprogramming capabilities,such as decorators and metaclasses.This makes it possible to createhigher-level domain-specific languages (DSLs).Examples include languages forfinite state machines,memory controllers,image and signal processing,and even processors.

The best way to learn Magma is through examples.Themagma_register_file_tutorialprovides an example of defining and verifying a register file generator.Themagmathon repository containsa set ofJupyterNotebooksthat introduce the system. There's alsomagma_examples andmagma_tutorial which contain aset of basic circuits and tests, providing an example templates for a magmaprojects. Finally there ismagma_riscv_miniwhich provides an example of a simple RISCV processor. Please also refer to thedocumentation.

The design of Magma was heavily influenced byChisel,so Magma should be easy to learn if you know Chisel.Some examples from the Chisel tutorial have been ported toMagma and can be found inhere.Magma also has aFIRRTL backend,and we hope to demonstrate interoperability with Chisel via FIRRTL soon.

Magma is designed to work withMantlewhich contains an a collection of useful circuits;and withLoamwhich is used to represent parts and boards,and to build applications for standalone FPGA boards.

magma requires using Python 3.7+. This section walks through a few common methodsfor getting set up with Python. The first (recommended) method is to useminiconda which supports MacOS and Linux (and Windows, but magma's support forwindows has not been tested). We also provide methods using the standardpackage managers for MacOS and Ubuntu Linux.

miniconda - A free minimal installer forconda. Miniconda is a small, bootstrap version of Anaconda that includes onlyconda, Python, the packages they depend on and a small number of other usefulpackages, including pip, zlib and a few others. Use the conda install commandto install 720+ additional conda packages from the Continuum repository.

Download the installer for your operating system fromhttps://conda.io/miniconda.html.

The following instructions uses the latest MacOSX release, replace the link inthe wget command for you operating system.

$ wget https://repo.continuum.io/miniconda/Miniconda3-latest-MacOSX-x86_64.sh$ bash Miniconda3-latest-MacOSX-x86_64.sh# Installing dependencies like matplotlib is typically more reliable with conda than pip$ conda install matplotlib

$ brew install python3

$ sudo apt-get install python3 python3-pip

$ pacman -S python python-pip

Magma depends on some third-party libraries that should be installed using youroperating system's package manager.

$ brew install verilator gmp mpfr libmpc

$ sudo apt-get install make gcc g++ verilator libgmp-dev libmpfr-dev libmpc-dev cmake

$ pacman -S verilator gmp mpfr libmpc tk

Magma is available as a pip package, install the lastest release with:

pip install magma-lang

Clone the magma repository

$ git clone https://github.com/phanrahan/magma$ cd magma

Install magma as a symbolic package

$ pip install -e .

Install testing infrastructure and run tests to validate the setup

$ pip install pytest fault  # you may need to add $HOME/.local/bin to your $PATH$ pytest tests

You should see something like

============================= test session starts ==============================platform darwin -- Python 3.6.1, pytest-3.0.7, py-1.4.33, pluggy-0.4.0rootdir: ..../repos/magmacore, inifile:collected 70 itemstests/test_circuit/test_anon.py .tests/test_circuit/test_declare.py .tests/test_circuit/test_define.py .tests/test_higher/test_braid.py .tests/test_higher/test_curry.py .tests/test_higher/test_currylut.py .tests/test_higher/test_curryrom.py .tests/test_higher/test_flat.py .tests/test_higher/test_fork.py .tests/test_higher/test_higher_compose.py .tests/test_higher/test_join.py .tests/test_interface/test_interface.py ....tests/test_io/test_inout1.py .tests/test_io/test_inout2.py .tests/test_io/test_out1.py .tests/test_io/test_out2.py .tests/test_ir/test_declaretest.py .tests/test_ir/test_ir.py .tests/test_meta/test_class.py .tests/test_meta/test_creg.py .tests/test_simulator/test_counter.py .tests/test_simulator/test_ff.py .tests/test_simulator/test_logic.py .tests/test_type/test_anon_type.py .tests/test_type/test_array.py .tests/test_type/test_array2d.py .tests/test_type/test_arrayconstruct.py .tests/test_type/test_arrayflip.py .tests/test_type/test_arrayval.py .tests/test_type/test_awire1.py .tests/test_type/test_bit.py .tests/test_type/test_bitflip.py .tests/test_type/test_bitval.py .tests/test_type/test_tuple.py .tests/test_type/test_tupleconstruct.py .tests/test_type/test_tupleflip.py .tests/test_type/test_tupleval.py .tests/test_type/test_twire1.py .tests/test_type/test_type_errors.py ...tests/test_type/test_vcc.py .tests/test_type/test_whole.py .tests/test_type/test_wire1.py .tests/test_type/test_wire2.py .tests/test_type/test_wire3.py .tests/test_type/test_wire4.py .tests/test_type/test_wire5.py .tests/test_verilog/test_verilog.py .tests/test_wire/test_arg1.py .tests/test_wire/test_arg2.py .tests/test_wire/test_array1.py .tests/test_wire/test_array2.py .tests/test_wire/test_array3.py .tests/test_wire/test_call1.py .tests/test_wire/test_call2.py .tests/test_wire/test_compose.py .tests/test_wire/test_const0.py .tests/test_wire/test_const1.py .tests/test_wire/test_errors.py ..tests/test_wire/test_flip.py .tests/test_wire/test_named1.py .tests/test_wire/test_named2a.py .tests/test_wire/test_named2b.py .tests/test_wire/test_named2c.py .tests/test_wire/test_pos.py .========================== 70 passed in 1.45 seconds ===========================