Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
  • 6 commits
  • 4 files changed
  • 0 comments
  • 1 contributor
7  doc/bus.rst
Source Rendered
@@ -15,10 +15,11 @@ It also provides interconnect components for these buses, such as arbiters and a
15 15
 
16 16
   wbcon = wishbone.InterconnectShared(
17 17
       [cpu.ibus, cpu.dbus, ethernet.dma, audio.dma],
18  
-      [(0, norflash.bus), (1, wishbone2asmi.wishbone),
19  
-      (3, wishbone2csr.wishbone)])
  18
+      [(lambda a: a[27:] == 0, norflash.bus),
  19
+       (lambda a: a[27:] == 1, wishbone2asmi.wishbone),
  20
+       (lambda a: a[27:] == 3, wishbone2csr.wishbone)])
20 21
 
21  
-In this example, the interconnect component generates a 4-way round-robin arbiter, multiplexes the master bus signals into a shared bus, determines that the address decoding must occur on 2 bits, 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. The resulting interconnect logic can be retrieved using ``wbcon.get_fragment()``, and combined with the fragments from the rest of the system.
  22
+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. The resulting interconnect logic can be retrieved using ``wbcon.get_fragment()``, and combined with the fragments from the rest of the system.
22 23
 
23 24
 
24 25
 Configuration and Status Registers
33  doc/dataflow.rst
Source Rendered
@@ -52,13 +52,13 @@ An endpoint description is a triple consisting of:
52 52
 Record layouts are a list of fields. Each field is described by a pair consisting of:
53 53
 
54 54
 * The field's name.
55  
-* Either a BV object (see :ref:`bv`) if the field is a bit vector, or another record layout if the field is a lower-level record.
  55
+* 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.
56 56
 
57 57
 For example, this code: ::
58 58
 
59 59
   Actor(
60  
-    ("operands", Sink, [("a", BV(16)), ("b", BV(16))]),
61  
-    ("result", Source, [("r", BV(17))]))
  60
+    ("operands", Sink, [("a", 16), ("b", 16)]),
  61
+    ("result", Source, [("r", 17)]))
62 62
 
63 63
 creates an actor with:
64 64
 
@@ -185,16 +185,7 @@ The ``Token`` class contains the following items:
185 185
 * 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.
186 186
 * 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.
187 187
 
188  
-See :ref:`dfsimexample` for an example demonstrating the use of these actors.
189  
-
190  
-Arithmetic and logic actors
191  
-===========================
192  
-
193  
-The ``migen.actorlib.ala`` module provides arithmetic and logic actors for the usual integer operations.
194  
-
195  
-If complex operation combinations are needed, the ``ComposableNode`` class can be used. It overloads Python operators to make them instantiate the arithmetic and logic actors and connect them into an existing network. This creates a small internal domain-specific language (DSL).
196  
-
197  
-The ``ComposableNode`` class is a derivative of the ``ActorNode`` class (see :ref:`actornetworks`) and should be used in the place of the latter when the DSL feature is desired.
  188
+See ``dataflow.py`` in the examples folder of the Migen sources for a demonstration of the use of these actors.
198 189
 
199 190
 .. _busactors:
200 191
 
@@ -263,10 +254,10 @@ Migen represents an actor network using the ``migen.flow.network.DataFlowGraph``
263 254
 
264 255
 .. [networkx] http://networkx.lanl.gov/
265 256
 
266  
-Nodes of the graph are instances of the ``migen.flow.network.ActorNode`` class. The latter can represent actors in two ways:
  257
+Nodes of the graph are either:
267 258
 
268  
-* A reference to an existing actor (*physical actor*).
269  
-* An class and a dictionary (*abstract actor*), meaning 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.
  259
+* An existing actor (*physical actor*).
  260
+* 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.
270 261
 
271 262
 Edges of the graph represent the flow of data between actors. They have the following data properties:
272 263
 
@@ -349,12 +340,4 @@ The ``DFGReporter`` contains a dictionary ``nodepair_to_ep`` that is keyed by ``
349 340
 High-level actor description
350 341
 ****************************
351 342
 
352  
-.. WARNING::
353  
-   Not implemented yet, just an idea.
354  
-
355  
-It is conceivable that a CAL [cal]_ to FHDL compiler be implemented at some point, to support higher level descriptions of some actors and reuse of third-party RVC-CAL applications. [orcc]_ [orcapps]_ [opendf]_
356  
-
357  
-.. [cal] http://opendf.svn.sourceforge.net/viewvc/opendf/trunk/doc/GentleIntro/GentleIntro.pdf
358  
-.. [orcc] http://orcc.sourceforge.net/
359  
-.. [orcapps] http://orc-apps.sourceforge.net/
360  
-.. [opendf] http://opendf.sourceforge.net/
  343
+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.
83  doc/fhdl.rst
Source Rendered
@@ -2,7 +2,9 @@ The FHDL layer
2 2
 ##############
3 3
 
4 4
 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 and encapsulating them in "fragments".
5  
-The FHDL module also contains a back-end to produce synthesizable Verilog, and some basic analysis functions. It would be possible to develop a VHDL back-end as well, though more difficult than for Verilog - we are "cheating" a bit now as Verilog provides most of the FHDL semantics.
  5
+The FHDL module also contains a back-end to produce synthesizable Verilog, and some structure analysis and manipulation functionality. A VHDL back-end [vhdlbe]_ is in development.
  6
+
  7
+.. [vhdlbe] https://github.com/peteut/migen
6 8
 
7 9
 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.
8 10
 
@@ -13,22 +15,14 @@ FHDL is made of several elements, which are briefly explained below.
13 15
 Expressions
14 16
 ***********
15 17
 
16  
-.. _bv:
17  
-
18  
-Bit vector (BV)
19  
-===============
20  
-The bit vector (BV) object defines if a constant or signal is signed or unsigned, and how many bits it has. This is useful e.g. to:
  18
+Integers and booleans
  19
+=====================
21 20
 
22  
-* Determine when to perform sign extension (FHDL uses the same rules as Verilog).
23  
-* Determine the size of registers.
24  
-* Determine how many bits should be used by each value in concatenations.
  21
+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.
25 22
 
26  
-Constant
27  
-========
28  
-This object should be self-explanatory. All constant objects contain a BV object and a value. If no BV object is specified, one will be made up using the following rules:
  23
+Negative integers are explicitly supported. As with MyHDL [countin]_, arithmetic operations return the natural results.
29 24
 
30  
-* If the value is positive, the BV is unsigned and has the minimum number of bits needed to represent the constant's value in the canonical base-2 system.
31  
-* If the value is negative, the BV is signed, and has the minimum number of bits needed to represent the constant's value in the canonical two's complement, base-2 system.
  25
+.. [countin] http://www.jandecaluwe.com/hdldesign/counting.html
32 26
 
33 27
 Signal
34 28
 ======
@@ -38,7 +32,8 @@ The main point of the signal object is that it is identified by its Python ID (a
38 32
 
39 33
 The properties of a signal object are:
40 34
 
41  
-* A bit vector description
  35
+* An integer or a (integer, boolean) pair that defines the number of bits and whether the bit of higher index of the signal is a sign bit (i.e. the signal is signed). The defaults are one bit and unsigned.
  36
+Alternatively, the ``min`` and ``max`` parameters can be specified to define the range of the signal and determine its bit width and signedness. As with Python ranges, ``min`` is inclusive and defaults to 0, ``max`` is exclusive and defaults to 2.
42 37
 * A name, used as a hint for the V*HDL back-end name mangler.
43 38
 * A boolean "variable". If true, the signal will behave like a VHDL variable, or a Verilog reg that uses blocking assignment. This parameter only has an effect when the signal's value is modified in a synchronous statement.
44 39
 * The signal's reset value. It must be an integer, and defaults to 0. When the signal's value is modified with a synchronous statement, the reset value is the initialization value of the associated register. When the signal is assigned to in a conditional combinatorial statement (``If`` or ``Case``), the reset value is the value that the signal has when no condition that causes the signal to be driven is verified. This enforces the absence of latches in designs. If the signal is permanently driven using a combinatorial statement, the reset value has no effect.
@@ -114,13 +109,11 @@ Example: ::
114 109
 
115 110
 Case
116 111
 ====
117  
-The ``Case`` object constructor takes as first parameter the expression to be tested, then a variable number of lists describing the various cases.
118  
-
119  
-Each list contains an expression (typically a constant) describing the value to be matched, followed by the statements to be executed when there is a match. The head of the list can be the an instance of the ``Default`` object.
  112
+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.
120 113
 
121 114
 Arrays
122 115
 ======
123  
-The ``Array`` object represents lists of other objects that can be indexed by FHDL expressions. It is explicitely possible to:
  116
+The ``Array`` object represents lists of other objects that can be indexed by FHDL expressions. It is explicitly possible to:
124 117
 
125 118
 * nest ``Array`` objects to create multidimensional tables.
126 119
 * list any Python object in a ``Array`` as long as every expression appearing in a fragment ultimately evaluates to a ``Signal`` for all possible values of the indices. This allows the creation of lists of structured data.
@@ -149,18 +142,16 @@ Instance objects represent the parametrized instantiation of a V*HDL module, and
149 142
 
150 143
 * Reusing legacy or third-party V*HDL code.
151 144
 * Using special FPGA features (DCM, ICAP, ...).
152  
-* Implementing logic that cannot be expressed with FHDL (asynchronous circuits, ...).
153  
-* Breaking down a Migen system into multiple sub-systems, possibly using different clock domains.
  145
+* Implementing logic that cannot be expressed with FHDL (e.g. latches).
  146
+* Breaking down a Migen system into multiple sub-systems.
  147
+
  148
+The instance object constructor takes the type (i.e. name of the instantiated module) of the instance, then multiple parameters describing how to connect and parametrize the instance.
154 149
 
155  
-The properties of the instance object are:
  150
+These parameters can be:
156 151
 
157  
-* The type of the instance (i.e. name of the instantiated module).
158  
-* A list of output ports of the instantiated module. Each element of the list is a pair containing a string, which is the name of the module's port, and either an existing signal (on which the port will be connected to) or a BV (which will cause the creation of a new signal).
159  
-* A list of input ports (likewise).
160  
-* A list of (name, value) pairs for the parameters ("generics" in VHDL) of the module.
161  
-* The name of the clock port of the module (if any). If this is specified, the port will be connected to the system clock.
162  
-* The name of the reset port of the module (likewise).
163  
-* The name of the instance (can be mangled like signal names).
  152
+* ``Instance.Input``, ``Instance.Output`` or ``Instance.InOut`` to describe signal connections with the instance. The parameters are the name of the port at the instance, and the FHDL expression it should be connected to.
  153
+* ``Instance.Parameter`` sets a parameter (with a name and value) of the instance.
  154
+* ``Instance.ClockPort`` and ``Instance.ResetPort`` are used to connect clock and reset signals to the instance. The only mandatory parameter is the name of the port at the instance. Optionally, a clock domain name can be specified, and the ``invert`` option can be used to interface to those modules that require a 180-degree clock or a active-low reset.
164 155
 
165 156
 Memories
166 157
 ========
@@ -171,23 +162,23 @@ A memory object has the following parameters:
171 162
 * The width, which is the number of bits in each word.
172 163
 * The depth, which represents the number of words in the memory.
173 164
 * An optional list of integers used to initialize the memory.
174  
-* A list of port descriptions.
175 165
 
176  
-Each port description contains:
  166
+To access the memory in hardware, ports can be obtained by calling the ``get_port`` method. A port always has an address signal ``a`` and a data read signal ``dat_r``. Other signals may be available depending on the port's configuration.
  167
+
  168
+Options to ``get_port`` are:
177 169
 
178  
-* The address signal (mandatory).
179  
-* The data read signal (mandatory).
180  
-* The write enable signal (optional). If the port is using masked writes, the width of the write enable signal should match the number of sub-words.
181  
-* The data write signal (iff there is a write enable signal).
182  
-* Whether reads are synchronous (default) or asynchronous.
183  
-* The read enable port (optional, ignored for asynchronous ports).
184  
-* The write granularity (default 0), which defines the number of bits in each sub-word. If it is set to 0, the port is using whole-word writes only and the width of the write enable signal must be 1. This parameter is ignored if there is no write enable signal.
185  
-* The mode of the port (default ``WRITE_FIRST``, ignored for asynchronous ports). It can be:
  170
+* ``write_capable`` (default: ``False``): if the port can be used to write to the memory. This creates an additional ``we`` signal.
  171
+* ``async_read`` (default: ``False``): whether reads are asychronous (combinatorial) or synchronous (registered).
  172
+* ``has_re`` (default: ``False``): adds a read clock-enable signal ``re`` (ignored for asychronous ports).
  173
+* ``we_granularity`` (default: ``0``): if non-zero, writes of less than a memory word can occur. The width of the ``we`` signal is increased to act as a selection signal for the sub-words.
  174
+* ``mode`` (default: ``WRITE_FIRST``, ignored for aynchronous ports).  It can be:
186 175
 
187 176
   * ``READ_FIRST``: during a write, the previous value is read.
188 177
   * ``WRITE_FIRST``: the written value is returned.
189 178
   * ``NO_CHANGE``: the data read signal keeps its previous value on a write.
190 179
 
  180
+* ``clock_domain`` (default: ``"sys"``): the clock domain used for reading and writing from this port.
  181
+
191 182
 Migen generates behavioural V*HDL code that should be compatible with all simulators and, if the number of ports is <= 2, most FPGA synthesizers. If a specific code is needed, the memory generator function can be overriden using the ``memory_handler`` parameter of the conversion function.
192 183
 
193 184
 Fragments
@@ -195,12 +186,12 @@ Fragments
195 186
 A "fragment" is a unit of logic, which is composed of:
196 187
 
197 188
 * A list of combinatorial statements.
198  
-* A list of synchronous statements.
  189
+* A list of synchronous statements, or a clock domain name -> synchronous statements dictionary.
199 190
 * A list of instances.
200 191
 * A list of memories.
201 192
 * A list of simulation functions (see :ref:`simulating`).
202 193
 
203  
-Fragments can reference arbitrary signals, including signals that are referenced in other fragments. Fragments can be combined using the "+" operator, which returns a new fragment containing the concatenation of each pair of lists.
  194
+Fragments can reference arbitrary signals, including signals that are referenced in other fragments. Fragments can be combined using the "+" operator, which returns a new fragment containing the concatenation of each matched pair of lists.
204 195
 
205 196
 Fragments can be passed to the back-end for conversion to Verilog.
206 197
 
@@ -212,3 +203,13 @@ Conversion for synthesis
212 203
 Any FHDL fragment (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.
213 204
 
214 205
 Migen does not provide support for any specific synthesis tools or ASIC/FPGA technologies. Users must run themselves the generated code through the appropriate tool flow for hardware implementation.
  206
+
  207
+The Mibuild package, available separately from the Migen website, provides scripts to interface third-party FPGA tools to Migen and a database of boards for the easy deployment of designs.
  208
+
  209
+
  210
+Multi-clock-domain designs
  211
+**************************
  212
+
  213
+A clock domain is identified by its name (a string). A design with multiple clock domains passes a dictionary instead of a list of synchronous statements in the ``Fragment`` constructor. Keys of that dictionary are the names of the clock domains, and the associated values are the statements that should be executed at each cycle of the clock in that domain.
  214
+
  215
+Mapping clock domain names to clock signals is done during conversion. The ``clock_domain`` parameter of the conversion function accepts a dictionary keyed by clock domain names that contains ``ClockDomain`` objects. ``ClockDomain`` objects are containers for a clock signal and a optional reset signal. Those signals can be driven like other FHDL signals.
35  doc/simulation.rst
Source Rendered
@@ -131,38 +131,3 @@ The generic top-level object
131 131
 Migen comes with a ``migen.sim.generic.TopLevel`` object that implements the above behaviour. It should be usable in the majority of cases.
132 132
 
133 133
 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).
134  
-
135  
-Simulation examples
136  
-*******************
137  
-
138  
-Most basic
139  
-==========
140  
-.. include:: ../examples/sim/basic1.py
141  
-   :code: python
142  
-
143  
-A few more features
144  
-===================
145  
-.. include:: ../examples/sim/basic2.py
146  
-   :code: python
147  
-
148  
-Memory access
149  
-=============
150  
-.. include:: ../examples/sim/memory.py
151  
-   :code: python
152  
-
153  
-A FIR filter
154  
-============
155  
-.. include:: ../examples/sim/fir.py
156  
-   :code: python
157  
-   
158  
-Abstract bus transactions
159  
-=========================
160  
-.. include:: ../examples/sim/abstract_transactions.py
161  
-   :code: python
162  
-
163  
-.. _dfsimexample:
164  
-   
165  
-Dataflow simulation actors
166  
-==========================
167  
-.. include:: ../examples/sim/dataflow.py
168  
-   :code: python

No commit comments for this range

Something went wrong with that request. Please try again.