.. _l01-intro:


======================================
Laboratorium 1: wprowadzenie do nMigen
======================================

Data: 20.10.2020

.. toctree::

.. contents::


nMigen
======

nMigen jest narzędziem do tworzenia układów logicznych w języku Python.
Nie jest ściśle rzecz biorąc językiem opisu sprzętu, choć w praktyce
może być tak używany.

Aby opisać układ logiczny w narzędziu nMigen, należy stworzyć klasę
dziedziczącą z typu ``Elaboratable``, która ma metodę ``elaborate``,
która zwróci instancję klasy ``Module`` zawierającą naszą logikę.
Takie klasy mogą rekurencyjnie instancjonować inne klasy (i moduły),
by stworzyć hierarchiczny układ logiczny.

Mając taką klasę, możemy ją zinstancjonowac by stworzyć nasz układ logiczny i użyć go na jeden z kilku sposobów:

- przekonwertować go na język Verilog, by użyć go z narzędzami producenta
- spiąć nMigen z syntezatorem yosys, by móc używać modułów nMigena z kodu napisanego w Verilogu (i na odwrót)
- uruchomić symulator wbudowany w nMigen i testować nasz moduł za pomocą kodu Pythona


Instalacja narzędzi
-------------------

Instalujemy ``gtkwave`` i ``xdot`` (powinno być w repozytorium paczek dystrybucji).

Instalujemy yosysa w wersji 0.9 lub z gita::

        git clone git@github.com:YosysHQ/yosys.git
        cd yosys
        make -j4
        sudo make install

Instalujemy nMigen::

        pip3 --user install nmigen


Przykład
--------

Przykładowy moduł nMigena wraz z przykładowym użyciem symulatora można znaleźć tutaj: :download:`counter.py`.

Generowanie Veriloga::

        python counter.py verilog > counter.v

Generowanie RTLIL::

        python counter.py rtlil > counter.il

Wizualizacja (yosys)::

        yosys counter.il -p 'proc; clean; show'

Synteza na Xilinxa (yosys)::

        yosys counter.il -p 'synth_xilinx -edif counter.edif'

Uruchomienie symulacji::

        python counter.py simulate

Wizualizacja symulacji::

        gtkwave ctr.vcd