Skip to content
Permalink
Browse files
deploy: 0328abe
  • Loading branch information
whitequark committed Jun 26, 2020
0 parents commit 6efa4411ec83e6c07b767f21bd1dd8dfe51a67a7
Show file tree
Hide file tree
Showing 107 changed files with 23,646 additions and 0 deletions.
@@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 5c8359e6bc6cd19272a598362757a582
tags: 645f666f9bcd5a90fca523b33c5a78b7
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Empty file.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -0,0 +1,24 @@
The nMigen core manual
######################

.. warning::

This manual is a work in progress and is seriously incomplete!

.. toctree::
:maxdepth: 2

intro
install
start
lang

Index
=====

* :ref:`genindex`

Search
======

* :ref:`search`
@@ -0,0 +1,121 @@
Installation
############

System requirements
===================

nMigen requires Python 3.6; it works on CPython_ 3.6 (or newer), and works faster on PyPy3.6_ 7.2 (or newer).

Simulating nMigen code requires no additional software. However, a waveform viewer like GTKWave_ is invaluable for debugging.

Converting nMigen code to Verilog requires Yosys_ 0.9 (or newer).

Synthesizing, placing and routing an nMigen design for an FPGA requires Yosys_ 0.9 (or newer), as well as the FPGA family specific toolchain.

.. TODO: Link to FPGA family docs here
.. _CPython: https://www.python.org/
.. _PyPy3.6: https://www.pypy.org/
.. _Yosys: http://www.clifford.at/yosys/
.. _GTKWave: http://gtkwave.sourceforge.net/


Installing prerequisites
========================

... on Windows
--------------

.. todo::

Determine what's appropriate here (do we put Python in PATH? what about Yosys? is there something better than GTKWave? do we just give up and suggest WSL?)


... on Debian Linux
-------------------

nMigen works on Debian 10 or newer. The required version of Yosys is available in the main repository since Debian 11, but requires the Backports_ repository on Debian 10. Run:

.. note: debian 10 provides: python3 3.7.3, yosys 0.8 (yosys 0.9 in backports)
.. note: debian 11 provides: python3 3.8.2, yosys 0.9
.. code-block:: shell
$ sudo apt-get install python3-pip yosys gtkwave
.. _Backports: https://wiki.debian.org/Backports


... on Ubuntu Linux
-------------------

nMigen works on Ubuntu 20.04 LTS or newer.

.. note: ubuntu 20.04 provides: python3 3.8.2, yosys 0.9
.. code-block:: shell
$ sudo apt-get install python3-pip yosys gtkwave
... on macOS
------------

nMigen works best with Homebrew_. Run:

.. code-block:: shell
$ brew install python yosys gtkwave
.. _Homebrew: https://brew.sh


... on other platforms
----------------------

Refer to the `Yosys README`_ for detailed build instructions.

.. _Yosys README: https://github.com/YosysHQ/yosys/#setup


Installing nMigen
=================

The latest release of nMigen should work well for most applications. Any development snapshot---commit from the ``master`` branch of nMigen---should be similarly reliable, but is likely to include experimental API changes that will be in flux until the next release. With that in mind, development snapshots can be used to try out new functionality or to avoid bugs fixed since the last release.


Latest release
--------------

To install the latest release of nMigen, run:

.. code-block:: shell
$ pip3 install --upgrade nmigen
Development snapshot
--------------------

To install a development snapshot of nMigen for the first time, run:

.. code-block:: shell
$ git clone https://github.com/nmigen/nmigen
$ cd nmigen
$ pip3 install --editable .
Any changes made to the ``nmigen`` directory will immediately affect any code that uses nMigen. To update the snapshot, run:

.. code-block:: shell
$ cd nmigen
$ git pull --ff-only origin master
Installing board definitions
=============================

.. todo::

Explain how to install `<https://github.com/nmigen/nmigen-boards>`_.
@@ -0,0 +1,93 @@
.. TODO: this introduction is written for people well familiar with HDLs; we likely need
another one for people who will use nMigen as their first HDL
Introduction
############

The core nMigen project provides an open-source toolchain for developing hardware based on synchronous digital logic using the Python programming language. It aims to be easy to learn and use, reduce or eliminate common coding mistakes, and simplify the design of complex hardware with reusable components.

The nMigen toolchain consists of the :ref:`nMigen language <intro-lang>`, the :ref:`standard library <intro-stdlib>`, the :ref:`simulator <intro-sim>`, and the :ref:`build system <intro-build>`, covering all steps of a typical FPGA development workflow. At the same time, it does not restrict the designer's choice of tools: existing industry-standard (System)Verilog or VHDL code can be integrated into an nMigen design flow, or, conversely, nMigen code can be integrated into an existing Verilog-based design flow.

.. TODO: add links to connect_rpc docs once they exist
.. _intro-lang:

The nMigen language
===================

The :doc:`nMigen hardware description language <lang>` is a Python library for register transfer level modeling of synchronous logic. Ordinary Python code is used to construct a netlist of a digital circuit, which can be simulated, directly synthesized via Yosys_, or converted to human-readable Verilog code for use with industry-standard toolchains.

By relying on the flexibility, rich functionality and widespread adoption of the Python language, the nMigen language is focused on a single task: modeling digital logic well. It has first-class support for building blocks like clock domains and finite state machines, and uses simple rules for arithmetic operations that closely match the Python semantics. Python classes, functions, loops and conditionals can be used to build organized and flexible designs; Python libraries can be seamlessly used with nMigen during design or verification; and Python development tools can process nMigen code.

A core design principle of the nMigen language is to be not only easy to use, but also hard to accidentally misuse. Some HDLs provide functionality that has unexpected and undesirable behavior in synthesis, often with expensive consequences, and require a significant effort in learning a "safe" coding style and adopting third-party linting tools. nMigen lacks non-synthesizable constructs and avoids error-prone inference in favor of explicit instantiation. It has many diagnostics (and regularly adds new ones) highlighting potential design issues. Most importantly, all usability issues are considered `reportable bugs`_.

.. _Yosys: http://www.clifford.at/yosys/
.. _reportable bugs: https://github.com/nmigen/nmigen/issues


.. _intro-stdlib:

The nMigen standard library
===========================

The nMigen language comes with a standard library---a collection of essential digital design components and interfaces. It includes clock domain crossing primitives, synchronous and asynchronous FIFOs, a flexible I/O buffer interface, and more. By providing reliable building blocks out of the box, nMigen allows the designer to focus on their application and avoids subtle differences in behavior between different designs.

.. TODO: link to stdlib here
Clock domain crossing often requires special treatment, such as using vendor-defined attributes or instantiating device-specific primitives. The CDC primitives in the nMigen standard library can be overridden by the platform integration, and every platform integration included with nMigen follows the vendor recommendations for CDC.

High-speed designs usually require the use of registered (and sometimes, geared) I/O buffers. The nMigen standard library provides a common interface to be used between I/O buffers and peripheral implementations. The nMigen build system, if used, can instantiate I/O buffers for every platform integration included with nMigen.

While many designs will use at least some vendor-specific functionality, the components provided by the nMigen standard library reduce the amount of code that needs to be changed when migrating between FPGA families, and the common interfaces simplify peripherals, test benches and simulations.

The nMigen standard library is optional: the nMigen language can be used without it. Conversely, it is possible to use the nMigen standard library components in Verilog or VHDL code, with some limitations.

.. TODO: link to connect_rpc docs here *again*
.. _intro-sim:

The nMigen simulator
====================

The nMigen project includes an advanced simulator for nMigen code implemented in Python with no system dependencies; in this simulator, test benches are written as Python generator functions. Of course, it is always possible to convert an nMigen design to Verilog for use with well-known tool like `Icarus Verilog`_ or Verilator_.

The nMigen simulator is event-driven and can simulate designs with multiple clocks or asynchronous resets. Although it is slower than `Icarus Verilog`_, it compiles the netlist to Python code ahead of time, achieving remarkably high performance for a pure Python implementation---especially when running on PyPy_.

Although nMigen does not support native code simulation or co-simulation at the moment, such support will be added in near future.

.. _Icarus Verilog: http://iverilog.icarus.com/
.. _Verilator: https://www.veripool.org/wiki/verilator
.. _GTKWave: http://gtkwave.sourceforge.net/
.. _PyPy: https://www.pypy.org/


.. _intro-build:

The nMigen build system
=======================

To achieve an end-to-end FPGA development workflow, the nMigen project integrates with all major FPGA toolchains and provides definitions for many common development boards.

.. TODO: link to vendor docs and board docs here
FPGA toolchain integration
--------------------------

Each FPGA family requires the use of synthesis and place & route tools specific for that device family. The nMigen build system directly integrates with every major open-source and commercial FPGA toolchain, and can be easily extended to cover others.

Through this integration, nMigen can specialize the CDC primitives and I/O buffers for a particular device and toolchain; generate I/O and clock constraints from board definition files; synchronize the power-on reset in single-clock designs; include (System)Verilog and VHDL files in the design (if supported by the toolchain); and finally, generate a script running synthesis, placement, routing, and timing analysis. The generated code can be customized to insert additional options, commands, constraints, and so on.

The nMigen build system produces self-contained, portable build trees that require only the toolchain to be present in the environment. This makes builds easier to reproduce, or to run on a remote machine. The generated build scripts are always provided for both \*nix and Windows.


Development board definitions
-----------------------------

Getting started with a new FPGA development board often requires going through a laborous and error-prone process of deriving toolchain configuration and constraint files from the supplied documentation. The nMigen project includes a community-maintained repository of definitions for many open-source and commercial FPGA development boards.

These board definitions contain everything that is necessary to start using the board: FPGA family and model, clocks and resets, descriptions of on-board peripherals (including pin direction and attributes such as I/O standard), connector pinouts, and for boards with a built-in debug probe, the steps required to program the board. It takes a single Python invocation to generate, build, and download a test design that shows whether the board, toolchain, and programmer are working correctly.

nMigen establishes a pin naming convention for many common peripherals (such as 7-segment displays, SPI flashes and SDRAM memories), enabling the reuse of unmodified interface code with many different boards. Further, the polarity of all control signals is unified to be active high, eliminating accidental polarity inversions and making simulation traces easier to follow; active low signals are inverted during I/O buffer instantiation.

0 comments on commit 6efa441

Please sign in to comment.