1MIGEN(1) Migen MIGEN(1)
2
6 migen - Migen manual
7
9 Migen is a Python-based tool that aims at automating further the VLSI
10 design process.
11 Migen makes it possible to apply modern software concepts such as
13 object-oriented programming and metaprogramming to design hardware.
14 This results in more elegant and easily maintained designs and reduces
15 the incidence of human errors.
16 Background
18 Even though the Milkymist system-on-chip [mm] had many successes, it
19 suffers from several limitations stemming from its implementation in
20 manually written Verilog HDL:
21 [mm] http://m-labs.hk
23 1. The "event-driven" paradigm of today's dominant hardware descrip‐
25 tions languages (Verilog and VHDL, collectively referred to as
26 "V*HDL" in the rest of this document) is often too general. Today's
27 FPGA architectures are optimized for the implementation of fully
28 synchronous circuits. This means that the bulk of the code for an
29 efficient FPGA design falls into three categories:
30 1. Combinatorial statements
32 2. Synchronous statements
34 3. Initialization of registers at reset
36 V*HDL do not follow this organization. This means that a lot of
38 repetitive manual coding is needed, which brings sources of human
39 errors, petty issues, and confusion for beginners:
40 1. wire vs. reg in Verilog
42 2. forgetting to initialize a register at reset
44 3. deciding whether a combinatorial statement must go into a
46 process/always block or not
47 4. simulation mismatches with combinatorial processes/always blocks
49 5. and more...
51 A little-known fact about FPGAs is that many of them have the abil‐
53 ity to initialize their registers from the bitstream contents. This
54 can be done in a portable and standard way using an "initial" block
55 in Verilog, and by affecting a value at the signal declaration in
56 VHDL. This renders an explicit reset signal unnecessary in practice
57 in some cases, which opens the way for further design optimization.
58 However, this form of initialization is entirely not synthesizable
59 for ASIC targets, and it is not easy to switch between the two forms
60 of reset using V*HDL.
61 2. V*HDL support for composite types is very limited. Signals having a
63 record type in VHDL are unidirectional, which makes them clumsy to
64 use e.g. in bus interfaces. There is no record type support in Ver‐
65 ilog, which means that a lot of copy-and-paste has to be done when
66 forwarding grouped signals.
67 3. V*HDL support for procedurally generated logic is extremely limited.
69 The most advanced forms of procedural generation of synthesizable
70 logic that V*HDL offers are CPP-style directives in Verilog, combi‐
71 natorial functions, and generate statements. Nothing really fancy,
72 and it shows. To give a few examples:
73 1. Building highly flexible bus interconnect is not possible. Even
75 arbitrating any given number of bus masters for commonplace pro‐
76 tocols such as Wishbone is difficult with the tools that V*HDL
77 puts at our disposal.
78 2. Building a memory infrastructure (including bus interconnect,
80 bridges and caches) that can automatically adapt itself at com‐
81 pile-time to any word size of the SDRAM is clumsy and tedious.
82 3. Building register banks for control, status and interrupt manage‐
84 ment of cores can also largely benefit from automation.
85 4. Many hardware acceleration problems can fit into the dataflow
87 programming model. Manual dataflow implementation in V*HDL has,
88 again, a lot of redundancy and potential for human errors. See
89 the Milkymist texture mapping unit [mthesis] [mxcell] for an
90 example of this. The amount of detail to deal with manually also
91 makes the design space exploration difficult, and therefore hin‐
92 ders the design of efficient architectures.
93 5. Pre-computation of values, such as filter coefficients for DSP or
95 even simply trigonometric tables, must often be done using exter‐
96 nal tools whose results are copy-and-pasted (in the best case,
97 automatically) into the V*HDL source.
98 [mthesis]
100 http://m-labs.hk/thesis/thesis.pdf
101 [mxcell]
103 http://www.xilinx.com/publications/archives/xcell/Xcell77.pdf
104 p30-35
105 Enter Migen, a Python toolbox for building complex digital hard‐
107 ware. We could have designed a brand new programming language, but
108 that would have been reinventing the wheel instead of being able
109 to benefit from Python's rich features and immense library. The
110 price to pay is a slightly cluttered syntax at times when writing
111 descriptions in FHDL, but we believe this is totally acceptable,
112 particularly when compared to VHDL ;-)
113 Migen is made up of several related components:
115 1. the base language, FHDL
117 2. a library of small generic cores
119 3. a simulator
121 4. a build system
123 Installing Migen
125 Either run the setup.py installation script or simply set PYTHONPATH to
126 the root of the source directory.
127 If you wish to contribute patches, the suggest way to install is;
129 1. Clone from the git repository at
131 http://github.com/m-labs/migen
132 2. Install using python3 ./setup.py develop --user
134 3. Edit the code in your git checkout.
136 Alternative install methods
138 · Migen is available for the Anaconda Python distribution. The pack‐
139 age can be found at at https://anaconda.org/m-labs/migen
140 · Migen can be referenced in a requirements.txt file (used for pip
142 install -r requirements.txt) via -e
143 git+http://github.com/m-labs/migen.git#egg=migen. See the pip doc‐
144 umentation for more information.
145 Feedback
147 Feedback concerning Migen or this manual should be sent to the M-Labs
148 developers' mailing list devel on lists.m-labs.hk.
149
151 The Fragmented Hardware Description Language (FHDL) is the basis of
152 Migen. It consists of a formal system to describe signals, and combina‐
153 torial and synchronous statements operating on them. The formal system
154 itself is low level and close to the synthesizable subset of Verilog,
155 and we then rely on Python algorithms to build complex structures by
156 combining FHDL elements. The FHDL module also contains a back-end to
157 produce synthesizable Verilog, and some structure analysis and manipu‐
158 lation functionality.
159 FHDL differs from MyHDL [myhdl] in fundamental ways. MyHDL follows the
161 event-driven paradigm of traditional HDLs (see background) while FHDL
162 separates the code into combinatorial statements, synchronous state‐
163 ments, and reset values. In MyHDL, the logic is described directly in
164 the Python AST. The converter to Verilog or VHDL then examines the
165 Python AST and recognizes a subset of Python that it translates into
166 V*HDL statements. This seriously impedes the capability of MyHDL to
167 generate logic procedurally. With FHDL, you manipulate a custom AST
168 from Python, and you can more easily design algorithms that operate on
169 it.
170 [myhdl]
172 http://www.myhdl.org
173 FHDL is made of several elements, which are briefly explained
175 below. They all can be imported directly from the migen module.
176 Expressions
178 Constants
179 The Constant object represents a constant, HDL-literal integer. It
180 behaves like specifying integers and booleans but also supports slicing
181 and can have a bit width or signedness different from what is implied
182 by the value it represents.
183 True and False are interpreted as 1 and 0, respectively.
185 Negative integers are explicitly supported. As with MyHDL [countin],
187 arithmetic operations return the natural results.
188 To lighten the syntax, assignments and operators automatically wrap
190 Python integers and booleans into Constant. Additionally, Constant is
191 aliased to C. The following are valid Migen statements: a.eq(0), a.eq(a
192 + 1), a.eq(C(42)[0:1]).
193 [countin]
195 http://www.jandecaluwe.com/hdldesign/counting.html
196 Signal
198 The signal object represents a value that is expected to change in the
199 circuit. It does exactly what Verilog's "wire" and "reg" and VHDL's
200 "signal" do.
201 The main point of the signal object is that it is identified by its
203 Python ID (as returned by the id() function), and nothing else. It is
204 the responsibility of the V*HDL back-end to establish an injective map‐
205 ping between Python IDs and the V*HDL namespace. It should perform name
206 mangling to ensure this. The consequence of this is that signal objects
207 can safely become members of arbitrary Python classes, or be passed as
208 parameters to functions or methods that generate logic involving them.
209 The properties of a signal object are:
211 · An integer or a (integer, boolean) pair that defines the number of
213 bits and whether the bit of higher index of the signal is a sign bit
214 (i.e. the signal is signed). The defaults are one bit and unsigned.
215 Alternatively, the min and max parameters can be specified to define
216 the range of the signal and determine its bit width and signedness.
217 As with Python ranges, min is inclusive and defaults to 0, max is
218 exclusive and defaults to 2.
219 · A name, used as a hint for the V*HDL back-end name mangler.
221 · The signal's reset value. It must be an integer, and defaults to 0.
223 When the signal's value is modified with a synchronous statement, the
224 reset value is the initialization value of the associated register.
225 When the signal is assigned to in a conditional combinatorial state‐
226 ment (If or Case), the reset value is the value that the signal has
227 when no condition that causes the signal to be driven is verified.
228 This enforces the absence of latches in designs. If the signal is
229 permanently driven using a combinatorial statement, the reset value
230 has no effect.
231 The sole purpose of the name property is to make the generated V*HDL
233 code easier to understand and debug. From a purely functional point of
234 view, it is perfectly OK to have several signals with the same name
235 property. The back-end will generate a unique name for each object. If
236 no name property is specified, Migen will analyze the code that created
237 the signal object, and try to extract the variable or member name from
238 there. For example, the following statements will create one or several
239 signals named "bar":
240 bar = Signal()
242 self.bar = Signal()
243 self.baz.bar = Signal()
244 bar = [Signal() for x in range(42)]
245 In case of conflicts, Migen tries first to resolve the situation by
247 prefixing the identifiers with names from the class and module hierar‐
248 chy that created them. If the conflict persists (which can be the case
249 if two signal objects are created with the same name in the same con‐
250 text), it will ultimately add number suffixes.
251 Operators
253 Operators are represented by the _Operator object, which generally
254 should not be used directly. Instead, most FHDL objects overload the
255 usual Python logic and arithmetic operators, which allows a much
256 lighter syntax to be used. For example, the expression:
257 a * b + c
259 is equivalent to:
261 _Operator("+", [_Operator("*", [a, b]), c])
263 Slices
265 Likewise, slices are represented by the _Slice object, which often
266 should not be used in favor of the Python slice operation [x:y].
267 Implicit indices using the forms [x], [x:] and [:y] are supported.
268 Beware! Slices work like Python slices, not like VHDL or Verilog
269 slices. The first bound is the index of the LSB and is inclusive. The
270 second bound is the index of MSB and is exclusive. In V*HDL, bounds are
271 MSB:LSB and both are inclusive.
272 Concatenations
274 Concatenations are done using the Cat object. To make the syntax
275 lighter, its constructor takes a variable number of arguments, which
276 are the signals to be concatenated together (you can use the Python "*"
277 operator to pass a list instead). To be consistent with slices, the
278 first signal is connected to the bits with the lowest indices in the
279 result. This is the opposite of the way the "{}" construct works in
280 Verilog.
281 Replications
283 The Replicate object represents the equivalent of {count{expression}}
284 in Verilog. For example, the expression:
285 Replicate(0, 4)
287 is equivalent to:
289 Cat(0, 0, 0, 0)
291 Statements
293 Assignment
294 Assignments are represented with the _Assign object. Since using it
295 directly would result in a cluttered syntax, the preferred technique
296 for assignments is to use the eq() method provided by objects that can
297 have a value assigned to them. They are signals, and their combinations
298 with the slice and concatenation operators. As an example, the state‐
299 ment:
300 a[0].eq(b)
302 is equivalent to:
304 _Assign(_Slice(a, 0, 1), b)
306 If
308 The If object takes a first parameter which must be an expression (com‐
309 bination of the Constant, Signal, _Operator, _Slice, etc. objects) rep‐
310 resenting the condition, then a variable number of parameters repre‐
311 senting the statements (_Assign, If, Case, etc. objects) to be executed
312 when the condition is verified.
313 The If object defines a Else() method, which when called defines the
315 statements to be executed when the condition is not true. Those state‐
316 ments are passed as parameters to the variadic method.
317 For convenience, there is also a Elif() method.
319 Example:
321 If(tx_count16 == 0,
323 tx_bitcount.eq(tx_bitcount + 1),
324 If(tx_bitcount == 8,
325 self.tx.eq(1)
326 ).Elif(tx_bitcount == 9,
327 self.tx.eq(1),
328 tx_busy.eq(0)
329 ).Else(
330 self.tx.eq(tx_reg[0]),
331 tx_reg.eq(Cat(tx_reg[1:], 0))
332 )
333 )
334 Case
336 The Case object constructor takes as first parameter the expression to
337 be tested, and a dictionary whose keys are the values to be matched,
338 and values the statements to be executed in the case of a match. The
339 special value "default" can be used as match value, which means the
340 statements should be executed whenever there is no other match.
341 Arrays
343 The Array object represents lists of other objects that can be indexed
344 by FHDL expressions. It is explicitly possible to:
345 · nest Array objects to create multidimensional tables.
347 · list any Python object in a Array as long as every expression appear‐
349 ing in a module ultimately evaluates to a Signal for all possible
350 values of the indices. This allows the creation of lists of struc‐
351 tured data.
352 · use expressions involving Array objects in both directions (assign‐
354 ment and reading).
355 For example, this creates a 4x4 matrix of 1-bit signals:
357 my_2d_array = Array(Array(Signal() for a in range(4)) for b in range(4))
359 You can then read the matrix with (x and y being 2-bit signals):
361 out.eq(my_2d_array[x][y])
363 and write it with:
365 my_2d_array[x][y].eq(inp)
367 Since they have no direct equivalent in Verilog, Array objects are low‐
369 ered into multiplexers and conditional statements before the actual
370 conversion takes place. Such lowering happens automatically without any
371 user intervention.
372 Any out-of-bounds access performed on an Array object will refer to the
374 last element.
375 Specials
377 Tri-state I/O
378 A triplet (O, OE, I) of one-way signals defining a tri-state I/O port
379 is represented by the TSTriple object. Such objects are only containers
380 for signals that are intended to be later connected to a tri-state I/O
381 buffer, and cannot be used as module specials. Such objects, however,
382 should be kept in the design as long as possible as they allow the
383 individual one-way signals to be manipulated in a non-ambiguous way.
384 The object that can be used in as a module special is Tristate, and it
386 behaves exactly like an instance of a tri-state I/O buffer that would
387 be defined as follows:
388 Instance("Tristate",
390 io_target=target,
391 i_o=o,
392 i_oe=oe,
393 o_i=i
394 )
395 Signals target, o and i can have any width, while oe is 1-bit wide. The
397 target signal should go to a port and not be used elsewhere in the
398 design. Like modern FPGA architectures, Migen does not support internal
399 tri-states.
400 A Tristate object can be created from a TSTriple object by calling the
402 get_tristate method.
403 By default, Migen emits technology-independent behavioral code for a
405 tri-state buffer. If a specific code is needed, the tristate handler
406 can be overriden using the appropriate parameter of the V*HDL conver‐
407 sion function.
408 Instances
410 Instance objects represent the parametrized instantiation of a V*HDL
411 module, and the connection of its ports to FHDL signals. They are use‐
412 ful in a number of cases:
413 · Reusing legacy or third-party V*HDL code.
415 · Using special FPGA features (DCM, ICAP, ...).
417 · Implementing logic that cannot be expressed with FHDL (e.g. latches).
419 · Breaking down a Migen system into multiple sub-systems.
421 The instance object constructor takes the type (i.e. name of the
423 instantiated module) of the instance, then multiple parameters describ‐
424 ing how to connect and parametrize the instance.
425 These parameters can be:
427 · Instance.Input, Instance.Output or Instance.InOut to describe signal
429 connections with the instance. The parameters are the name of the
430 port at the instance, and the FHDL expression it should be connected
431 to.
432 · Instance.Parameter sets a parameter (with a name and value) of the
434 instance.
435 · Instance.ClockPort and Instance.ResetPort are used to connect clock
437 and reset signals to the instance. The only mandatory parameter is
438 the name of the port at the instance. Optionally, a clock domain name
439 can be specified, and the invert option can be used to interface to
440 those modules that require a 180-degree clock or a active-low reset.
441 Memories
443 Memories (on-chip SRAM) are supported using a mechanism similar to
444 instances.
445 A memory object has the following parameters:
447 · The width, which is the number of bits in each word.
449 · The depth, which represents the number of words in the memory.
451 · An optional list of integers used to initialize the memory.
453 To access the memory in hardware, ports can be obtained by calling the
455 get_port method. A port always has an address signal a and a data read
456 signal dat_r. Other signals may be available depending on the port's
457 configuration.
458 Options to get_port are:
460 · write_capable (default: False): if the port can be used to write to
462 the memory. This creates an additional we signal.
463 · async_read (default: False): whether reads are asychronous (combina‐
465 torial) or synchronous (registered).
466 · has_re (default: False): adds a read clock-enable signal re (ignored
468 for asychronous ports).
469 · we_granularity (default: 0): if non-zero, writes of less than a mem‐
471 ory word can occur. The width of the we signal is increased to act as
472 a selection signal for the sub-words.
473 · mode (default: WRITE_FIRST, ignored for aynchronous ports). It can
475 be:
476 · READ_FIRST: during a write, the previous value is read.
478 · WRITE_FIRST: the written value is returned.
480 · NO_CHANGE: the data read signal keeps its previous value on a
482 write.
483 · clock_domain (default: "sys"): the clock domain used for reading and
485 writing from this port.
486 Migen generates behavioural V*HDL code that should be compatible with
488 all simulators and, if the number of ports is <= 2, most FPGA synthe‐
489 sizers. If a specific code is needed, the memory handler can be overri‐
490 den using the appropriate parameter of the V*HDL conversion function.
491 Modules
493 Modules play the same role as Verilog modules and VHDL entities. Simi‐
494 larly, they are organized in a tree structure. A FHDL module is a
495 Python object that derives from the Module class. This class defines
496 special attributes to be used by derived classes to describe their
497 logic. They are explained below.
498 Combinatorial statements
500 A combinatorial statement is a statement that is executed whenever one
501 of its inputs changes.
502 Combinatorial statements are added to a module by using the comb spe‐
504 cial attribute. Like most module special attributes, it must be
505 accessed using the += incrementation operator, and either a single
506 statement, a tuple of statements or a list of statements can appear on
507 the right hand side.
508 For example, the module below implements a OR gate:
510 class ORGate(Module):
512 def __init__(self):
513 self.a = Signal()
514 self.b = Signal()
515 self.x = Signal()
516 ###
518 self.comb += self.x.eq(self.a | self.b)
520 To improve code readability, it is recommended to place the interface
522 of the module at the beginning of the __init__ function, and separate
523 it from the implementation using three hash signs.
524 Synchronous statements
526 A synchronous statements is a statement that is executed at each edge
527 of some clock signal.
528 They are added to a module by using the sync special attribute, which
530 has the same properties as the comb attribute.
531 The sync special attribute also has sub-attributes that correspond to
533 abstract clock domains. For example, to add a statement to the clock
534 domain named foo, one would write self.sync.foo += statement. The
535 default clock domain is sys and writing self.sync += statement is
536 equivalent to writing self.sync.sys += statement.
537 Submodules and specials
539 Submodules and specials can be added by using the submodules and spe‐
540 cials attributes respectively. This can be done in two ways:
541 1. anonymously, by using the += operator on the special attribute
543 directly, e.g. self.submodules += some_other_module. Like with the
544 comb and sync attributes, a single module/special or a tuple or list
545 can be specified.
546 2. by naming the submodule/special using a subattribute of the submod‐
548 ules or specials attribute, e.g. self.submodules.foo = module_foo.
549 The submodule/special is then accessible as an attribute of the
550 object, e.g. self.foo (and not self.submodules.foo). Only one sub‐
551 module/special can be added at a time using this form.
552 Clock domains
554 Specifying the implementation of a clock domain is done using the
555 ClockDomain object. It contains the name of the clock domain, a clock
556 signal that can be driven like any other signal in the design (for
557 example, using a PLL instance), and optionally a reset signal. Clock
558 domains without a reset signal are reset using e.g. initial statements
559 in Verilog, which in many FPGA families initalize the registers during
560 configuration.
561 The name can be omitted if it can be extracted from the variable name.
563 When using this automatic naming feature, prefixes _, cd_ and _cd_ are
564 removed.
565 Clock domains are then added to a module using the clock_domains spe‐
567 cial attribute, which behaves exactly like submodules and specials.
568 Summary of special attributes
570 ┌───────────────────────────┬────────────────────────────┐
571 │Syntax │ Action │
572 ├───────────────────────────┼────────────────────────────┤
573 │self.comb += stmt │ Add combinatorial state‐ │
574 │ │ ment to current module. │
575 ├───────────────────────────┼────────────────────────────┤
576 │self.comb += stmtA, stmtB │ Add combinatorial state‐ │
577 │ │ ments A and B to current │
578 │self.comb += [stmtA, │ module. │
579 │stmtB] │ │
580 ├───────────────────────────┼────────────────────────────┤
581 │self.sync += stmt │ Add synchronous statement │
582 │ │ to current module, in │
583 │ │ default clock domain sys. │
584 ├───────────────────────────┼────────────────────────────┤
585 │self.sync.foo += stmt │ Add synchronous statement │
586 │ │ to current module, in │
587 │ │ clock domain foo. │
588 ├───────────────────────────┼────────────────────────────┤
589 │self.sync.foo += stmtA, │ Add synchronous statements │
590 │stmtB │ A and B to current module, │
591 │ │ in clock domain foo. │
592 │self.sync.foo += [stmtA, │ │
593 │stmtB] │ │
594 ├───────────────────────────┼────────────────────────────┤
595 │self.submodules += mod │ Add anonymous submodule to │
596 │ │ current module. │
597 ├───────────────────────────┼────────────────────────────┤
598 │self.submodules += modA, │ Add anonymous submodules A │
599 │modB │ and B to current module. │
600 │ │ │
601 │self.submodules += [modA, │ │
602 │modB] │ │
603 └───────────────────────────┴────────────────────────────┘
604 │self.submodules.bar = mod │ Add submodule named bar to │
606 │ │ current module. The sub‐ │
607 │ │ module can then be │
608 │ │ accessed using self.bar. │
609 ├───────────────────────────┼────────────────────────────┤
610 │self.specials += spe │ Add anonymous special to │
611 │ │ current module. │
612 ├───────────────────────────┼────────────────────────────┤
613 │self.specials += speA, │ Add anonymous specials A │
614 │speB │ and B to current module. │
615 │ │ │
616 │self.specials += [speA, │ │
617 │speB] │ │
618 ├───────────────────────────┼────────────────────────────┤
619 │self.specials.bar = spe │ Add special named bar to │
620 │ │ current module. The spe‐ │
621 │ │ cial can then be accessed │
622 │ │ using self.bar. │
623 ├───────────────────────────┼────────────────────────────┤
624 │self.clock_domains += cd │ Add clock domain to cur‐ │
625 │ │ rent module. │
626 ├───────────────────────────┼────────────────────────────┤
627 │self.clock_domains += cdA, │ Add clock domains A and B │
628 │cdB │ to current module. │
629 │ │ │
630 │self.clock_domains += │ │
631 │[cdA, cdB] │ │
632 ├───────────────────────────┼────────────────────────────┤
633 │self.clock_domains.pix = │ Create and add clock │
634 │ClockDomain() │ domain pix to current mod‐ │
635 │ │ ule. The clock domain name │
636 │self.clock_domains._pix = │ is pix in all cases. It │
637 │ClockDomain() │ can be accessed using │
638 │ │ self.pix, self._pix, │
639 │self.clock_domains.cd_pix │ self.cd_pix and │
640 │= ClockDomain() │ self._cd_pix, respec‐ │
641 │ │ tively. │
642 │self.clock_domains._cd_pix │ │
643 │= ClockDomain() │ │
644 └───────────────────────────┴────────────────────────────┘
645 Clock domain management
647 When a module has named submodules that define one or several clock
648 domains with the same name, those clock domain names are prefixed with
649 the name of each submodule plus an underscore.
650 An example use case of this feature is a system with two independent
652 video outputs. Each video output module is made of a clock generator
653 module that defines a clock domain pix and drives the clock signal,
654 plus a driver module that has synchronous statements and other elements
655 in clock domain pix. The designer of the video output module can simply
656 use the clock domain name pix in that module. In the top-level system
657 module, the video output submodules are named video0 and video1. Migen
658 then automatically renames the pix clock domain of each module to
659 video0_pix and video1_pix. Note that happens only because the clock
660 domain is defined (using ClockDomain objects), not simply referenced
661 (using e.g. synchronous statements) in the video output modules.
662 Clock domain name overlap is an error condition when any of the submod‐
664 ules that defines the clock domains is anonymous.
665 Finalization mechanism
667 Sometimes, it is desirable that some of a module logic be created only
668 after the user has finished manipulating that module. For example, the
669 FSM module supports that states be defined dynamically, and the width
670 of the state signal can be known only after all states have been added.
671 One solution is to declare the final number of states in the FSM con‐
672 structor, but this is not user-friendly. A better solution is to auto‐
673 matically create the state signal just before the FSM module is con‐
674 verted to V*HDL. Migen supports this using the so-called finalization
675 mechanism.
676 Modules can overload a do_finalize method that can create logic and is
678 called using the algorithm below:
679 1. Finalization of the current module begins.
681 2. If the module has already been finalized (e.g. manually), the proce‐
683 dure stops here.
684 3. Submodules of the current module are recursively finalized.
686 4. do_finalize is called for the current module.
688 5. Any new submodules created by the current module's do_finalize are
690 recursively finalized.
691 Finalization is automatically invoked at V*HDL conversion and at simu‐
693 lation. It can be manually invoked for any module by calling its final‐
694 ize method.
695 The clock domain management mechanism explained above happens during
697 finalization.
698 Conversion for synthesis
700 Any FHDL module can be converted into synthesizable Verilog HDL. This
701 is accomplished by using the convert function in the migen.fhdl.verilog
702 module:
703 # define FHDL module MyDesign here
705 if __name__ == "__main__":
707 from migen.fhdl.verilog import convert
708 convert(MyDesign()).write("my_design.v")
709 The migen.build component provides scripts to interface third-party
711 FPGA tools (from Xilinx, Altera and Lattice) to Migen, and a database
712 of boards for the easy deployment of designs.
713
715 Migen allows you to easily simulate your FHDL design and interface it
716 with arbitrary Python code. The simulator is written in pure Python and
717 interprets the FHDL structure directly without using an external Ver‐
718 ilog simulator.
719 Migen lets you write testbenches using Python's generator functions.
721 Such testbenches execute concurrently with the FHDL simulator, and com‐
722 municate with it using the yield statement. There are four basic pat‐
723 terns:
724 1. Reads: the state of the signal at the current time can be queried
726 using (yield signal);
727 2. Writes: the state of the signal after the next clock cycle can be
729 set using (yield signal.eq(value));
730 3. Clocking: simulation can be advanced by one clock cycle using
732 yield;
733 4. Composition: control can be transferred to another testbench
735 function using yield from run_other().
736 A testbench can be run using the run_simulation function from
738 migen.sim; run_simulation(dut, bench) runs the generator function bench
739 against the logic defined in an FHDL module dut.
740 Passing the vcd_name="file.vcd" argument to run_simulation will cause
742 it to write a VCD dump of the signals inside dut to file.vcd.
743 Examples
745 For example, consider this module:
746 class ORGate(Module):
748 def __init__(self):
749 self.a = Signal()
750 self.b = Signal()
751 self.x = Signal()
752 ###
754 self.comb += self.x.eq(self.a | self.b)
756 It could be simulated together with the following testbench:
758 dut = ORGate()
760 def testbench():
762 yield dut.a.eq(0)
763 yield dut.b.eq(0)
764 yield
765 assert (yield dut.x) == 0
766 yield dut.a.eq(0)
768 yield dut.b.eq(1)
769 yield
770 assert (yield dut.x) == 1
771 run_simulation(dut, testbench())
773 This is, of course, quite verbose, and individual steps can be factored
775 into a separate function:
776 dut = ORGate()
778 def check_case(a, b, x):
780 yield dut.a.eq(a)
781 yield dut.b.eq(b)
782 yield
783 assert (yield dut.x) == x
784 def testbench():
786 yield from check_case(0, 0, 0)
787 yield from check_case(0, 1, 1)
788 yield from check_case(1, 0, 1)
789 yield from check_case(1, 1, 1)
790 run_simulation(dut, testbench())
792 Pitfalls
794 There are, unfortunately, some basic mistakes that can produce very
795 puzzling results.
796 When calling other testbenches, it is important to not forget the yield
798 from. If it is omitted, the call would silently do nothing.
799 When writing to a signal, it is important that nothing else should
801 drive the signal concurrently. If that is not the case, the write would
802 silently do nothing.
803
805 [To be written]
806
808 fhdl.structure module
809 class migen.fhdl.structure.Array
810 Bases: list
811 Addressable multiplexer
813 An array is created from an iterable of values and indexed using
815 the usual Python simple indexing notation (no negative indices
816 or slices). It can be indexed by numeric constants, _Value s, or
817 Signal s.
818 The result of indexing the array is a proxy for the entry at the
820 given index that can be used on either RHS or LHS of assign‐
821 ments.
822 An array can be indexed multiple times.
824 Multidimensional arrays are supported by packing inner arrays
826 into outer arrays.
827 Parameters
829 values (iterable of ints, _Values, Signals) -- Entries of
830 the array. Each entry can be a numeric constant, a Signal
831 or a Record.
832 Examples.sp
833 >>> a = Array(range(10))
834 >>> b = Signal(max=10)
835 >>> c = Signal(max=10)
836 >>> b.eq(a[9 - c])
837 migen.fhdl.structure.C
839 alias of migen.fhdl.structure.Constant
840 class migen.fhdl.structure.Case(test, cases)
842 Bases: migen.fhdl.structure._Statement
843 Case/Switch statement
845 Parameters
847 · test (_Value, in) -- Selector value used to decide
849 which block to execute
850 · cases (dict) -- Dictionary of cases. The keys are
852 numeric constants to compare with test. The values are
853 statements to be executed the corresponding key matches
854 test. The dictionary may contain a string key "default"
855 to mark a fall-through case that is executed if no
856 other key matches.
857 Examples.sp
858 >>> a = Signal()
859 >>> b = Signal()
860 >>> Case(a, {
861 ... 0: b.eq(1),
862 ... 1: b.eq(0),
863 ... "default": b.eq(0),
864 ... })
865 makedefault(key=None)
867 Mark a key as the default case
868 Deletes/substitutes any previously existing default case.
870 Parameters
872 key (int, Constant or None) -- Key to use as
873 default case if no other key matches. By default,
874 the largest key is the default key.
875 class migen.fhdl.structure.Cat(*args)
877 Bases: migen.fhdl.structure._Value
878 Concatenate values
880 Form a compound _Value from several smaller ones by concatena‐
882 tion. The first argument occupies the lower bits of the result.
883 The return value can be used on either side of an assignment,
884 that is, the concatenated value can be used as an argument on
885 the RHS or as a target on the LHS. If it is used on the LHS, it
886 must solely consist of Signal s, slices of Signal s, and other
887 concatenations meeting these properties. The bit length of the
888 return value is the sum of the bit lengths of the arguments:
889 len(Cat(args)) == sum(len(arg) for arg in args)
891 Parameters
893 *args (_Values or iterables of _Values, inout) -- _Value
894 s to be concatenated.
895 Returns
897 Resulting _Value obtained by concatentation.
898 Return type
900 Cat, inout
901 class migen.fhdl.structure.ClockDomain(name=None, reset_less=False)
903 Bases: object
904 Synchronous domain
906 Parameters
908 · name (str or None) -- Domain name. If None (the
910 default) the name is inferred from the variable name
911 this ClockDomain is assigned to (stripping any "cd_"
912 prefix).
913 · reset_less (bool) -- The domain does not use a reset
915 signal. Registers within this domain are still all ini‐
916 tialized to their reset state once, e.g. through Ver‐
917 ilog "initial" statements.
918 clk The clock for this domain. Can be driven or used to drive
920 other signals (preferably in combinatorial context).
921 Type Signal, inout
923 rst Reset signal for this domain. Can be driven or used to
925 drive.
926 Type Signal or None, inout
928 rename(new_name)
930 Rename the clock domain
931 Parameters
933 new_name (str) -- New name
934 class migen.fhdl.structure.ClockSignal(cd='sys')
936 Bases: migen.fhdl.structure._Value
937 Clock signal for a given clock domain
939 ClockSignal s for a given clock domain can be retrieved multiple
941 times. They all ultimately refer to the same signal.
942 Parameters
944 cd (str) -- Clock domain to obtain a clock signal for.
945 Defaults to "sys".
946 class migen.fhdl.structure.Constant(value, bits_sign=None)
948 Bases: migen.fhdl.structure._Value
949 A constant, HDL-literal integer _Value
951 Parameters
953 · value (int) --
955 · bits_sign (int or tuple or None) -- Either an integer
957 bits or a tuple (bits, signed) specifying the number of
958 bits in this Constant and whether it is signed (can
959 represent negative values). bits_sign defaults to the
960 minimum width and signedness of value.
961 class migen.fhdl.structure.DUID
963 Bases: object
964 Deterministic Unique IDentifier
966 class migen.fhdl.structure.If(cond, *t)
968 Bases: migen.fhdl.structure._Statement
969 Conditional execution of statements
971 Parameters
973 · cond (_Value(1), in) -- Condition
975 · *t (Statements) -- Statements to execute if cond is
977 asserted.
978 Examples.sp
979 >>> a = Signal()
980 >>> b = Signal()
981 >>> c = Signal()
982 >>> d = Signal()
983 >>> If(a,
984 ... b.eq(1)
985 ... ).Elif(c,
986 ... b.eq(0)
987 ... ).Else(
988 ... b.eq(d)
989 ... )
990 Elif(cond, *t)
992 Add an else if conditional block
993 Parameters
995 · cond (_Value(1), in) -- Condition
997 · *t (Statements) -- Statements to execute if pre‐
999 vious conditions fail and cond is asserted.
1000 Else(*f)
1002 Add an else conditional block
1003 Parameters
1005 *f (Statements) -- Statements to execute if all
1006 previous conditions fail.
1007 migen.fhdl.structure.Mux(sel, val1, val0)
1009 Multiplex between two values
1010 Parameters
1012 · sel (_Value(1), in) -- Selector.
1014 · val1 (_Value(N), in) --
1016 · val0 (_Value(N), in) -- Input values.
1018 Returns
1020 Output _Value. If sel is asserted, the Mux returns val1,
1021 else val0.
1022 Return type
1024 _Value(N), out
1025 class migen.fhdl.structure.Replicate(v, n)
1027 Bases: migen.fhdl.structure._Value
1028 Replicate a value
1030 An input value is replicated (repeated) several times to be used
1032 on the RHS of assignments:
1033 len(Replicate(s, n)) == len(s)*n
1035 Parameters
1037 · v (_Value, in) -- Input value to be replicated.
1039 · n (int) -- Number of replications.
1041 Returns
1043 Replicated value.
1044 Return type
1046 Replicate, out
1047 class migen.fhdl.structure.ResetSignal(cd='sys',
1049 allow_reset_less=False)
1050 Bases: migen.fhdl.structure._Value
1051 Reset signal for a given clock domain
1053 ResetSignal s for a given clock domain can be retrieved multiple
1055 times. They all ultimately refer to the same signal.
1056 Parameters
1058 · cd (str) -- Clock domain to obtain a reset signal for.
1060 Defaults to "sys".
1061 · allow_reset_less (bool) -- If the clock domain is
1063 resetless, return 0 instead of reporting an error.
1064 class migen.fhdl.structure.Signal(bits_sign=None, name=None, vari‐
1066 able=False, reset=0, reset_less=False, name_override=None, min=None,
1067 max=None, related=None, attr=None)
1068 Bases: migen.fhdl.structure._Value
1069 A _Value that can change
1071 The Signal object represents a value that is expected to change
1073 in the circuit. It does exactly what Verilog's wire and reg and
1074 VHDL's signal do.
1075 A Signal can be indexed to access a subset of its bits. Negative
1077 indices (signal[-1]) and the extended Python slicing notation
1078 (signal[start:stop:step]) are supported. The indices 0 and -1
1079 are the least and most significant bits respectively.
1080 Parameters
1082 · bits_sign (int or tuple) -- Either an integer bits or a
1084 tuple (bits, signed) specifying the number of bits in
1085 this Signal and whether it is signed (can represent
1086 negative values). signed defaults to False.
1087 · name (str or None) -- Name hint for this signal. If
1089 None (default) the name is inferred from the variable
1090 name this Signal is assigned to. Name collisions are
1091 automatically resolved by prepending names of objects
1092 that contain this Signal and by appending integer
1093 sequences.
1094 · variable (bool) -- Deprecated.
1096 · reset (int) -- Reset (synchronous) or default (combina‐
1098 torial) value. When this Signal is assigned to in syn‐
1099 chronous context and the corresponding clock domain is
1100 reset, the Signal assumes the given value. When this
1101 Signal is unassigned in combinatorial context (due to
1102 conditional assignments not being taken), the Signal
1103 assumes its reset value. Defaults to 0.
1104 · reset_less (bool) -- If True, do not generate reset
1106 logic for this Signal in synchronous statements. The
1107 reset value is only used as a combinatorial default or
1108 as the initial value. Defaults to False.
1109 · name_override (str or None) -- Do not use the inferred
1111 name but the given one.
1112 · min (int or None) --
1114 · max (int or None) -- If bits_sign is None, the signal
1116 bit width and signedness are determined by the integer
1117 range given by min (inclusive, defaults to 0) and max
1118 (exclusive, defaults to 2).
1119 · related (Signal or None) --
1121 · attr (set of synthesis attributes) --
1123 classmethod like(other, **kwargs)
1125 Create Signal based on another.
1126 Parameters
1128 · other (_Value) -- Object to base this Signal on.
1130 · migen.fhdl.bitcontainer.value_bits_sign for
1132 details. (See) --
1133 migen.fhdl.structure.wrap(value)
1135 Ensures that the passed object is a Migen value. Booleans and
1136 integers are automatically wrapped into Constant.
1137 fhdl.bitcontainer module
1139 migen.fhdl.bitcontainer.value_bits_sign(v)
1140 Bit length and signedness of a value.
1141 Parameters
1143 v (Value) --
1144 Returns
1146 Number of bits required to store v or available in v,
1147 followed by whether v has a sign bit (included in the bit
1148 count).
1149 Return type
1151 int, bool
1152 Examples.sp
1153 >>> value_bits_sign(f.Signal(8))
1154 8, False
1155 >>> value_bits_sign(C(0xaa))
1156 8, False
1157 genlib.fifo module
1159 class migen.genlib.fifo.SyncFIFO(width, depth, fwft=True)
1160 Bases: migen.fhdl.module.Module, migen.genlib.fifo._FIFOInter‐
1161 face
1162 Synchronous FIFO (first in, first out)
1164 Read and write interfaces are accessed from the same clock
1166 domain. If different clock domains are needed, use AsyncFIFO.
1167 Data written to the input interface (din, we, writable) is
1169 buffered and can be read at the output interface (dout, re,
1170 readable). The data entry written first to the input also
1171 appears first on the output.
1172 Parameters
1174 · width (int) -- Bit width for the data.
1176 · depth (int) -- Depth of the FIFO.
1178 din Input data
1180 Type in, width
1182 writable
1184 There is space in the FIFO and we can be asserted to load
1185 new data.
1186 Type out
1188 we Write enable signal to latch din into the FIFO. Does
1190 nothing if writable is not asserted.
1191 Type in
1193 dout Output data. Only valid if readable is asserted.
1195 Type out, width
1197 readable
1199 Output data dout valid, FIFO not empty.
1200 Type out
1202 re Acknowledge dout. If asserted, the next entry will be
1204 available on the next cycle (if readable is high then).
1205 Type in
1207 level Number of unread entries.
1209 Type out
1211 replace
1213 Replaces the last entry written into the FIFO with din.
1214 Does nothing if that entry has already been read (i.e.
1215 the FIFO is empty). Assert in conjunction with we.
1216 Type in
1218 class migen.genlib.fifo.SyncFIFOBuffered(width, depth)
1220 Bases: migen.fhdl.module.Module, migen.genlib.fifo._FIFOInter‐
1221 face
1222 Has an interface compatible with SyncFIFO with fwft=True, but
1224 does not use asynchronous RAM reads that are not compatible with
1225 block RAMs. Increases latency by one cycle.
1226 class migen.genlib.fifo.AsyncFIFO(width, depth)
1228 Bases: migen.fhdl.module.Module, migen.genlib.fifo._FIFOInter‐
1229 face
1230 Asynchronous FIFO (first in, first out)
1232 Read and write interfaces are accessed from different clock
1234 domains, named read and write. Use ClockDomainsRenamer to rename
1235 to other names.
1236 Data written to the input interface (din, we, writable) is
1238 buffered and can be read at the output interface (dout, re,
1239 readable). The data entry written first to the input also
1240 appears first on the output.
1241 Parameters
1243 · width (int) -- Bit width for the data.
1245 · depth (int) -- Depth of the FIFO.
1247 din Input data
1249 Type in, width
1251 writable
1253 There is space in the FIFO and we can be asserted to load
1254 new data.
1255 Type out
1257 we Write enable signal to latch din into the FIFO. Does
1259 nothing if writable is not asserted.
1260 Type in
1262 dout Output data. Only valid if readable is asserted.
1264 Type out, width
1266 readable
1268 Output data dout valid, FIFO not empty.
1269 Type out
1271 re Acknowledge dout. If asserted, the next entry will be
1273 available on the next cycle (if readable is high then).
1274 Type in
1276 class migen.genlib.fifo.AsyncFIFOBuffered(width, depth)
1278 Bases: migen.fhdl.module.Module, migen.genlib.fifo._FIFOInter‐
1279 face
1280 Improves timing when it breaks due to sluggish clock-to-output
1282 delay in e.g. Xilinx block RAMs. Increases latency by one cycle.
1283 genlib.coding module
1285 Encoders and decoders between binary and one-hot representation
1286 class migen.genlib.coding.Decoder(width)
1288 Bases: migen.fhdl.module.Module
1289 Decode binary to one-hot
1291 If n is low, the i th bit in o is asserted, the others are not,
1293 else o == 0.
1294 Parameters
1296 width (int) -- Bit width of the output
1297 i Input binary
1299 Type Signal(max=width), in
1301 o Decoded one-hot
1303 Type Signal(width), out
1305 n Invalid, no output bits are to be asserted
1307 Type [22mSignal(1), in
1309 class migen.genlib.coding.Encoder(width)
1311 Bases: migen.fhdl.module.Module
1312 Encode one-hot to binary
1314 If n is low, the o th bit in i is asserted, else none or multi‐
1316 ple bits are asserted.
1317 Parameters
1319 width (int) -- Bit width of the input
1320 i One-hot input
1322 Type Signal(width), in
1324 o Encoded binary
1326 Type Signal(max=width), out
1328 n Invalid, either none or multiple input bits are asserted
1330 Type [22mSignal(1), out
1332 class migen.genlib.coding.PriorityDecoder(width)
1334 Bases: migen.genlib.coding.Decoder
1335 class migen.genlib.coding.PriorityEncoder(width)
1337 Bases: migen.fhdl.module.Module
1338 Priority encode requests to binary
1340 If n is low, the o th bit in i is asserted and the bits below o
1342 are unasserted, else o == 0. The LSB has priority.
1343 Parameters
1345 width (int) -- Bit width of the input
1346 i Input requests
1348 Type Signal(width), in
1350 o Encoded binary
1352 Type Signal(max=width), out
1354 n Invalid, no input bits are asserted
1356 Type [22mSignal(1), out
1358 genlib.sort module
1360 class migen.genlib.sort.BitonicSort(n, m, ascending=True)
1361 Bases: migen.fhdl.module.Module
1362 Combinatorial sorting network
1364 The Bitonic sort is implemented as a combinatorial sort using
1366 comparators and multiplexers. Its asymptotic complexity (in
1367 terms of number of comparators/muxes) is O(n log(n)**2), like
1368 mergesort or shellsort.
1369 http://www.dps.uibk.ac.at/~cosenza/teaching/gpu/sort-batcher.pdf
1371 http://www.inf.fh-flensburg.de/lang/algorithmen/sortieren/bitonic/bitonicen.htm
1373 http://www.myhdl.org/doku.php/cookbook:bitonic
1375 Parameters
1377 · n (int) -- Number of inputs and output signals.
1379 · m (int) -- Bit width of inputs and outputs. Or a tuple
1381 of (m, signed).
1382 · ascending (bool) -- Sort direction. True if input is to
1384 be sorted ascending, False for descending. Defaults to
1385 ascending.
1386 i Input values, each m wide.
1388 Type list of Signals, in
1390 o Output values, sorted, each m bits wide.
1392 Type list of Signals, out
1394 genlib.fsm module
1396 class migen.genlib.fsm.FSM(reset_state=None)
1397 Bases: migen.fhdl.module.Module
1398 Finite state machine
1400 Any Python objects can be used as states, e.g. strings.
1402 Parameters
1404 reset_state -- Reset state. Defaults to the first added
1405 state.
1406 Examples.sp
1407 >>> self.active = Signal()
1408 >>> self.bitno = Signal(3)
1409 >>>
1410 >>> fsm = FSM(reset_state="START")
1411 >>> self.submodules += fsm
1412 >>>
1413 >>> fsm.act("START",
1414 ... self.active.eq(1),
1415 ... If(strobe,
1416 ... NextState("DATA")
1417 ... )
1418 ... )
1419 >>> fsm.act("DATA",
1420 ... self.active.eq(1),
1421 ... If(strobe,
1422 ... NextValue(self.bitno, self.bitno + 1),
1423 ... If(self.bitno == 7,
1424 ... NextState("END")
1425 ... )
1426 ... )
1427 ... )
1428 >>> fsm.act("END",
1429 ... self.active.eq(0),
1430 ... NextState("STOP")
1431 ... )
1432 act(state, *statements)
1434 Schedules statements to be executed in state. Statements
1435 may include:
1436 · combinatorial statements of form a.eq(b), equivalent
1438 to self.comb += a.eq(b) when the FSM is in the given
1439 state;
1440 · synchronous statements of form NextValue(a, b),
1442 equivalent to self.sync += a.eq(b) when the FSM is
1443 in the given state;
1444 · a statement of form NextState(new_state), selecting
1446 the next state;
1447 · If, Case, etc.
1449 ongoing(state)
1451 Returns a signal that has the value 1 when the FSM is in
1452 the given state, and 0 otherwise.
1453
1455 Sebastien Bourdeauducq
1456
1458 2011-2015, M-Labs Limited
14590.9 Jun 06, 2019 MIGEN(1)