From 74b0cfc83b360c335304f07ed02a52a988381195 Mon Sep 17 00:00:00 2001 From: Sebastien Bourdeauducq Date: Sun, 20 Sep 2015 16:10:40 +0800 Subject: [PATCH] doc: remove outdated or moved parts, cleanup --- doc/actors_endpoints.dia | Bin 1634 -> 0 bytes doc/actors_endpoints.png | Bin 112180 -> 0 bytes doc/bus.rst | 149 -------------- doc/casestudies.rst | 58 ------ doc/conf.py | 10 +- doc/dataflow.rst | 342 --------------------------------- doc/fbflow.dia | Bin 2026 -> 0 bytes doc/fbflow.png | Bin 86187 -> 0 bytes doc/fhdl.rst | 31 +-- doc/index.rst | 6 +- doc/introduction.rst | 10 +- doc/{api.rst => reference.rst} | 14 +- doc/simulation.rst | 174 +---------------- doc/synthesis.rst | 4 + setup.py | 2 +- 15 files changed, 41 insertions(+), 759 deletions(-) delete mode 100644 doc/actors_endpoints.dia delete mode 100644 doc/actors_endpoints.png delete mode 100644 doc/bus.rst delete mode 100644 doc/casestudies.rst delete mode 100644 doc/dataflow.rst delete mode 100644 doc/fbflow.dia delete mode 100644 doc/fbflow.png rename doc/{api.rst => reference.rst} (74%) create mode 100644 doc/synthesis.rst diff --git a/doc/actors_endpoints.dia b/doc/actors_endpoints.dia deleted file mode 100644 index 7ab569a1c8963086a1c8eacd0ee10cd2b5aa950c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1634 zcmV-o2A%mIiwFP!000021MQs6bDKC6!0-7h7Y5M|v%4v44JWDxG0&l~a7SR>E(>*%>wMgPkg=Y;GvT`(_U^jEWJQyhe}5xr(fRqSdVr-3NKx9g)K4RW&2y)tE~R1}I9 z_aDA9&RO!Is8)G$C$Fxujf(h+CW|0C)+PEUEII=kHX_;K0Bj=@y6B}}E?4Ibt1cW? zT{5h?Af2t_geNrM$11%z4jGLKtvuPV_IlDe4aE>U)hy6n`a{5Ze5U>nG)&*pfa3J4 z#a(K>izM(*8}C7h1}RU0&zG}jN!?XQ-%67H7^Hz0vbx#_5${d>wjc4;yOVqH-Q^ue zLm{nkitsVBnSJ>bvDgGYOV13m!!iw$mSwT&xn8f9duzuOrz#V6t|FvcmXzYZ?WSt2 zyuqc%(de89k1yZ$`Xu)LVRK$K_6MhtPZMAJsC|o{^&N)@3JLr>{V(&dv#QM#!h|0@ z>aBIW8&YTjtF1rw9Zj-5uPQnbm8a1nWTkj$5PJf|$1Nm=DgHFYXFG)~WUJXcPNHK* z=%qoq{M?5eH|o`YI2~j!S+H30X5qMw_~>N~KKGz04W>pj-vnzs|*Dkp>!={lrAqL``wT>-1&kwFkNi z!mX$ljZ$4p`8M;&!kZSC{>j2e#)CQCpExeB!I7cYc@lBAEEkG{SO5cJTitXXj=iSw zXCN^=x+$t!e&a);X?9a2$a)d2SpCgp(PmWxMW?W+Zf3vCDjxGHRqbL|l{b3Sc`RJ0 znEvA^Judnv`7UuRA8eSGDshgVabJzJhA~%wwjV*M!uE;Ed$#?#Whr1qjp51Y%N70#|V)F zUj;dU*#mP(4Q!BIV549TK;$!r%*cjfj^C9z0O$ca03HB3fO`NP0FMMZg6Nmpy)i6u zh@qm8W1PqVuCrkjz#iNnlAn@-_Ht6J0di81N=i}7DH5my^^lc<Bqe z)>GssrXZD>GG5ZS&OT9K^^lt)mo(5GY2?`{$daF(B9k;!c;mMXZ`eKLryw*yf(n8~ zc%#fuK}dx+RCuFdJVF)T7%OyKXQwD|ddNJQzzJMutQ3aXV+W-gxF1`h> zVLBLQ3y3ChTYAE*H)k*2>4MfZEM>NT1cw_x$C%_csS`=e@uA53uc~^~GNR037@bGynhq diff --git a/doc/actors_endpoints.png b/doc/actors_endpoints.png deleted file mode 100644 index 3eb99c08c2a63614bd80cb30a59cbacc6952730b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 112180 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 LE*D??^Zx$=dmEyu diff --git a/doc/bus.rst b/doc/bus.rst deleted file mode 100644 index b9c853ca..00000000 --- a/doc/bus.rst +++ /dev/null @@ -1,149 +0,0 @@ -Bus support -########### - -Migen Bus contains classes providing a common structure for master and slave interfaces of the following buses: - -* Wishbone [wishbone]_, the general purpose bus recommended by Opencores. -* CSR-2 (see :ref:`csr2`), a low-bandwidth, resource-sensitive bus designed for accessing the configuration and status registers of cores from software. -* LASMIbus (see :ref:`lasmi`), a bus optimized for use with a high-performance frequency-ratio SDRAM controller. -* DFI [dfi]_ (partial), a standard interface protocol between memory controller logic and PHY interfaces. - -.. [wishbone] http://cdn.opencores.org/downloads/wbspec_b4.pdf -.. [dfi] http://www.ddr-phy.org/ - -It also provides interconnect components for these buses, such as arbiters and address decoders. The strength of the Migen procedurally generated logic can be illustrated by the following example: :: - - self.submodules.wbcon = wishbone.InterconnectShared( - [cpu.ibus, cpu.dbus, ethernet.dma, audio.dma], - [(lambda a: a[27:] == 0, norflash.bus), - (lambda a: a[27:] == 1, wishbone2lasmi.wishbone), - (lambda a: a[27:] == 3, wishbone2csr.wishbone)]) - -In this example, the interconnect component generates a 4-way round-robin arbiter, multiplexes the master bus signals into a shared bus, and connects all slave interfaces to the shared bus, inserting the address decoder logic in the bus cycle qualification signals and multiplexing the data return path. It can recognize the signals in each core's bus interface thanks to the common structure mandated by Migen Bus. All this happens automatically, using only that much user code. - - -Configuration and Status Registers -********************************** - -.. _csr2: - -CSR-2 bus -========= -The CSR-2 bus is a low-bandwidth, resource-sensitive bus designed for accessing the configuration and status registers of cores from software. - -It is the successor of the CSR bus used in Milkymist SoC 1.x, with two modifications: - -* Up to 32 slave devices (instead of 16) -* Data words are 8 bits (instead of 32) - -.. _bank: - -Generating register banks -========================= -Migen Bank is a system comparable to wishbone-gen [wbgen]_, which automates the creation of configuration and status register banks and interrupt/event managers implemented in cores. - -.. [wbgen] http://www.ohwr.org/projects/wishbone-gen - -Bank takes a description made up of a list of registers and generates logic implementing it with a slave interface compatible with Migen Bus. - -The lowest-level description of a register is provided by the ``CSR`` class, which maps to the value at a single address on the target bus. The width of the register needs to be less than or equal to the bus word width. All accesses are atomic. It has the following signal properties to interface to the user design: - -* ``r``, which contains the data written from the bus interface. -* ``re``, which is the strobe signal for ``r``. It is active for one cycle, after or during a write from the bus. ``r`` is only valid when ``re`` is high. -* ``w``, which must provide at all times the value to be read from the bus. - -Names of CSRs can be omitted if they can be extracted from the variable name. When using this automatic naming feature, prefixes ``_``, ``r_`` and ``_r_`` are removed. - -Compound CSRs (which are transformed into ``CSR`` plus additional logic for implementation) provide additional features optimized for common applications. - -The ``CSRStatus`` class is meant to be used as a status register that is read-only from the CPU. The user design is expected to drive its ``status`` signal. The advantage of using ``CSRStatus`` instead of using ``CSR`` and driving ``w`` is that the width of ``CSRStatus`` can be arbitrary. Status registers larger than the bus word width are automatically broken down into several ``CSR`` registers to span several addresses. Be careful, though: the atomicity of reads is not guaranteed. - -The ``CSRStorage`` class provides a memory location that can be read and written by the CPU, and read and optionally written by the design. It can also span several CSR addresses. An optional mechanism for atomic CPU writes is provided; when enabled, writes to the first CSR addresses go to a back-buffer whose contents are atomically copied to the main buffer when the last address is written. When ``CSRStorage`` can be written to by the design, the atomicity of reads by the CPU is not guaranteed. - -A module can provide bus-independent CSRs by implementing a ``get_csrs`` method that returns a list of instances of the classes described above. Similary, bus-independent memories can be returned as a list by a ``get_memories`` method. - -To avoid listing those manually, a module can inherit from the ``AutoCSR`` class, which provides ``get_csrs`` and ``get_memories`` methods that scan for CSR and memory attributes and return their list. If the module has child objects that implement ``get_csrs`` or ``get_memories``, they will be called by the ``AutoCSR`` methods and their CSR and memories added to the lists returned, with the child objects' names as prefixes. - -Generating interrupt controllers -================================ -The event manager provides a systematic way to generate standard interrupt controllers. - -Its constructor takes as parameters one or several *event sources*. An event source is an instance of either: - -* ``EventSourcePulse``, which contains a signal ``trigger`` that generates an event when high. The event stays asserted after the ``trigger`` signal goes low, and until software acknowledges it. An example use is to pulse ``trigger`` high for 1 cycle after the reception of a character in a UART. -* ``EventSourceProcess``, which contains a signal ``trigger`` that generates an event on its falling edge. The purpose of this event source is to monitor the status of processes and generate an interrupt on their completion. The signal ``trigger`` can be connected to the ``busy`` signal of a dataflow actor, for example. -* ``EventSourceLevel``, whose ``trigger`` contains the instantaneous state of the event. It must be set and released by the user design. For example, a DMA controller with several slots can use this event source to signal that one or more slots require CPU attention. - -The ``EventManager`` provides a signal ``irq`` which is driven high whenever there is a pending and unmasked event. It is typically connected to an interrupt line of a CPU. - -The ``EventManager`` provides a method ``get_csrs``, that returns a bus-independent list of CSRs to be used with Migen Bank as explained above. Each event source is assigned one bit in each of those registers. They are: - -* ``status``: contains the current level of the trigger line of ``EventSourceProcess`` and ``EventSourceLevel`` sources. It is 0 for ``EventSourcePulse``. This register is read-only. -* ``pending``: contains the currently asserted events. Writing 1 to the bit assigned to an event clears it. -* ``enable``: defines which asserted events will cause the ``irq`` line to be asserted. This register is read-write. - -.. _lasmi: - -Lightweight Advanced System Memory Infrastructure -************************************************* - -Rationale -========= -The lagging of the DRAM semiconductor processes behind the logic processes has led the industry into a subtle way of ever increasing memory performance. - -Modern devices feature a DRAM core running at a fraction of the logic frequency, whose wide data bus is serialized and deserialized to and from the faster clock domain. Further, the presence of more banks increases page hit rate and provides opportunities for parallel execution of commands to different banks. - -A first-generation SDR-133 SDRAM chip runs both DRAM, I/O and logic at 133MHz and features 4 banks. A 16-bit chip has a 16-bit DRAM core. - -A newer DDR3-1066 chip still runs the DRAM core at 133MHz, but the logic at 533MHz (4 times the DRAM frequency) and the I/O at 1066Mt/s (8 times the DRAM frequency). A 16-bit chip has a 128-bit internal DRAM core. Such a device features 8 banks. Note that the serialization also introduces multiplied delays (e.g. CAS latency) when measured in number of cycles of the logic clock. - -To take full advantage of these new architectures, the memory controller should be able to peek ahead at the incoming requests and service several of them in parallel, while respecting the various timing specifications of each DRAM bank and avoiding conflicts for the shared data lines. Going further in this direction, a controller able to complete transfers out of order can provide even more performance by: - -#. grouping requests by DRAM row, in order to minimize time spent on precharging and activating banks. -#. grouping requests by direction (read or write) in order to minimize delays introduced by bus turnaround and write recovery times. -#. being able to complete a request that hits a page earlier than a concurrent one which requires the cycling of another bank. - -The first two techniques are explained with more details in [drreorder]_. - -.. [drreorder] http://www.xilinx.com/txpatches/pub/documentation/misc/improving%20ddr%20sdram%20efficiency.pdf - -Migen and MiSoC implement their own bus, called LASMIbus, that features the last two techniques. Grouping by row had been previously explored with ASMI, but difficulties in achieving timing closure at reasonable latencies in FPGA combined with uncertain performance pay-off for some applications discouraged work in that direction. - -Topology and transactions -========================= -The LASMI consists of one or several memory controllers (e.g. LASMIcon from MiSoC), multiple masters, and crossbar interconnect. - -Each memory controller can expose several bank machines to the crossbar. This way, requests to different SDRAM banks can be processed in parallel. - -Transactions on LASMI work as follows: - -1. The master presents a valid address and write enable signals, and asserts its strobe signal. -2. The crossbar decodes the bank address and, in a multi-controller configuration, the controller address and connects the master to the appropriate bank machine. -3. The bank machine acknowledges the request from the master. The master can immediately issue a new request to the same bank machine, without waiting for data. -4. The bank machine sends data acknowledgements to the master, in the same order as it issued requests. After receiving a data acknowldegement, the master must either: - - * present valid data after a fixed number of cycles (for writes). Masters must hold their data lines at 0 at all other times so that they can be simply ORed for each controller to produce the final SDRAM write data. - * sample the data bus after a fixed number of cycles (for reads). - -5. In a multi-controller configuration, the crossbar multiplexes write and data signals to route data to and from the appropriate controller. - -When there are queued requests (i.e. more request acknowledgements than data acknowledgements), the bank machine asserts its ``lock`` signal which freezes the crossbar connection between the master and the bank machine. This simplifies two problems: - -#. Determining to which master a data acknowledgement from a bank machine should be sent. -#. Having to deal with a master queuing requests into multiple different bank machines which may collectively complete them in a different order than the master issued them. - -For each master, transactions are completed in-order by the memory system. Reordering may only occur between masters, e.g. a master issuing a request that hits a page may have it completed sooner than a master requesting earlier a precharge/activate cycle of another bank. - -It is suggested that memory controllers use an interface to a PHY compatible with DFI [dfi]_. The DFI clock can be the same as the LASMIbus clock, with optional serialization and deserialization taking place across the PHY, as specified in the DFI standard. - -SDRAM burst length and clock ratios -=================================== -A system using LASMI must set the SDRAM burst length B, the LASMIbus word width W and the ratio between the LASMIbus clock frequency Fa and the SDRAM I/O frequency Fi so that all data transfers last for exactly one LASMIbus cycle. - -More explicitly, these relations must be verified: - -B = Fi/Fa - -W = B*[number of SDRAM I/O pins] - -For DDR memories, the I/O frequency is twice the logic frequency. diff --git a/doc/casestudies.rst b/doc/casestudies.rst deleted file mode 100644 index 64e5dd38..00000000 --- a/doc/casestudies.rst +++ /dev/null @@ -1,58 +0,0 @@ -Case studies -############ - -A VGA framebuffer core -********************** - -Purpose -======= - -The purpose of the VGA framebuffer core is to scan a buffer in system memory and generate an appropriately timed video signal in order to display the picture from said buffer on a regular VGA monitor. - -The core is meant to be integrated in a SoC and is controllable by a CPU which can set parameters such as the framebuffer address, video resolution and timing parameters. - -This case study highlights what tools Migen provides to design such a core. - -Architecture -============ - -The framebuffer core is designed using the Migen dataflow system (see :ref:`dataflow`). Its block diagram is given in the figure below: - -.. figure:: fbflow.png - :scale: 50 % - - Data flow graph of the framebuffer core. - -Actors drawn with a blue background are designed specifically for the framebuffer cores, the others are generic actors from the Migen library. Migen also provides the interconnect logic between the actors. - -Frame initiator -=============== - -The frame initiator generates tokens that correspond each to one complete scan of the picture (active video, synchronization pulses, front and back porches). The token contains the address and the length of the framebuffer used for the active video region, and timing parameters to generate the synchronization and porches. - -Switching the framebuffer address (without tearing) is simply done by generating a token with the new address. Tearing will not occur since the new token will accepted only after the one from the previous frame has been processed (i.e. all addresses within the previous frame have been generated). - -Video resolution can be changed in a similar way. - -To interface with the CPU, the frame initiator uses Migen to provide a CSR bank (see :ref:`bank`). - -Pixel fetcher -============= - -The pixel fetcher is made up of the address generator, the LASMI reader and the unpacker. - -The address generator is a simple counter that takes one token containing the pair ``(base, length)`` and generates ``length`` tokens containing ``base``, ..., ``base+length-1``. It is implemented using a Migen library component (see :ref:`intsequence`). - -Those addresses are fed into the LASMI reader (see :ref:`busactors`) that fetches the corresponding locations from the system memory. The LASMI reader design supports several outstanding requests, which enables it to sustain a high throughput in spite of memory latency. This feature makes it possible to utilize the available memory bandwidth to the full extent, and reduces the need for on-chip buffering. - -LASMI memory words are wide and contain several pixels. The unpacking actor (see :ref:`structuring`) takes a token containing a memory word and "chops" it into multiple tokens containing one pixel each. - -Video timing generator -====================== - -The video timing generator is the central piece of the framebuffer core. It takes one token containing the timing parameters of a frame, followed by as many tokens as there are pixels in the frame. It generates tokens containing the status of the horizontal/vertical synchronization signals and red/green/blue values. When the contents of those tokens are sent out at the pixel clock rate (and the red/green/blue value converted to analog), they form a valid video signal for one frame. - -DAC driver -========== - -The DAC driver accepts and buffers the output tokens from the video timing generator, and sends their content to the DAC and video port at the pixel clock rate using an asynchronous FIFO. diff --git a/doc/conf.py b/doc/conf.py index fc7f1180..f134ce9b 100644 --- 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 @@ master_doc = 'index' # 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. @@ -98,7 +96,7 @@ numpydoc_show_class_members = False # 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 deleted file mode 100644 index c435eddf..00000000 --- a/doc/dataflow.rst +++ /dev/null @@ -1,342 +0,0 @@ -.. _dataflow: - -Dataflow -######## - -Many hardware acceleration problems can be expressed in the dataflow paradigm. It models a program as a directed graph of the data flowing between functions. The nodes of the graph are functional units called actors, and the edges represent the connections (transporting data) between them. - -Actors communicate by exchanging data units called tokens. A token contains arbitrary (user-defined) data, which is a record containing one or many fields, a field being a bit vector or another record. Token exchanges are atomic (i.e. all fields are transferred at once from the transmitting actor to the receiving actor). - -Actors -****** - -Actors and endpoints -==================== - -Actors in Migen are implemented in FHDL. This low-level approach maximizes the practical flexibility: for example, an actor can manipulate the bus signals to implement a DMA master in order to read data from system memory (see :ref:`busactors`). - -Token exchange ports of actors are called endpoints. Endpoints are unidirectional and can be sources (which transmit tokens out of the actor) or sinks (which receive tokens into the actor). - -.. figure:: actors_endpoints.png - :scale: 50 % - - Actors and endpoints. - -The flow of tokens is controlled using two handshake signals (strobe and acknowledgement) which are implemented by every endpoint. The strobe signal is driven by sources, and the acknowledgement signal by sinks. - -======= ======= ==================================================================================================== -``stb`` ``ack`` Situation -======= ======= ==================================================================================================== -0 0 The source endpoint does not have data to send, and the sink endpoint is not ready to - accept data. -0 1 The sink endpoint is ready to accept data, but the source endpoint has currently no data - to send. The sink endpoint is not required to keep its ``ack`` signal asserted. -1 0 The source endpoint is trying to send data to the sink endpoint, which is currently not - ready to accept it. The transaction is *stalled*. The source endpoint must keep ``stb`` - asserted and continue to present valid data until the transaction is completed. -1 1 The source endpoint is sending data to the sink endpoint which is ready to accept it. The - transaction is *completed*. The sink endpoint must register the incoming data, as the - source endpoint is not required to hold it valid at the next cycle. -======= ======= ==================================================================================================== - -It is permitted to generate an ``ack`` signal combinatorially from one or several ``stb`` signals. However, there should not be any combinatorial path from an ``ack`` to a ``stb`` signal. - -Actors are FHDL modules that have one or several endpoint attributes of the ``migen.flow.actor.Sink`` or ``migen.flow.actor.Source`` type, and a ``busy`` signal. - -Endpoint constructors take as parameter the layout of the data record that the endpoint is dealing with. - -Record layouts are a list of fields. Each field is described by a pair consisting of: - -* The field's name. -* Either a bit width or a (bit width, signedness) pair if the field is a bit vector, or another record layout if the field is a lower-level record. - -For example, this code: :: - - class MyActor(Module): - def __init__(self): - self.busy = Signal() - self.operands = Sink([("a", 16), ("b", 16)]) - self.result = Source([("r", 17)]) - -creates an actor with: - -* One sink named ``operands`` accepting data structured as a 16-bit field ``a`` and a 16-bit field ``b``. Note that this is functionally different from having two endpoints ``a`` and ``b``, each accepting a single 16-bit field. With a single endpoint, the data is strobed when *both* ``a`` and ``b`` are valid, and ``a`` and ``b`` are *both* acknowledged *atomically*. With two endpoints, the actor has to deal with accepting ``a`` and ``b`` independently. Plumbing actors (see :ref:`plumbing`) and abstract networks (see :ref:`actornetworks`) provide a systematic way of converting between these two behaviours, so user actors should implement the behaviour that results in the simplest or highest performance design. -* One source named ``result`` transmitting a single 17-bit field named ``r``. - -Accessing the endpoints is done by manipulating the signals inside the ``Source`` and ``Sink`` objects. They hold: - -* A signal object ``stb``. -* A signal object ``ack``. -* The data payload ``payload``, which is a record with the layout given to the endpoint constructor. - -Endpoints can also be used to manipulate packets, this is done by setting packetized parameter to True which adds: - -* A signal object ``sop`` (Start Of Packet). -* A signal object ``eop`` (End Of Packet). - -When used in packetized mode, packet parameters (signals that do no change for the duration of a packet) should to be declared in -param_layout. Declaring these signals in payload_layout will works in most cases but will prevent logic optimizations. - -Busy signal -=========== - -The basic actor class creates a ``busy`` control signal that actor implementations should drive. - -This signal represents whether the actor's state holds information that will cause the completion of the transmission of output tokens. For example: - -* A "buffer" actor that simply registers and forwards incoming tokens should drive 1 on ``busy`` when its register contains valid data pending acknowledgement by the receiving actor, and 0 otherwise. -* An actor sequenced by a finite state machine should drive ``busy`` to 1 whenever the state machine leaves its idle state. -* An actor made of combinatorial logic is stateless and should tie ``busy`` to 0. - -.. _schedmod: - -Common scheduling models -======================== - -For the simplest and most common scheduling cases, Migen provides logic to generate the handshake signals and the busy signal. This is done through abstract actor classes that examine the endpoints defined by the user and add logic to drive their control signals (i.e. everything except the payload). The ``__init__`` method of the abstract scheduling class must be called after the user has created the endpoints. The ``busy`` signal is created by the abstract scheduling class. - -These classes are usable only when the actor has exactly one sink and one source (but those endpoints can contain an arbitrary data structure), and in the cases listed below. - -Combinatorial -------------- -The actor datapath is made entirely of combinatorial logic. The handshake signals pass through. A small integer adder would use this model. - -This model is implemented by the ``migen.flow.actor.CombinatorialActor`` class. There are no parameters or additional control signals. - -N-sequential ------------- -The actor consumes one token at its input, and it produces one output token after N cycles. It cannot accept new input tokens until it has produced its output. A multicycle integer divider would use this model. - -This model is implemented by the ``migen.flow.actor.SequentialActor`` class. The constructor of this class takes as parameter the number of cycles N. The class provides an extra control signal ``trigger`` that pulses to 1 for one cycle when the actor should register the inputs and start its processing. The actor is then expected to provide an output after the N cycles and hold it constant until the next trigger pulse. - -N-pipelined ------------ -This is similar to the sequential model, but the actor can always accept new input tokens. It produces an output token N cycles of latency after accepting an input token. A pipelined multiplier would use this model. - -This model is implemented by the ``migen.flow.actor.PipelinedActor`` class. The constructor takes the number of pipeline stages N. There is an extra control signal ``pipe_ce`` that should enable or disable all synchronous statements in the datapath (i.e. it is the common clock enable signal for all the registers forming the pipeline stages). - -The Migen actor library -*********************** - -.. _plumbing: - -Plumbing actors -=============== - -Plumbing actors arbitrate the flow of data between actors. For example, when a source feeds two sinks, they ensure that each sink receives exactly one copy of each token transmitted by the source. - -Most of the time, you will not need to instantiate plumbing actors directly, as abstract actor networks (see :ref:`actornetworks`) provide a more powerful solution and let Migen insert plumbing actors behind the scenes. - -Buffer ------- - -The ``Buffer`` registers the incoming token and retransmits it. It is a pipelined actor with one stage. It can be used to relieve some performance problems or ease timing closure when many levels of combinatorial logic are accumulated in the datapath of a system. - -When used in a network, abstract instances of ``Buffer`` are automatically configured by Migen (i.e. the appropriate token layout is set). - -Combinator ----------- - -This actor combines tokens from several sinks into one source. - -For example, when the operands of a pipelined multiplier are available independently, the ``Combinator`` can turn them into a structured token that is sent atomically into the multiplier when both operands are available, simplifying the design of the multiplier actor. - -Splitter --------- - -This actor does the opposite job of the ``Combinator``. It receives a token from its sink, duplicates it into an arbitrary number of copies, and transmits one through each of its sources. It can optionally omit certain fields of the token (i.e. take a subrecord). - -For example, an Euclidean division actor generating the quotient and the remainder in one step can transmit both using one token. The ``Splitter`` can then forward the quotient and the remainder independently, as integers, to other actors. - -.. _structuring: - -Structuring actors -================== - -Cast ----- - -This actor concatenates all the bits from the data of its sink (in the order as they appear in the layout) and connects them to the raw bits of its source (obtained in the same way). The source and the sink layouts must contain the same number of raw bits. This actor is a simple "connect-through" which does not use any hardware resources. - -It can be used in conjunction with the bus master actors (see :ref:`busactors`) to destructure (resp. structure) data going to (resp. coming from) the bus. - -Unpack ------- - -This actor takes a token with the fields ``chunk0`` ... ``chunk[N-1]`` (each having the same layout L) and generates N tokens with the layout L containing the data of ``chunk0`` ... ``chunk[N-1]`` respectively. - -Pack ----- - -This actor receives N tokens with a layout L and generates one token with the fields ``chunk0`` ... ``chunk[N-1]`` (each having the same layout L) containing the data of the N incoming tokens respectively. - -Simulation actors -================= - -When hardware implementation is not desired, Migen lets you program actor behaviour in "regular" Python. - -For this purpose, it provides a ``migen.actorlib.sim.SimActor`` class. The constructor takes a generator as parameter, which implements the actor's behaviour. The user must derive the ``SimActor`` class and add endpoint attributes. The ``busy`` signal is provided by the ``SimActor`` class. - -Generators can yield ``None`` (in which case, the actor does no transfer for one cycle) or one or a tuple of instances of the ``Token`` class. Tokens for sink endpoints are pulled and the "value" field filled in. Tokens for source endpoints are pushed according to their "value" field. The generator is run again after all transactions are completed. - -The possibility to push several tokens at once is important to interact with actors that only accept a group of tokens when all of them are available. - -The ``Token`` class contains the following items: - -* The name of the endpoint from which it is to be received, or to which it is to be transmitted. This value is not modified by the transaction. -* A dictionary of values corresponding to the fields of the token. Fields that are lower-level records are represented by another dictionary. This item should be set to ``None`` (default) when receiving from a sink. - -See ``dataflow.py`` in the examples folder of the Migen sources for a demonstration of the use of these actors. - -.. _busactors: - -Bus actors -========== - -Migen provides a collection of bus-mastering actors, which makes it possible for dataflow systems to access system memory easily and efficiently. - -Wishbone reader ---------------- - -The ``migen.actorlib.dma_wishbone.Reader`` takes a token representing a 30-bit Wishbone address (expressed in words), reads one 32-bit word on the bus at that address, and transmits the data. - -It does so using Wishbone classic cycles (there is no burst or cache support). The actor is pipelined and its throughput is only limited by the Wishbone stall cycles. - -Wishbone writer ---------------- - -The ``migen.actorlib.dma_wishbone.Writer`` takes a token containing a 30-bit Wishbone address (expressed in words) and a 32-bit word of data, and writes that word to the bus. - -Only Wishbone classic cycles are supported. The throughput is limited by the Wishbone stall cycles only. - -LASMI reader ------------- - -The ``migen.actorlib.dma_lasmi.Reader`` requires a LASMI master port at instantiation time. This port defines the address and data widths of the actor and how many outstanding transactions are supported. - -Input tokens contain the raw LASMI address, and output tokens are wide LASMI data words. - -LASMI writer ------------- - -Similarly, Migen provides a LASMI writer actor that accepts tokens containing an address and write data (in the same format as a LASMI word). - -Miscellaneous actors -==================== - -.. _intsequence: - -Integer sequence generator --------------------------- - -The integer sequence generator either: - -* takes a token containing a maximum value N and generates N tokens containing the numbers 0 to N-1. -* takes a token containing a number of values N and a offset O and generates N-O tokens containing the numbers O to O+N-1. - -The actor instantiation takes several parameters: - -* the number of bits needed to represent the maximum number of generated values. -* the number of bits needed to represent the maximum offset. When this value is 0 (default), then offsets are not supported and the sequence generator accepts tokens which contain the maximum value alone. - -The integer sequence generator can be used in combination with bus actors to generate addresses and read contiguous blocks of system memory (see :ref:`busactors`). - -.. _actornetworks: - -Actor networks -************** - -Graph definition -================ - -Migen represents an actor network using the ``migen.flow.network.DataFlowGraph`` class (a directed graph with self-loops and parallel edges). - -Nodes of the graph are either: - -* An existing actor (*physical actor*). -* An instance of ``migen.flow.network.AbstractActor``, containing the actor class and a dictionary (*abstract actor*). It means that the actor class should be instantiated with the parameters from the dictionary. This form is needed to enable optimizations such as actor duplication or sharing during elaboration. - -Edges of the graph represent the flow of data between actors. They have the following data properties: - -* ``source``: a string containing the name of the source endpoint, which can be ``None`` (Python's ``None``, not the string ``"None"``) if the transmitting actor has only one source endpoint. -* ``sink``: a string containing the name of the sink endpoint, which can be ``None`` if the transmitting actor has only one sink endpoint. -* ``source_subr``: if only certain fields (a subrecord) of the source endpoint should be included in the connection, their names are listed in this parameter. The ``None`` value connects all fields. -* ``sink_subr``: if the connection should only drive certain fields (a subrecord) of the sink endpoint, they are listed here. The ``None`` value connects all fields. - -Migen's ``DataFlowGraph`` class implements a method that makes it easy to add actor connections to a graph: :: - - add_connection(source_node, sink_node, - source_ep=None, sink_ep=None, # default: assume nodes have 1 source/sink - # and use that one - source_subr=None, sink_subr=None) # default: use whole record - -Abstract and physical networks -============================== - -A network (or graph) is abstract if it cannot be physically implemented by only connecting existing records together. More explicitly, a graph is abstract if any of these conditions is met: - -#. A node is an abstract actor. -#. A subrecord is used at a source or a sink. -#. A single source feeds more than one sink. - -The ``DataFlowGraph`` class implements a method ``is_abstract`` that tests and returns if the network is abstract. - -An abstract graph can be turned into a physical graph through *elaboration*. - -Elaboration -=========== - -The most straightforward elaboration process goes as follows: - -#. Whenever several sources drive different fields of a single sink, insert a ``Combinator`` plumbing actor. A ``Combinator`` should also be inserted when a single source drive only certain fields of a sink. -#. Whenever several sinks are driven by a single source (possibly by different fields of that source), insert a ``Splitter`` plumbing actor. A ``Splitter`` should also be inserted when only certain fields of a source drive a sink. -#. Whenever an actor is abstract, instantiate it. - -This method is implemented by default by the ``elaborate`` method of the ``DataFlowGraph`` class, that modifies the graph in-place. - -Thanks to abstract actors, there are optimization possibilities during this stage: - -* Time-sharing an actor to reduce resource utilization. -* Duplicating an actor to increase performance. -* Promoting an actor to a wider datapath to enable time-sharing with another. For example, if a network contains a 16-bit and a 32-bit multiplier, the 16-bit multiplier can be promoted to 32-bit and time-shared. -* Algebraic optimizations. -* Removing redundant actors whose output is only used partially. For example, two instances of divider using the restoring method can be present in a network, and each could generate either the quotient or the remainder of the same integers. Since the restoring method produces both results at the same time, only one actor should be used instead. - -None of these optimizations are implemented yet. - -Implementation -============== - -A physical graph can be implemented and turned into a synthesizable or simulable fragment using the ``migen.flow.network.CompositeActor`` actor. - -Performance tools -***************** - -The module ``migen.flow.perftools`` provides utilities to analyze the performance of a dataflow network. - -The class ``EndpointReporter`` is a simulation object that attaches to an endpoint and measures three parameters: - -* The total number of clock cycles per token (CPT). This gives a measure of the raw inverse token rate through the endpoint. The smaller this number, the faster the endpoint operates. Since an endpoint has only one set of synchronous control signals, the CPT value is always superior or equal to 1 (multiple data records can however be packed into a single token, see for example :ref:`structuring`). -* The average number of inactivity cycles per token (IPT). An inactivity cycle is defined as a cycle with the ``stb`` signal deasserted. This gives a measure of the delay between attempts at token transmissions ("slack") on the endpoint. -* The average number of stall cycles per token (NPT). A stall cycle is defined as a cycle with ``stb`` asserted and ``ack`` deasserted. This gives a measure of the "backpressure" on the endpoint, which represents the average number of wait cycles it takes for the source to have a token accepted by the sink. If all tokens are accepted immediately in one cycle, then NPT=0. - -In the case of an actor network, the ``DFGReporter`` simulation object attaches an ``EndpointReporter`` to the source endpoint of each edge in the graph. The graph must not be abstract. - -The ``DFGReporter`` contains a dictionary ``nodepair_to_ep`` that is keyed by ``(source actor, destination actor)`` pairs. Entries are other dictionaries that are keyed with the name of the source endpoint and return the associated ``EndpointReporter`` objects. - -``DFGReporter`` also provides a method ``get_edge_labels`` that can be used in conjunction with NetworkX's [networkx]_ ``draw_networkx_edge_labels`` function to draw the performance report on a graphical representation of the graph (for an example, see :ref:`get_edge_labels`). - -.. [networkx] http://networkx.lanl.gov/ - -.. _get_edge_labels: - -.. figure:: get_edge_labels.png - :scale: 55 % - - Actor network with performance data from a simulation run. - - -High-level actor description -**************************** - -Actors can be written in a subset of Python and automatically compiled into FHDL by using the Pytholite component. This functionality is still very limited for now. diff --git a/doc/fbflow.dia b/doc/fbflow.dia deleted file mode 100644 index 3c1050a98018de08dc83980da503e6520a2c15bb..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2026 zcmV%m5` z*<$bjapIf(?JESSzrcW+zg4iY-A9!UrM;p5{xG?qL`gE+b#0Lva2JetIQ z5KXTK-@ko+M+YBo-hA)_@4fgpO}x1wz7eJQr|ZEi%NFm4!-t0lD_o^s7AIC1+*>Ih z{^y0EHxz}2gPS*ov1!2fGA}yVwO!ZF0K1 zakuWmZrvr_x(m|LB2Kcz3$lHe<2Vkv7ZqN!Y$Mb_8ET+us3B-F zm7(TZl!)F>ErbCS@kT6wT*qV6792r`6%G6y`$>Lk(cCh`kP*QFLQIG}s zB&mks4-9;D6ctBVmEZihap%p0a3xO9i_(FSW~*GGg}N4B{ey=~o&^(cb09hW4E6%Q zN?9xniWfu3vFWBtp5t@7FV^)(3o+4Gnt9rlg4!9QZ8viyPMo*N% zYT$rPRS*aUa1_cQki;S1uV8^3OfhmasM2d;j;9y+g@6DxW^ZT$mGBLSu|h>n3=Of?Sl5C`x@aDcRd1Fm`;AZr{zpaUGx+Y+x12i!JrK;@1U+Z_;vw z09(WrA6ZWp2);)Pam6(VbOHiQuM6}Q1jt1|fHvMS%|~X1>W3r8MG?B`s2N7GCAlF1NhYfUvspTM&JI!f>zI@vFC-8Y}WWii~(t8q} zv4`xJnmzi;9`qvY0qi#5!&MI-WDOq}bO0ZE6+**@g5*fh27Rbp=|I$C#6+}Y55f6Z zIP3{|{C@kJ;U~dTuXJ=m8+xUqx3mFNr$v4VB3{KCu!Zz+pmebV$izsw*deB1d153w zn>X@S9P!AP=YK-2stcSs>l7Vove@-qb+gndMniFZm2FzIk?2eITC?K2;3*uO?JwJ1 zg+nXJkt$asAg~Bwzywfk140WSo0-6|#8^WW2gOd^stY);B`Ef$1Cc-Sk|chpA3;z< z%cGD-)5Dc~+|m z8}{@I_PQa2vN%X_j4CE z_4x9d$CsM>OHP`K;tMUzw3378bRZiLZ^?$+jcjb+{asanXxY%R(Pkd{NwPsMBpbAi z4K1gGnXKGLUe9E^kd2+HRTt2*p=G1h%#qU;zAv>8#9F`&q<$)lpj3}5R4jPQ3@f1@ z>UjeloDk<3DoAUF){K@`z)(kF5A8O>9;gp{yPRX>x$fPpfFW>Xf`Rn*?+N#AkhXht zO-2_4Z7jE8l|4FNJhdE~6i>Dx@~Kalp&sOOjlGncMxn*8E~CqKD9T^Vu>k@$?&6s? z*n(^`_4QZC=(78h(bbY9!8YdPw#qrVyiHO_63SD$Da*&(ekf9TSIff7AHtc5me;b> zL87Uh%M#VH)NffrZKQrem8qY35@tb4$hDa3%B}Ez2on$#{DVisyIh#GD5-xYFo2qs zdYkcKNk7QrJAHI8*KOGHrP*e`%%PAfaN z0+Sq~cB+^^5P<@A<=B=3TzM}rCJeoNNt&grXkr@6;=jZ+rlv903e~}ckywy0tQD${ zY(_7{X6@w7s@B88iPS^rSV%sV&d&7^zkEIPis#g81?=D{bhcK&-YOuukOH=o0^ETD z!jcH{-|}L4=50UpZ_ej&vN9gx#Mc_wfd*;{?5_s8O*OFiEPrM6=FQg6klwucAI|41 IYpQ$z0DN)YWdHyG diff --git a/doc/fbflow.png b/doc/fbflow.png deleted file mode 100644 index 8570c2593092102b0df1ba2b603d82c701c08683..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 86187 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 diff --git a/doc/fhdl.rst b/doc/fhdl.rst index e3fa7e68..b6225605 100644 --- a/doc/fhdl.rst +++ b/doc/fhdl.rst @@ -1,7 +1,7 @@ -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. @@ -28,6 +28,7 @@ To lighten the syntax, assignments and operators automatically wrap Python integ 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. @@ -49,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 @@ -59,15 +61,18 @@ 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 @@ -75,6 +80,7 @@ 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: :: @@ -86,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. @@ -109,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. @@ -138,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: :: @@ -157,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. @@ -174,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: @@ -262,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 | @@ -342,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/index.rst b/doc/index.rst index 6c21d762..36f73aa3 100644 --- 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 index 324e59bc..abc68ee0 100644 --- 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 @@ -51,8 +51,6 @@ 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`. - If you wish to contribute patches, the suggest way to install is; #. Clone from the git repository at http://github.com/m-labs/migen #. Install using ``python3 ./setup.py develop --user`` @@ -61,9 +59,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 `_ 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 b/doc/reference.rst similarity index 74% rename from doc/api.rst rename to doc/reference.rst index 1efa5668..bec65ce8 100644 --- a/doc/api.rst +++ b/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 index fa93c995..8f392d9c 100644 --- 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. - -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 new file mode 100644 index 00000000..a5b99502 --- /dev/null +++ b/doc/synthesis.rst @@ -0,0 +1,4 @@ +Synthesizing a Migen design +########################### + +[To be written] diff --git a/setup.py b/setup.py index 14bb95bb..fcb79998 100755 --- a/setup.py +++ b/setup.py @@ -15,7 +15,7 @@ if sys.version_info < required_version: setup( name="migen", - version="0.0+dev", + version="1.0", description="Python toolbox for building complex digital hardware", long_description=README, author="Sebastien Bourdeauducq", -- 2.30.2