m-labs · Sep 5, 2015 · Sep 5, 2015 · Sep 10, 2015 · Sep 10, 2015 · Sep 10, 2015
diff --git a/.travis.yml b/.travis.yml
@@ -15,12 +15,12 @@ before_install:
   - conda install anaconda-client numpydoc
 install:
   # Install iverilog package.
-  - "sudo add-apt-repository -y ppa:mithro/iverilog-backport"
-  - "sudo apt-get update"
-  - "sudo apt-get install iverilog"
-  - "iverilog -v; true"
+  # - "sudo add-apt-repository -y ppa:mithro/iverilog-backport"
+  # - "sudo apt-get update"
+  # - "sudo apt-get install iverilog"
+  # - "iverilog -v; true"
   # Build the vpi module.
-  - "(cd vpi; make; sudo make install)"
+  # - "(cd vpi; make; sudo make install)"
   # Install verilator package
   - "sudo apt-get install verilator"
   - "verilator --version; true"

diff --git a/README.md → README.rst b/README.md → README.rst
@@ -47,8 +47,8 @@ http://m-labs.hk/gateware.html
 #### Quick intro
 
 ```python
-from migen.fhdl.std import *
-from mibuild.platforms import m1
+from migen import *
+from migen.build.platforms import m1
 plat = m1.Platform()
 led = plat.request("user_led")
 m = Module()

diff --git a/doc/actors_endpoints.dia b/doc/actors_endpoints.dia
diff --git a/doc/actors_endpoints.png b/doc/actors_endpoints.png
diff --git a/doc/bus.rst b/doc/bus.rst
diff --git a/doc/casestudies.rst b/doc/casestudies.rst
diff --git a/doc/conf.py b/doc/conf.py
@@ -11,8 +11,6 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -47,16 +45,16 @@
 
 # General information about the project.
 project = u'Migen'
-copyright = u'2012, Sebastien Bourdeauducq'
+copyright = u'2011-2015, M-Labs Limited'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = 'X'
+version = '1.0'
 # The full version, including alpha/beta/rc tags.
-release = 'X'
+release = '1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -90,15 +88,15 @@
 pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
-modindex_common_prefix = ['migen.', 'mibuild.']
+modindex_common_prefix = ['migen.']
 
 numpydoc_show_class_members = False
 
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

diff --git a/doc/dataflow.rst b/doc/dataflow.rst
diff --git a/doc/fbflow.dia b/doc/fbflow.dia
diff --git a/doc/fbflow.png b/doc/fbflow.png
diff --git a/doc/fhdl.rst b/doc/fhdl.rst
@@ -1,29 +1,34 @@
-The FHDL layer
-##############
+The FHDL domain-specific language
+#################################
 
-The Fragmented Hardware Description Language (FHDL) is the lowest layer of Migen. It consists of a formal system to describe signals, and combinatorial and synchronous statements operating on them. The formal system itself is low level and close to the synthesizable subset of Verilog, and we then rely on Python algorithms to build complex structures by combining FHDL elements.
+The Fragmented Hardware Description Language (FHDL) is the basis of Migen. It consists of a formal system to describe signals, and combinatorial and synchronous statements operating on them. The formal system itself is low level and close to the synthesizable subset of Verilog, and we then rely on Python algorithms to build complex structures by combining FHDL elements.
 The FHDL module also contains a back-end to produce synthesizable Verilog, and some structure analysis and manipulation functionality.
 
 FHDL differs from MyHDL [myhdl]_ in fundamental ways. MyHDL follows the event-driven paradigm of traditional HDLs (see :ref:`background`) while FHDL separates the code into combinatorial statements, synchronous statements, and reset values. In MyHDL, the logic is described directly in the Python AST. The converter to Verilog or VHDL then examines the Python AST and recognizes a subset of Python that it translates into V*HDL statements. This seriously impedes the capability of MyHDL to generate logic procedurally. With FHDL, you manipulate a custom AST from Python, and you can more easily design algorithms that operate on it.
 
 .. [myhdl] http://www.myhdl.org
 
-FHDL is made of several elements, which are briefly explained below. They all can be imported from the ``migen.fhdl.std`` module.
+FHDL is made of several elements, which are briefly explained below. They all can be imported directly from the ``migen`` module.
 
 Expressions
 ***********
 
-Integers and booleans
-=====================
+Constants
+=========
+
+The ``Constant`` object represents a constant, HDL-literal integer. It behaves like specifying integers and booleans but also supports slicing and can have a bit width or signedness different from what is implied by the value it represents.
 
-Python integers and booleans can appear in FHDL expressions to represent constant values in a circuit. ``True`` and ``False`` are interpreted as 1 and 0, respectively.
+``True`` and ``False`` are interpreted as 1 and 0, respectively.
 
 Negative integers are explicitly supported. As with MyHDL [countin]_, arithmetic operations return the natural results.
 
+To lighten the syntax, assignments and operators automatically wrap Python integers and booleans into ``Constant``. Additionally, ``Constant`` is aliased to ``C``. The following are valid Migen statements: ``a.eq(0)``, ``a.eq(a + 1)``, ``a.eq(C(42)[0:1])``.
+
 .. [countin] http://www.jandecaluwe.com/hdldesign/counting.html
 
 Signal
 ======
+
 The signal object represents a value that is expected to change in the circuit. It does exactly what Verilog's "wire" and "reg" and VHDL's "signal" do.
 
 The main point of the signal object is that it is identified by its Python ID (as returned by the :py:func:`id` function), and nothing else. It is the responsibility of the V*HDL back-end to establish an injective mapping between Python IDs and the V*HDL namespace. It should perform name mangling to ensure this. The consequence of this is that signal objects can safely become members of arbitrary Python classes, or be passed as parameters to functions or methods that generate logic involving them.
@@ -45,6 +50,7 @@ In case of conflicts, Migen tries first to resolve the situation by prefixing th
 
 Operators
 =========
+
 Operators are represented by the ``_Operator`` object, which generally should not be used directly. Instead, most FHDL objects overload the usual Python logic and arithmetic operators, which allows a much lighter syntax to be used. For example, the expression: ::
 
   a * b + c
@@ -55,22 +61,26 @@ is equivalent to::
 
 Slices
 ======
+
 Likewise, slices are represented by the ``_Slice`` object, which often should not be used in favor of the Python slice operation [x:y]. Implicit indices using the forms [x], [x:] and [:y] are supported. Beware! Slices work like Python slices, not like VHDL or Verilog slices. The first bound is the index of the LSB and is inclusive. The second bound is the index of MSB and is exclusive. In V*HDL, bounds are MSB:LSB and both are inclusive.
 
 Concatenations
 ==============
+
 Concatenations are done using the ``Cat`` object. To make the syntax lighter, its constructor takes a variable number of arguments, which are the signals to be concatenated together (you can use the Python "*" operator to pass a list instead).
 To be consistent with slices, the first signal is connected to the bits with the lowest indices in the result. This is the opposite of the way the "{}" construct works in Verilog.
 
 Replications
 ============
+
 The ``Replicate`` object represents the equivalent of {count{expression}} in Verilog.
 
 Statements
 **********
 
 Assignment
 ==========
+
 Assignments are represented with the ``_Assign`` object. Since using it directly would result in a cluttered syntax, the preferred technique for assignments is to use the ``eq()`` method provided by objects that can have a value assigned to them. They are signals, and their combinations with the slice and concatenation operators.
 As an example, the statement: ::
 
@@ -82,6 +92,7 @@ is equivalent to: ::
 
 If
 ==
+
 The ``If`` object takes a first parameter which must be an expression (combination of the ``Constant``, ``Signal``, ``_Operator``, ``_Slice``, etc. objects) representing the condition, then a variable number of parameters representing the statements (``_Assign``, ``If``, ``Case``, etc. objects) to be executed when the condition is verified.
 
 The ``If`` object defines a ``Else()`` method, which when called defines the statements to be executed when the condition is not true. Those statements are passed as parameters to the variadic method.
@@ -105,10 +116,12 @@ Example: ::
 
 Case
 ====
+
 The ``Case`` object constructor takes as first parameter the expression to be tested, and a dictionary whose keys are the values to be matched, and values the statements to be executed in the case of a match. The special value ``"default"`` can be used as match value, which means the statements should be executed whenever there is no other match.
 
 Arrays
 ======
+
 The ``Array`` object represents lists of other objects that can be indexed by FHDL expressions. It is explicitly possible to:
 
 * nest ``Array`` objects to create multidimensional tables.
@@ -134,6 +147,7 @@ Specials
 
 Tri-state I/O
 =============
+
 A triplet (O, OE, I) of one-way signals defining a tri-state I/O port is represented by the ``TSTriple`` object. Such objects are only containers for signals that are intended to be later connected to a tri-state I/O buffer, and cannot be used as module specials. Such objects, however, should be kept in the design as long as possible as they allow the individual one-way signals to be manipulated in a non-ambiguous way.
 
 The object that can be used in as a module special is ``Tristate``, and it behaves exactly like an instance of a tri-state I/O buffer that would be defined as follows: ::
@@ -153,6 +167,7 @@ By default, Migen emits technology-independent behavioral code for a tri-state b
 
 Instances
 =========
+
 Instance objects represent the parametrized instantiation of a V*HDL module, and the connection of its ports to FHDL signals. They are useful in a number of cases:
 
 * Reusing legacy or third-party V*HDL code.
@@ -170,6 +185,7 @@ These parameters can be:
 
 Memories
 ========
+
 Memories (on-chip SRAM) are supported using a mechanism similar to instances.
 
 A memory object has the following parameters:
@@ -258,7 +274,7 @@ Clock domains are then added to a module using the ``clock_domains`` special att
 Summary of special attributes
 =============================
 
-.. table:: Summary of special attributes
+.. table::
 
    +--------------------------------------------+--------------------------------------------------------------+
    | Syntax                                     | Action                                                       |
@@ -338,16 +354,9 @@ Finalization is automatically invoked at V*HDL conversion and at simulation. It
 
 The clock domain management mechanism explained above happens during finalization.
 
-Simulation
-==========
-
-The ``do_simulation`` method of the ``Module`` class can be defined and will be executed at each clock cycle, or the generator-style API can be used by defining ``gen_simulation`` instead. The generator yields the number of cycles it wants to wait for. See :ref:`simulating` for more information on using the simulator.
-
-Simulation of designs with several clock domains is not supported yet.
-
 Conversion for synthesis
 ************************
 
-Any FHDL module (except, of course, its simulation functions) can be converted into synthesizable Verilog HDL. This is accomplished by using the ``convert`` function in the ``verilog`` module.
+Any FHDL module can be converted into synthesizable Verilog HDL. This is accomplished by using the ``convert`` function in the ``verilog`` module.
 
-The Mibuild component provides scripts to interface third-party FPGA tools to Migen and a database of boards for the easy deployment of designs.
+The ``migen.build`` component provides scripts to interface third-party FPGA tools (from Xilinx, Altera and Lattice) to Migen, and a database of boards for the easy deployment of designs.
diff --git a/doc/get_edge_labels.png b/doc/get_edge_labels.png
diff --git a/doc/index.rst b/doc/index.rst
@@ -6,8 +6,6 @@ Migen manual
 
    introduction
    fhdl
-   bus
-   dataflow
    simulation
-   casestudies
-   api
+   synthesis
+   reference
diff --git a/doc/introduction.rst b/doc/introduction.rst
@@ -10,7 +10,7 @@ Migen makes it possible to apply modern software concepts such as object-oriente
 Background
 **********
 
-Even though the Milkymist system-on-chip [mm]_ is technically successful, it suffers from several limitations stemming from its implementation in manually written Verilog HDL:
+Even though the Milkymist system-on-chip [mm]_ had many successes, it suffers from several limitations stemming from its implementation in manually written Verilog HDL:
 
 .. [mm] http://m-labs.hk
 
@@ -38,20 +38,24 @@ Even though the Milkymist system-on-chip [mm]_ is technically successful, it suf
    #. Building a memory infrastructure (including bus interconnect, bridges and caches) that can automatically adapt itself at compile-time to any word size of the SDRAM is clumsy and tedious.
    #. Building register banks for control, status and interrupt management of cores can also largely benefit from automation.
    #. Many hardware acceleration problems can fit into the dataflow programming model. Manual dataflow implementation in V*HDL has, again, a lot of redundancy and potential for human errors. See the Milkymist texture mapping unit [mthesis]_ [mxcell]_ for an example of this. The amount of detail to deal with manually also makes the design space exploration difficult, and therefore hinders the design of efficient architectures.
-   #. Pre-computation of values, such as filter coefficients for DSP or even simply trigonometric tables, must often be done using external tools whose results are copy-and-pasted (in the best cases, automatically) into the V*HDL source.
+   #. Pre-computation of values, such as filter coefficients for DSP or even simply trigonometric tables, must often be done using external tools whose results are copy-and-pasted (in the best case, automatically) into the V*HDL source.
 
 .. [mthesis] http://m-labs.hk/thesis/thesis.pdf
 .. [mxcell] http://www.xilinx.com/publications/archives/xcell/Xcell77.pdf p30-35
    
 Enter Migen, a Python toolbox for building complex digital hardware. We could have designed a brand new programming language, but that would have been reinventing the wheel instead of being able to benefit from Python's rich features and immense library. The price to pay is a slightly cluttered syntax at times when writing descriptions in FHDL, but we believe this is totally acceptable, particularly when compared to VHDL ;-)
 
-Migen is made up of several related components, which are described in this manual.
+Migen is made up of several related components:
+
+#. the base language, FHDL
+#. a library of small generic cores
+#. a simulator
+#. a build system
 
 Installing Migen
 ****************
-Either run the ``setup.py`` installation script or simply set ``PYTHONPATH`` to the root of the source directory.
 
-For simulation support, an extra step is needed. See :ref:`vpisetup`.
+Either run the ``setup.py`` installation script or simply set ``PYTHONPATH`` to the root of the source directory.
 
 If you wish to contribute patches, the suggest way to install is;
    #. Clone from the git repository at http://github.com/m-labs/migen
@@ -61,9 +65,9 @@ If you wish to contribute patches, the suggest way to install is;
 Alternative install methods
 ===========================
 
- * Migen is available for linux-64 and linux-32 through Binstar's conda tool. Instructions are at https://binstar.org/fallen/migen
- * Migen can be referenced in a requirements.txt file (used for ``pip install -r requirements.txt``) via ``-e git+http://github.com/m-labs/migen.git#egg=migen``. See the `pip documentation <https://pip.pypa.io/en/latest/reference/pip_install.html#id19>`_ for more information.
+ * Migen is available for the Anaconda Python distribution. The package can be found at at https://anaconda.org/m-labs/migen
+ * Migen can be referenced in a requirements.txt file (used for ``pip install -r requirements.txt``) via ``-e git+http://github.com/m-labs/migen.git#egg=migen``. See the pip documentation for more information.
 
 Feedback
 ********
-Feedback concerning Migen or this manual should be sent to the M-Labs developers' mailing list at devel@lists.m-labs.hk.
+Feedback concerning Migen or this manual should be sent to the M-Labs developers' mailing list ``devel`` on lists.m-labs.hk.
diff --git a/doc/api.rst → doc/reference.rst b/doc/api.rst → doc/reference.rst
@@ -1,35 +1,35 @@
-migen API Documentation
-=======================
+API reference
+=============
 
-:mod:`fhdl.structure` Module
+:mod:`fhdl.structure` module
 ----------------------------
 
 .. automodule:: migen.fhdl.structure
         :members:
         :show-inheritance:
 
-:mod:`fhdl.bitcontainer` Module
+:mod:`fhdl.bitcontainer` module
 -------------------------------
 
 .. automodule:: migen.fhdl.bitcontainer
         :members:
         :show-inheritance:
 
-:mod:`genlib.fifo` Module
+:mod:`genlib.fifo` module
 -------------------------
 
 .. automodule:: migen.genlib.fifo
         :members:
         :show-inheritance:
 
-:mod:`genlib.coding` Module
+:mod:`genlib.coding` module
 ---------------------------
 
 .. automodule:: migen.genlib.coding
         :members:
         :show-inheritance:
 
-:mod:`genlib.sort` Module
+:mod:`genlib.sort` module
 -------------------------
 
 .. automodule:: migen.genlib.sort

diff --git a/doc/simulation.rst b/doc/simulation.rst
@@ -1,178 +1,6 @@
-.. _simulating:
-
 Simulating a Migen design
 #########################
 
-Migen allows you to easily simulate your FHDL design and interface it with arbitrary Python code.
-
-To interpret the design, the FHDL structure is simply converted into Verilog and then simulated using an external program (e.g. Icarus Verilog). This is is intrinsically compatible with VHDL/Verilog instantiations from Migen and maximizes software reuse.
-
-To interface the external simulator to Python, a VPI task is called at each clock cycle and implement the test bench functionality proper - which can be fully written in Python.
-
-Signals inside the simulator can be read and written using VPI as well. This is how the Python test bench generates stimulus and obtains the values of signals for processing.
-
-.. _vpisetup:
-
-Installing the VPI module
-*************************
-
-To communicate with the external simulator, Migen uses a UNIX domain socket and a custom protocol which is handled by a VPI plug-in (written in C) on the simulator side.
-
-To build and install this plug-in, run the following commands from the ``vpi`` directory: ::
-
-  make [INCDIRS=-I/usr/...]
-  make install [INSTDIR=/usr/...]
-
-The variable ``INCDIRS`` (default: empty) can be used to give a list of paths where to search for the include files. This is useful considering that different Linux distributions put the ``vpi_user.h`` file in various locations.
-
-The variable ``INSTDIR`` (default: ``/usr/lib/ivl``) specifies where the ``migensim.vpi`` file is to be installed.
-
-This plug-in is designed for Icarus Verilog, but can probably be used with most Verilog simulators with minor modifications.
-
-The generic simulator object
-****************************
-
-The generic simulator object (``migen.sim.generic.Simulator``) is the central component of the simulation.
-
-Creating a simulator object
-===========================
-
-The constructor of the ``Simulator`` object takes the following parameters:
-
-#. The module to simulate.
-#. A top-level object (see :ref:`toplevel`). With the default value of ``None``, the simulator creates a default top-level object itself.
-#. A simulator runner object (see :ref:`simrunner`). With the default value of ``None``, Icarus Verilog is used with the default parameters.
-#. The name of the UNIX domain socket used to communicate with the external simulator through the VPI plug-in (default: "simsocket").
-#. Additional keyword arguments (if any) are passed to the Verilog conversion function.
-
-For proper initialization and clean-up, the simulator object should be used as a context manager, e.g. ::
-
-  with Simulator(tb) as s:
-    s.run()
-
-Running the simulation
-======================
-
-Running the simulation is achieved by calling the ``run`` method of the ``Simulator`` object.
-
-It takes an optional parameter ``ncycles`` that defines the maximum number of clock cycles that this call simulates. The default value of ``None`` sets no cycle limit.
-
-The cycle counter
-=================
-
-Simulation functions can read the current simulator cycle by reading the ``cycle_counter`` property of the ``Simulator``. The cycle counter's value is 0 for the cycle immediately following the reset cycle.
-
-Simplified simulation set-up
-============================
-
-Most simulations are run in the same way and do not need the slightly heavy syntax needed to create and run a Simulator object. There is a function that exposes the most common features with a simpler syntax: ::
-
-  run_simulation(module, ncycles=None, vcd_name=None, keep_files=False)
-
-Module-level simulation API
-***************************
-
-Simulation functions and generators
-===================================
-
-Whenever a ``Module`` declares a ``do_simulation`` method, it is executed at each cycle and can manipulate values from signal and memories (as explained in the next section).
-
-Instead of defining such a method, ``Modules`` can declare a ``gen_simulation`` generator that is initialized at the beginning of the simulation, and yields (usually multiple times) to proceed to the next simulation cycle.
-
-Simulation generators can yield an integer in order to wait for that number of cycles, or yield nothing (``None``) to wait for 1 cycle.
-
-Reading and writing values
-===========================
-
-Simulation functions and generators take as parameter a special object that gives access to the values of the signals of the current module using the regular Python read/write syntax. Nested objects, lists and dictionaries containing signals are supported, as well as Migen memories, for reading and writing.
-
-Here are some examples: ::
-
-  def do_simulation(self, selfp):
-    selfp.foo = 42
-    self.last_foo_value = selfp.foo
-    selfp.dut.banks[2].bar["foo"] = 1
-    self.last_memory_data = selfp.dut.mem[self.memory_index]
-
-The semantics of reads and writes (respectively immediately before and after the clock edge) match those of the non-blocking assignment in Verilog. Note that because of Verilog's design, reading "variable" signals (i.e. written to using blocking assignment) directly may give unexpected and non-deterministic results and is not supported. You should instead read the values of variables after they have gone through a non-blocking assignment in the same ``always`` block.
-
-Those constructs are syntactic sugar for calling the ``Simulator`` object's methods ``rd`` and ``wr``, that respectively read and write data from and to the simulated design. The simulator object can be accessed as ``selfp.simulator``, and for special cases it is sometimes desirable to call the lower-level methods directly.
-
-The ``rd`` method takes the FHDL ``Signal`` object to read and returns its value as a Python integer. The returned integer is the value of the signal immediately before the clock edge.
-
-The ``wr`` method takes a ``Signal`` object and the value to write as a Python integer. The signal takes the new value immediately after the clock edge.
-
-References to FHDL ``Memory`` objects can also be passed to the ``rd`` and ``wr`` methods. In this case, they take an additional parameter for the memory address.
-
-Simulation termination management
-=================================
-
-Simulation functions and generators can raise the ``StopSimulation`` exception. It is automatically raised when a simulation generator is exhausted. This exception disables the current simulation function, i.e. it is no longer run by the simulator. The simulation is over when all simulation functions are disabled (or the specified maximum number of cycles, if any, has been reached - whichever comes first).
-
-Some simulation modules only respond to external stimuli - e.g. the ``bus.wishbone.Tap`` that snoops on bus transactions and prints them on the console - and have simulation functions that never end. To deal with those, the new API introduces "passive" simulation functions that are not taken into account when deciding to continue to run the simulation. A simulation function is declared passive by setting a "passive" attribute on it that evaluates to True. Raising ``StopSimulation`` in such a function still makes the simulator stop running it for the rest of the simulation.
-
-When starting the simulation of a design that contains no simulation functions or only passive simulation functions, the simulation will continue until the specified number of cycles is reached. The ``ncycles`` parameter is mandatory in this case.
-
-.. _simrunner:
-
-The external simulator runner
-*****************************
-
-Role
-====
-
-The runner object is responsible for starting the external simulator, loading the VPI module, and feeding the generated Verilog into the simulator.
-
-It must implement a ``start`` method, called by the ``Simulator``, which takes two strings as parameters. They contain respectively the Verilog source of the top-level design and the converted module.
-
-Icarus Verilog support
-======================
-
-Migen comes with a ``migen.sim.icarus.Runner`` object that supports Icarus Verilog.
-
-Its constructor has the following optional parameters:
-
-#. ``extra_files`` (default: ``None``): lists additional Verilog files to simulate.
-#. ``top_file`` (default: "migensim_top.v"): name of the temporary file containing the top-level.
-#. ``dut_file`` (default: "migensim_dut.v"): name of the temporary file containing the converted fragment.
-#. ``vvp_file`` (default: ``None``): name of the temporary file compiled by Icarus Verilog. When ``None``, becomes ``dut_file + "vp"``.
-#. ``keep_files`` (default: ``False``): do not delete temporary files. Useful for debugging.
-
-.. _toplevel:
-
-The top-level object
-********************
-
-Role of the top-level object
-============================
-
-The top-level object is responsible for generating the Verilog source for the top-level test bench.
-
-It must implement a method ``get`` that takes as parameter the name of the UNIX socket the VPI plugin should connect to, and returns the full Verilog source as a string.
-
-It must have the following attributes (which are read by the ``Simulator`` object):
-
-* ``clk_name``: name of the clock signal.
-* ``rst_name``: name of the reset signal.
-* ``dut_type``: module type of the converted fragment.
-* ``dut_name``: name used for instantiating the converted fragment.
-* ``top_name``: name/module type of the top-level design.
-
-Role of the generated Verilog
-=============================
-
-The generated Verilog must:
-
-#. instantiate the converted fragment and connect its clock and reset ports.
-#. produce a running clock signal.
-#. assert the reset signal for the first cycle and deassert it immediately after.
-#. at the beginning, call the task ``$migensim_connect`` with the UNIX socket name as parameter.
-#. at each rising clock edge, call the task ``$migensim_tick``. It is an error to call ``$migensim_tick`` before a call to ``$migensim_connect``.
-#. set up the optional VCD output file.
-
-The generic top-level object
-============================
-
-Migen comes with a ``migen.sim.generic.TopLevel`` object that implements the above behaviour. It should be usable in the majority of cases.
+Migen allows you to easily simulate your FHDL design and interface it with arbitrary Python code. The simulator is written in pure Python and interprets the FHDL structure directly without using an external Verilog simulator.
 
-The main parameters of its constructor are the output VCD file (default: ``None``) and the levels of hierarchy that must be present in the VCD (default: 1).
+[To be rewritten]
diff --git a/doc/synthesis.rst b/doc/synthesis.rst
@@ -0,0 +1,4 @@
+Synthesizing a Migen design
+###########################
+
+[To be written]
diff --git a/examples/basic/arrays.py b/examples/basic/arrays.py
@@ -1,4 +1,4 @@
-from migen.fhdl.std import *
+from migen import *
 from migen.fhdl import verilog
 
 
@@ -24,4 +24,5 @@ def __init__(self):
         outa = Array(Signal() for a in range(dy))
         self.specials += Instance("test", o_O=outa[y], i_I=ina[x])
 
-print(verilog.convert(Example()))
+if __name__ == "__main__":
+    print(verilog.convert(Example()))
diff --git a/examples/basic/complex.py b/examples/basic/complex.py
diff --git a/examples/basic/fsm.py b/examples/basic/fsm.py
@@ -1,12 +1,11 @@
-from migen.fhdl.std import *
+from migen import *
 from migen.fhdl import verilog
-from migen.genlib.fsm import FSM, NextState, NextValue
-
 
 class Example(Module):
     def __init__(self):
         self.s = Signal()
         self.counter = Signal(8)
+        x = Array(Signal(name="a") for i in range(7))
 
         myfsm = FSM()
         self.submodules += myfsm
@@ -18,6 +17,7 @@ def __init__(self):
         myfsm.act("BAR",
             self.s.eq(0),
             NextValue(self.counter, self.counter + 1),
+            NextValue(x[self.counter], 89),
             NextState("FOO")
         )
 
@@ -26,5 +26,6 @@ def __init__(self):
         self.bl = myfsm.before_leaving("FOO")
         self.al = myfsm.after_leaving("FOO")
 
-example = Example()
-print(verilog.convert(example, {example.s, example.counter, example.be, example.ae, example.bl, example.al}))
+if __name__ == "__main__":
+    example = Example()
+    print(verilog.convert(example, {example.s, example.counter, example.be, example.ae, example.bl, example.al}))
diff --git a/examples/basic/graycounter.py b/examples/basic/graycounter.py
@@ -1,20 +1,18 @@
 from random import Random
 
-from migen.fhdl.std import *
+from migen import *
 from migen.genlib.cdc import GrayCounter
-from migen.sim.generic import run_simulation
 
 
-class TB(Module):
-    def __init__(self, width=3):
-        self.width = width
-        self.submodules.gc = GrayCounter(self.width)
-        self.prng = Random(7345)
+def tb(dut):
+    prng = Random(7345)
+    for i in range(35):
+        print("{0:0{1}b} CE={2} bin={3}".format((yield dut.q),
+            len(dut.q), (yield dut.ce), (yield dut.q_binary)))
+        yield dut.ce.eq(prng.getrandbits(1))
+        yield
 
-    def do_simulation(self, selfp):
-        print("{0:0{1}b} CE={2} bin={3}".format(selfp.gc.q,
-            self.width, selfp.gc.ce, selfp.gc.q_binary))
-        selfp.gc.ce = self.prng.getrandbits(1)
 
 if __name__ == "__main__":
-    run_simulation(TB(), ncycles=35)
+    dut = GrayCounter(3)
+    run_simulation(dut, tb(dut), vcd_name="graycounter.vcd")
diff --git a/examples/basic/hamming.py b/examples/basic/hamming.py
diff --git a/examples/basic/instance.py b/examples/basic/instance.py
@@ -1,7 +1,6 @@
 import subprocess
 
-from migen.fhdl.std import *
-from migen.fhdl.specials import Instance
+from migen import *
 from migen.fhdl.verilog import convert
 
 

diff --git a/examples/basic/local_cd.py b/examples/basic/local_cd.py
@@ -1,4 +1,4 @@
-from migen.fhdl.std import *
+from migen import *
 from migen.fhdl import verilog
 from migen.genlib.divider import Divider
 
@@ -14,5 +14,6 @@ def __init__(self):
         self.submodules.foo = CDM()
         self.submodules.bar = CDM()
 
-mm = MultiMod()
-print(verilog.convert(mm, {mm.foo.cd_sys.clk, mm.bar.cd_sys.clk}))
+if __name__ == "__main__":
+    mm = MultiMod()
+    print(verilog.convert(mm, {mm.foo.cd_sys.clk, mm.bar.cd_sys.clk}))
diff --git a/examples/basic/memory.py b/examples/basic/memory.py
@@ -1,4 +1,4 @@
-from migen.fhdl.std import *
+from migen import *
 from migen.fhdl import verilog
 
 
@@ -11,5 +11,7 @@ def __init__(self):
         self.ios = {p1.adr, p1.dat_r, p1.we, p1.dat_w,
             p2.adr, p2.dat_r, p2.re}
 
-example = Example()
-print(verilog.convert(example, example.ios))
+
+if __name__ == "__main__":
+    example = Example()
+    print(verilog.convert(example, example.ios))
diff --git a/examples/basic/namer.py b/examples/basic/namer.py
@@ -1,6 +1,8 @@
-from migen.fhdl.std import *
+from migen import *
 from migen.fhdl import verilog
-from migen.genlib.misc import optree
+
+from functools import reduce
+from operator import or_
 
 
 def gen_list(n):
@@ -37,6 +39,6 @@ def __init__(self):
         for lst in [a, b, c]:
             for obj in lst:
                 allsigs.extend(obj.sigs)
-        self.comb += output.eq(optree("|", allsigs))
+        self.comb += output.eq(reduce(or_, allsigs))
 
 print(verilog.convert(Example()))
diff --git a/examples/basic/psync.py b/examples/basic/psync.py
@@ -1,4 +1,4 @@
-from migen.fhdl.std import *
+from migen import *
 from migen.fhdl.specials import SynthesisDirective
 from migen.fhdl import verilog
 from migen.genlib.cdc import *
@@ -16,6 +16,8 @@ class XilinxMultiReg:
     def lower(dr):
         return XilinxMultiRegImpl(dr.i, dr.o, dr.odomain, dr.n)
 
-ps = PulseSynchronizer("from", "to")
-v = verilog.convert(ps, {ps.i, ps.o}, special_overrides={MultiReg: XilinxMultiReg})
-print(v)
+
+if __name__ == "__main__":
+    ps = PulseSynchronizer("from", "to")
+    v = verilog.convert(ps, {ps.i, ps.o}, special_overrides={MultiReg: XilinxMultiReg})
+    print(v)
diff --git a/examples/basic/record.py b/examples/basic/record.py
@@ -1,6 +1,6 @@
-from migen.fhdl.std import *
+from migen import *
 from migen.fhdl import verilog
-from migen.genlib.record import *
+
 
 L = [
     ("position", [
@@ -19,6 +19,8 @@ def __init__(self):
         slave = Record(L)
         self.comb += master.connect(slave)
 
-print(verilog.convert(Test()))
-print(layout_len(L))
-print(layout_partial(L, "position/x", "color"))
+
+if __name__ == "__main__":
+    print(verilog.convert(Test()))
+    print(layout_len(L))
+    print(layout_partial(L, "position/x", "color"))
diff --git a/examples/basic/reslice.py b/examples/basic/reslice.py
@@ -1,4 +1,4 @@
-from migen.fhdl.std import *
+from migen import *
 from migen.fhdl import verilog
 
 
@@ -14,4 +14,6 @@ def __init__(self):
         self.comb += s3.eq(0)
         self.comb += d.eq(Cat(d[::-1], Cat(s1[:1], s3[-4:])[:3]))
 
-print(verilog.convert(Example()))
+
+if __name__ == "__main__":
+    print(verilog.convert(Example()))
diff --git a/examples/basic/simple_gpio.py b/examples/basic/simple_gpio.py
diff --git a/examples/basic/tristate.py b/examples/basic/tristate.py
@@ -1,4 +1,4 @@
-from migen.fhdl.std import *
+from migen import *
 from migen.fhdl import verilog
 
 
@@ -8,5 +8,6 @@ def __init__(self, n=6):
         self.t = TSTriple(n)
         self.specials += self.t.get_tristate(self.pad)
 
-e = Example()
-print(verilog.convert(e, ios={e.pad, e.t.o, e.t.oe, e.t.i}))
+if __name__ == "__main__":
+    e = Example()
+    print(verilog.convert(e, ios={e.pad, e.t.o, e.t.oe, e.t.i}))
diff --git a/examples/basic/two_dividers.py b/examples/basic/two_dividers.py
@@ -1,4 +1,4 @@
-from migen.fhdl.std import *
+from migen import *
 from migen.fhdl import verilog
 from migen.genlib import divider
 
@@ -14,5 +14,6 @@ def __init__(self, width):
             d1.ready_o, d1.quotient_o, d1.remainder_o, d1.start_i, d1.dividend_i, d1.divisor_i,
             d2.ready_o, d2.quotient_o, d2.remainder_o, d2.start_i, d2.dividend_i, d2.divisor_i}
 
-example = Example(16)
-print(verilog.convert(example, example.ios | {example.ce, example.reset}))
+if __name__ == "__main__":
+    example = Example(16)
+    print(verilog.convert(example, example.ios | {example.ce, example.reset}))
diff --git a/examples/dataflow/dma.py b/examples/dataflow/dma.py
diff --git a/examples/dataflow/misc.py b/examples/dataflow/misc.py
diff --git a/examples/dataflow/structuring.py b/examples/dataflow/structuring.py
diff --git a/examples/sim/abstract_transactions_wb.py b/examples/sim/abstract_transactions_wb.py
diff --git a/examples/sim/basic1.py b/examples/sim/basic1.py
@@ -1,9 +1,7 @@
-from migen.fhdl.std import *
-from migen.sim.generic import run_simulation
+from migen import *
 
 
-# Our simple counter, which increments at every cycle
-# and prints its current value in simulation.
+# Our simple counter, which increments at every cycle.
 class Counter(Module):
     def __init__(self):
         self.count = Signal(4)
@@ -12,18 +10,20 @@ def __init__(self):
         # We do it with convertible/synthesizable FHDL code.
         self.sync += self.count.eq(self.count + 1)
 
-    # This function will be called at every cycle.
-    def do_simulation(self, selfp):
-        # Simply read the count signal and print it.
-        # The output is:
-        # Count: 0
-        # Count: 1
-        # Count: 2
-        # ...
-        print("Count: " + str(selfp.count))
+
+# Simply read the count signal and print it.
+# The output is:
+# Count: 0
+# Count: 1
+# Count: 2
+# ...
+def counter_test(dut):
+    for i in range(20):
+        print((yield dut.count))  # read and print
+        yield  # next clock cycle
+    # simulation ends with this generator
+
 
 if __name__ == "__main__":
     dut = Counter()
-    # Since we do not use StopSimulation, limit the simulation
-    # to some number of cycles.
-    run_simulation(dut, ncycles=20)
+    run_simulation(dut, counter_test(dut), vcd_name="basic1.vcd")
diff --git a/examples/sim/basic2.py b/examples/sim/basic2.py
@@ -1,5 +1,4 @@
-from migen.fhdl.std import *
-from migen.sim.generic import run_simulation
+from migen import *
 
 
 # A slightly more elaborate counter.
@@ -13,15 +12,17 @@ def __init__(self):
 
         self.sync += If(self.ce, self.count.eq(self.count + 1))
 
-    def do_simulation(self, selfp):
+
+def counter_test(dut):
+    for cycle in range(20):
         # Only assert CE every second cycle.
         # => each counter value is held for two cycles.
-        if selfp.simulator.cycle_counter % 2:
-            selfp.ce = 0  # This is how you write to a signal.
+        if cycle % 2:
+            yield dut.ce.eq(0)  # This is how you write to a signal.
         else:
-            selfp.ce = 1
-        print("Cycle: " + str(selfp.simulator.cycle_counter) + " Count: " + \
-            str(selfp.count))
+            yield dut.ce.eq(1)
+        print("Cycle: {} Count: {}".format(cycle, (yield dut.count)))
+        yield
 
 # Output is:
 # Cycle: 0 Count: -5
@@ -33,5 +34,4 @@ def do_simulation(self, selfp):
 
 if __name__ == "__main__":
     dut = Counter()
-    # Demonstrate VCD output
-    run_simulation(dut, vcd_name="my.vcd", ncycles=20)
+    run_simulation(dut, counter_test(dut), vcd_name="basic2.vcd")
diff --git a/examples/sim/dataflow.py b/examples/sim/dataflow.py
diff --git a/examples/sim/fir.py b/examples/sim/fir.py
@@ -1,11 +1,12 @@
+from functools import reduce
+from operator import add
+
 from math import cos, pi
 from scipy import signal
 import matplotlib.pyplot as plt
 
-from migen.fhdl.std import *
+from migen import *
 from migen.fhdl import verilog
-from migen.genlib.misc import optree
-from migen.sim.generic import run_simulation
 
 
 # A synthesizable FIR filter.
@@ -27,25 +28,21 @@ def __init__(self, coef, wsize=16):
             c_fp = int(c*2**(self.wsize - 1))
             muls.append(c_fp*sreg)
         sum_full = Signal((2*self.wsize-1, True))
-        self.sync += sum_full.eq(optree("+", muls))
-        self.comb += self.o.eq(sum_full[self.wsize-1:])
+        self.sync += sum_full.eq(reduce(add, muls))
+        self.comb += self.o.eq(sum_full >> self.wsize-1)
 
 
 # A test bench for our FIR filter.
 # Generates a sine wave at the input and records the output.
-class TB(Module):
-    def __init__(self, coef, frequency):
-        self.submodules.fir = FIR(coef)
-        self.frequency = frequency
-        self.inputs = []
-        self.outputs = []
+def fir_tb(dut, frequency, inputs, outputs):
+    f = 2**(dut.wsize - 1)
+    for cycle in range(200):
+        v = 0.1*cos(2*pi*frequency*cycle)
+        yield dut.i.eq(int(f*v))
+        inputs.append(v)
+        outputs.append((yield dut.o)/f)
+        yield
 
-    def do_simulation(self, selfp):
-        f = 2**(self.fir.wsize - 1)
-        v = 0.1*cos(2*pi*self.frequency*selfp.simulator.cycle_counter)
-        selfp.fir.i = int(f*v)
-        self.inputs.append(v)
-        self.outputs.append(selfp.fir.o/f)
 
 if __name__ == "__main__":
     # Compute filter coefficients with SciPy.
@@ -56,10 +53,9 @@ def do_simulation(self, selfp):
     in_signals = []
     out_signals = []
     for frequency in [0.05, 0.1, 0.25]:
-        tb = TB(coef, frequency)
-        run_simulation(tb, ncycles=200)
-        in_signals += tb.inputs
-        out_signals += tb.outputs
+        dut = FIR(coef)
+        tb = fir_tb(dut, frequency, in_signals, out_signals)
+        run_simulation(dut, tb)
 
     # Plot data from the input and output waveforms.
     plt.plot(in_signals)

diff --git a/examples/sim/memory.py b/examples/sim/memory.py
@@ -1,5 +1,4 @@
-from migen.fhdl.std import *
-from migen.sim.generic import run_simulation
+from migen import *
 
 
 class Mem(Module):
@@ -8,19 +7,20 @@ def __init__(self):
         # from 0 to 19.
         self.specials.mem = Memory(16, 2**12, init=list(range(20)))
 
-    def do_simulation(self, selfp):
-        # Read the memory. Use the cycle counter as address.
-        value = selfp.mem[selfp.simulator.cycle_counter]
-        # Print the result. Output is:
-        # 0
-        # 1
-        # 2
-        # ...
+
+def memory_test(dut):
+    # write (only first 5 values)
+    for i in range(5):
+        yield dut.mem[i].eq(42 + i)
+    # remember: values are written after the tick, and read before the tick.
+    # wait one tick for the memory to update.
+    yield
+    # read what we have written, plus some initialization data
+    for i in range(10):
+        value = yield dut.mem[i]
         print(value)
-        # Raising StopSimulation disables the current (and here, only one)
-        # simulation function. Simulator stops when all functions are disabled.
-        if value == 10:
-            raise StopSimulation
+
 
 if __name__ == "__main__":
-    run_simulation(Mem())
+    dut = Mem()
+    run_simulation(dut, memory_test(dut))
diff --git a/mibuild/altera/__init__.py b/mibuild/altera/__init__.py
diff --git a/mibuild/lattice/__init__.py b/mibuild/lattice/__init__.py
diff --git a/mibuild/sim/__init__.py b/mibuild/sim/__init__.py
diff --git a/mibuild/xilinx/__init__.py b/mibuild/xilinx/__init__.py
diff --git a/migen/__init__.py b/migen/__init__.py
@@ -0,0 +1,10 @@
+from migen.fhdl.structure import *
+from migen.fhdl.module import *
+from migen.fhdl.specials import *
+from migen.fhdl.bitcontainer import *
+from migen.fhdl.decorators import *
+
+from migen.sim import *
+
+from migen.genlib.record import *
+from migen.genlib.fsm import *
diff --git a/migen/actorlib/__init__.py b/migen/actorlib/__init__.py
diff --git a/migen/actorlib/dma_wishbone.py b/migen/actorlib/dma_wishbone.py
diff --git a/migen/actorlib/fifo.py b/migen/actorlib/fifo.py
diff --git a/migen/actorlib/misc.py b/migen/actorlib/misc.py
diff --git a/migen/actorlib/packet.py b/migen/actorlib/packet.py
diff --git a/migen/actorlib/sim.py b/migen/actorlib/sim.py
diff --git a/migen/actorlib/spi.py b/migen/actorlib/spi.py
diff --git a/migen/actorlib/structuring.py b/migen/actorlib/structuring.py
diff --git a/migen/bank/__init__.py b/migen/bank/__init__.py
diff --git a/migen/bank/bank.py b/migen/bank/bank.py
diff --git a/migen/bank/csrgen.py b/migen/bank/csrgen.py
diff --git a/migen/bank/description.py b/migen/bank/description.py
diff --git a/migen/bank/eventmanager.py b/migen/bank/eventmanager.py