README.rst

   1 ### Migen (Milkymist generator)
   2
   3 [![Build Status](https://travis-ci.org/m-labs/migen.svg)](
   4 https://travis-ci.org/m-labs/migen)
   5
   6 #### A Python toolbox for building complex digital hardware
   7
   8 Despite being faster than schematics entry, hardware design with Verilog and
   9 VHDL remains tedious and inefficient for several reasons. The event-driven
  10 model introduces issues and manual coding that are unnecessary for synchronous
  11 circuits, which represent the lion's share of today's logic designs. Counter-
  12 intuitive arithmetic rules result in steeper learning curves and provide a
  13 fertile ground for subtle bugs in designs. Finally, support for procedural
  14 generation of logic (metaprogramming) through "generate" statements is very
  15 limited and restricts the ways code can be made generic, reused and organized.
  16
  17 To address those issues, we have developed the **Migen FHDL** library that
  18 replaces the event-driven paradigm with the notions of combinatorial and
  19 synchronous statements, has arithmetic rules that make integers always behave
  20 like mathematical integers, and most importantly allows the design's logic to
  21 be constructed by a Python program. This last point enables hardware designers
  22 to take advantage of the richness of the Python language - object oriented
  23 programming, function parameters, generators, operator overloading, libraries,
  24 etc. - to build well organized, reusable and elegant designs.
  25
  26 Other Migen libraries are built on FHDL and provide various tools such as a
  27 system-on-chip interconnect infrastructure, a dataflow programming system, a
  28 more traditional high-level synthesizer that compiles Python routines into
  29 state machines with datapaths, and a simulator that allows test benches to be
  30 written in Python.
  31
  32 See the doc/ folder for more technical information.
  33
  34 Migen is designed for Python 3.3. Note that Migen is **not** spelled MiGen.
  35
  36 #### Quick Links
  37
  38 Code repository:
  39 https://github.com/m-labs/migen
  40
  41 System-on-chip design based on Migen:
  42 https://github.com/m-labs/misoc
  43
  44 Online documentation:
  45 http://m-labs.hk/gateware.html
  46
  47 #### Quick intro
  48
  49 ```python
  50 from migen import *
  51 from migen.build.platforms import m1
  52 plat = m1.Platform()
  53 led = plat.request("user_led")
  54 m = Module()
  55 counter = Signal(26)
  56 m.comb += led.eq(counter[25])
  57 m.sync += counter.eq(counter + 1)
  58 plat.build_cmdline(m)
  59 ```
  60
  61 #### License
  62
  63 Migen is released under the very permissive two-clause BSD license. Under the
  64 terms of this license, you are authorized to use Migen for closed-source
  65 proprietary designs.
  66 Even though we do not require you to do so, those things are awesome, so please
  67 do them if possible:
  68 * tell us that you are using Migen
  69 * put the Migen logo (doc/migen_logo.svg) on the page of a product using it,
  70   with a link to http://m-labs.hk
  71 * cite Migen in publications related to research it has helped
  72 * send us feedback and suggestions for improvements
  73 * send us bug reports when something goes wrong
  74 * send us the modifications and improvements you have done to Migen. The use
  75    of "git format-patch" is recommended. If your submission is large and
  76    complex and/or you are not sure how to proceed, feel free to discuss it on
  77    the mailing list or IRC (#m-labs on Freenode) beforehand.
  78
  79 See LICENSE file for full copyright and license info. You can contact us on the
  80 public mailing list devel [AT] lists.m-labs.hk.
  81
  82   "Electricity! It's like magic!"