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(iterable=(), /)
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
834 >>> a = Array(range(10))
836 >>> b = Signal(max=10)
837 >>> c = Signal(max=10)
838 >>> b.eq(a[9 - c])
839 migen.fhdl.structure.C
841 alias of migen.fhdl.structure.Constant
842 class migen.fhdl.structure.Case(test, cases)
844 Bases: migen.fhdl.structure._Statement
845 Case/Switch statement
847 Parameters
849 · test (_Value, in) -- Selector value used to decide
851 which block to execute
852 · cases (dict) -- Dictionary of cases. The keys are
854 numeric constants to compare with test. The values are
855 statements to be executed the corresponding key matches
856 test. The dictionary may contain a string key "default"
857 to mark a fall-through case that is executed if no
858 other key matches.
859 Examples
861 >>> a = Signal()
863 >>> b = Signal()
864 >>> Case(a, {
865 ... 0: b.eq(1),
866 ... 1: b.eq(0),
867 ... "default": b.eq(0),
868 ... })
869 makedefault(key=None)
871 Mark a key as the default case
872 Deletes/substitutes any previously existing default case.
874 Parameters
876 key (int, Constant or None) -- Key to use as
877 default case if no other key matches. By default,
878 the largest key is the default key.
879 class migen.fhdl.structure.Cat(*args)
881 Bases: migen.fhdl.structure._Value
882 Concatenate values
884 Form a compound _Value from several smaller ones by concatena‐
886 tion. The first argument occupies the lower bits of the result.
887 The return value can be used on either side of an assignment,
888 that is, the concatenated value can be used as an argument on
889 the RHS or as a target on the LHS. If it is used on the LHS, it
890 must solely consist of Signal s, slices of Signal s, and other
891 concatenations meeting these properties. The bit length of the
892 return value is the sum of the bit lengths of the arguments:
893 len(Cat(args)) == sum(len(arg) for arg in args)
895 Parameters
897 *args (_Values or iterables of _Values, inout) -- _Value
898 s to be concatenated.
899 Returns
901 Resulting _Value obtained by concatentation.
902 Return type
904 Cat, inout
905 class migen.fhdl.structure.ClockDomain(name=None, reset_less=False)
907 Bases: object
908 Synchronous domain
910 Parameters
912 · name (str or None) -- Domain name. If None (the
914 default) the name is inferred from the variable name
915 this ClockDomain is assigned to (stripping any "cd_"
916 prefix).
917 · reset_less (bool) -- The domain does not use a reset
919 signal. Registers within this domain are still all ini‐
920 tialized to their reset state once, e.g. through Ver‐
921 ilog "initial" statements.
922 clk The clock for this domain. Can be driven or used to drive
924 other signals (preferably in combinatorial context).
925 Type Signal, inout
927 rst Reset signal for this domain. Can be driven or used to
929 drive.
930 Type Signal or None, inout
932 rename(new_name)
934 Rename the clock domain
935 Parameters
937 new_name (str) -- New name
938 class migen.fhdl.structure.ClockSignal(cd='sys')
940 Bases: migen.fhdl.structure._Value
941 Clock signal for a given clock domain
943 ClockSignal s for a given clock domain can be retrieved multiple
945 times. They all ultimately refer to the same signal.
946 Parameters
948 cd (str) -- Clock domain to obtain a clock signal for.
949 Defaults to "sys".
950 class migen.fhdl.structure.Constant(value, bits_sign=None)
952 Bases: migen.fhdl.structure._Value
953 A constant, HDL-literal integer _Value
955 Parameters
957 · value (int) --
959 · bits_sign (int or tuple or None) -- Either an integer
961 bits or a tuple (bits, signed) specifying the number of
962 bits in this Constant and whether it is signed (can
963 represent negative values). bits_sign defaults to the
964 minimum width and signedness of value.
965 class migen.fhdl.structure.DUID
967 Bases: object
968 Deterministic Unique IDentifier
970 class migen.fhdl.structure.If(cond, *t)
972 Bases: migen.fhdl.structure._Statement
973 Conditional execution of statements
975 Parameters
977 · cond (_Value(1), in) -- Condition
979 · *t (Statements) -- Statements to execute if cond is
981 asserted.
982 Examples
984 >>> a = Signal()
986 >>> b = Signal()
987 >>> c = Signal()
988 >>> d = Signal()
989 >>> If(a,
990 ... b.eq(1)
991 ... ).Elif(c,
992 ... b.eq(0)
993 ... ).Else(
994 ... b.eq(d)
995 ... )
996 Elif(cond, *t)
998 Add an else if conditional block
999 Parameters
1001 · cond (_Value(1), in) -- Condition
1003 · *t (Statements) -- Statements to execute if pre‐
1005 vious conditions fail and cond is asserted.
1006 Else(*f)
1008 Add an else conditional block
1009 Parameters
1011 *f (Statements) -- Statements to execute if all
1012 previous conditions fail.
1013 migen.fhdl.structure.Mux(sel, val1, val0)
1015 Multiplex between two values
1016 Parameters
1018 · sel (_Value(1), in) -- Selector.
1020 · val1 (_Value(N), in) --
1022 · val0 (_Value(N), in) -- Input values.
1024 Returns
1026 Output _Value. If sel is asserted, the Mux returns val1,
1027 else val0.
1028 Return type
1030 _Value(N), out
1031 class migen.fhdl.structure.Replicate(v, n)
1033 Bases: migen.fhdl.structure._Value
1034 Replicate a value
1036 An input value is replicated (repeated) several times to be used
1038 on the RHS of assignments:
1039 len(Replicate(s, n)) == len(s)*n
1041 Parameters
1043 · v (_Value, in) -- Input value to be replicated.
1045 · n (int) -- Number of replications.
1047 Returns
1049 Replicated value.
1050 Return type
1052 Replicate, out
1053 class migen.fhdl.structure.ResetSignal(cd='sys',
1055 allow_reset_less=False)
1056 Bases: migen.fhdl.structure._Value
1057 Reset signal for a given clock domain
1059 ResetSignal s for a given clock domain can be retrieved multiple
1061 times. They all ultimately refer to the same signal.
1062 Parameters
1064 · cd (str) -- Clock domain to obtain a reset signal for.
1066 Defaults to "sys".
1067 · allow_reset_less (bool) -- If the clock domain is
1069 resetless, return 0 instead of reporting an error.
1070 class migen.fhdl.structure.Signal(bits_sign=None, name=None, vari‐
1072 able=False, reset=0, reset_less=False, name_override=None, min=None,
1073 max=None, related=None, attr=None)
1074 Bases: migen.fhdl.structure._Value
1075 A _Value that can change
1077 The Signal object represents a value that is expected to change
1079 in the circuit. It does exactly what Verilog's wire and reg and
1080 VHDL's signal do.
1081 A Signal can be indexed to access a subset of its bits. Negative
1083 indices (signal[-1]) and the extended Python slicing notation
1084 (signal[start:stop:step]) are supported. The indices 0 and -1
1085 are the least and most significant bits respectively.
1086 Parameters
1088 · bits_sign (int or tuple) -- Either an integer bits or a
1090 tuple (bits, signed) specifying the number of bits in
1091 this Signal and whether it is signed (can represent
1092 negative values). signed defaults to False.
1093 · name (str or None) -- Name hint for this signal. If
1095 None (default) the name is inferred from the variable
1096 name this Signal is assigned to. Name collisions are
1097 automatically resolved by prepending names of objects
1098 that contain this Signal and by appending integer
1099 sequences.
1100 · variable (bool) -- Deprecated.
1102 · reset (int) -- Reset (synchronous) or default (combina‐
1104 torial) value. When this Signal is assigned to in syn‐
1105 chronous context and the corresponding clock domain is
1106 reset, the Signal assumes the given value. When this
1107 Signal is unassigned in combinatorial context (due to
1108 conditional assignments not being taken), the Signal
1109 assumes its reset value. Defaults to 0.
1110 · reset_less (bool) -- If True, do not generate reset
1112 logic for this Signal in synchronous statements. The
1113 reset value is only used as a combinatorial default or
1114 as the initial value. Defaults to False.
1115 · name_override (str or None) -- Do not use the inferred
1117 name but the given one.
1118 · min (int or None) --
1120 · max (int or None) -- If bits_sign is None, the signal
1122 bit width and signedness are determined by the integer
1123 range given by min (inclusive, defaults to 0) and max
1124 (exclusive, defaults to 2).
1125 · related (Signal or None) --
1127 · attr (set of synthesis attributes) --
1129 classmethod like(other, **kwargs)
1131 Create Signal based on another.
1132 Parameters
1134 · other (_Value) -- Object to base this Signal on.
1136 · migen.fhdl.bitcontainer.value_bits_sign for
1138 details. (See) --
1139 migen.fhdl.structure.wrap(value)
1141 Ensures that the passed object is a Migen value. Booleans and
1142 integers are automatically wrapped into Constant.
1143 fhdl.bitcontainer module
1145 migen.fhdl.bitcontainer.value_bits_sign(v)
1146 Bit length and signedness of a value.
1147 Parameters
1149 v (Value) --
1150 Returns
1152 Number of bits required to store v or available in v,
1153 followed by whether v has a sign bit (included in the bit
1154 count).
1155 Return type
1157 int, bool
1158 Examples
1160 >>> value_bits_sign(f.Signal(8))
1162 8, False
1163 >>> value_bits_sign(C(0xaa))
1164 8, False
1165 genlib.fifo module
1167 class migen.genlib.fifo.AsyncFIFO(width, depth)
1168 Bases: migen.fhdl.module.Module, migen.genlib.fifo._FIFOInter‐
1169 face
1170 Asynchronous FIFO (first in, first out)
1172 Read and write interfaces are accessed from different clock
1174 domains, named read and write. Use ClockDomainsRenamer to rename
1175 to other names.
1176 Data written to the input interface (din, we, writable) is
1178 buffered and can be read at the output interface (dout, re,
1179 readable). The data entry written first to the input also
1180 appears first on the output.
1181 Parameters
1183 · width (int) -- Bit width for the data.
1185 · depth (int) -- Depth of the FIFO.
1187 din Input data
1189 Type in, width
1191 writable
1193 There is space in the FIFO and we can be asserted to load
1194 new data.
1195 Type out
1197 we Write enable signal to latch din into the FIFO. Does
1199 nothing if writable is not asserted.
1200 Type in
1202 dout Output data. Only valid if readable is asserted.
1204 Type out, width
1206 readable
1208 Output data dout valid, FIFO not empty.
1209 Type out
1211 re Acknowledge dout. If asserted, the next entry will be
1213 available on the next cycle (if readable is high then).
1214 Type in
1216 class migen.genlib.fifo.AsyncFIFOBuffered(width, depth)
1218 Bases: migen.fhdl.module.Module, migen.genlib.fifo._FIFOInter‐
1219 face
1220 Improves timing when it breaks due to sluggish clock-to-output
1222 delay in e.g. Xilinx block RAMs. Increases latency by one cycle.
1223 class migen.genlib.fifo.SyncFIFO(width, depth, fwft=True)
1225 Bases: migen.fhdl.module.Module, migen.genlib.fifo._FIFOInter‐
1226 face
1227 Synchronous FIFO (first in, first out)
1229 Read and write interfaces are accessed from the same clock
1231 domain. If different clock domains are needed, use AsyncFIFO.
1232 Data written to the input interface (din, we, writable) is
1234 buffered and can be read at the output interface (dout, re,
1235 readable). The data entry written first to the input also
1236 appears first on the output.
1237 Parameters
1239 · width (int) -- Bit width for the data.
1241 · depth (int) -- Depth of the FIFO.
1243 din Input data
1245 Type in, width
1247 writable
1249 There is space in the FIFO and we can be asserted to load
1250 new data.
1251 Type out
1253 we Write enable signal to latch din into the FIFO. Does
1255 nothing if writable is not asserted.
1256 Type in
1258 dout Output data. Only valid if readable is asserted.
1260 Type out, width
1262 readable
1264 Output data dout valid, FIFO not empty.
1265 Type out
1267 re Acknowledge dout. If asserted, the next entry will be
1269 available on the next cycle (if readable is high then).
1270 Type in
1272 level Number of unread entries.
1274 Type out
1276 replace
1278 Replaces the last entry written into the FIFO with din.
1279 Does nothing if that entry has already been read (i.e.
1280 the FIFO is empty). Assert in conjunction with we.
1281 Type in
1283 class migen.genlib.fifo.SyncFIFOBuffered(width, depth)
1285 Bases: migen.fhdl.module.Module, migen.genlib.fifo._FIFOInter‐
1286 face
1287 Has an interface compatible with SyncFIFO with fwft=True, but
1289 does not use asynchronous RAM reads that are not compatible with
1290 block RAMs. Increases latency by one cycle.
1291 genlib.coding module
1293 Encoders and decoders between binary and one-hot representation
1294 class migen.genlib.coding.Decoder(width)
1296 Bases: migen.fhdl.module.Module
1297 Decode binary to one-hot
1299 If n is low, the i th bit in o is asserted, the others are not,
1301 else o == 0.
1302 Parameters
1304 width (int) -- Bit width of the output
1305 i Input binary
1307 Type Signal(max=width), in
1309 o Decoded one-hot
1311 Type Signal(width), out
1313 n Invalid, no output bits are to be asserted
1315 Type [22mSignal(1), in
1317 class migen.genlib.coding.Encoder(width)
1319 Bases: migen.fhdl.module.Module
1320 Encode one-hot to binary
1322 If n is low, the o th bit in i is asserted, else none or multi‐
1324 ple bits are asserted.
1325 Parameters
1327 width (int) -- Bit width of the input
1328 i One-hot input
1330 Type Signal(width), in
1332 o Encoded binary
1334 Type Signal(max=width), out
1336 n Invalid, either none or multiple input bits are asserted
1338 Type [22mSignal(1), out
1340 class migen.genlib.coding.PriorityDecoder(width)
1342 Bases: migen.genlib.coding.Decoder
1343 class migen.genlib.coding.PriorityEncoder(width)
1345 Bases: migen.fhdl.module.Module
1346 Priority encode requests to binary
1348 If n is low, the o th bit in i is asserted and the bits below o
1350 are unasserted, else o == 0. The LSB has priority.
1351 Parameters
1353 width (int) -- Bit width of the input
1354 i Input requests
1356 Type Signal(width), in
1358 o Encoded binary
1360 Type Signal(max=width), out
1362 n Invalid, no input bits are asserted
1364 Type [22mSignal(1), out
1366 genlib.sort module
1368 class migen.genlib.sort.BitonicSort(n, m, ascending=True)
1369 Bases: migen.fhdl.module.Module
1370 Combinatorial sorting network
1372 The Bitonic sort is implemented as a combinatorial sort using
1374 comparators and multiplexers. Its asymptotic complexity (in
1375 terms of number of comparators/muxes) is O(n log(n)**2), like
1376 mergesort or shellsort.
1377 http://www.dps.uibk.ac.at/~cosenza/teaching/gpu/sort-batcher.pdf
1379 http://www.inf.fh-flensburg.de/lang/algorithmen/sortieren/bitonic/bitonicen.htm
1381 http://www.myhdl.org/doku.php/cookbook:bitonic
1383 Parameters
1385 · n (int) -- Number of inputs and output signals.
1387 · m (int) -- Bit width of inputs and outputs. Or a tuple
1389 of (m, signed).
1390 · ascending (bool) -- Sort direction. True if input is to
1392 be sorted ascending, False for descending. Defaults to
1393 ascending.
1394 i Input values, each m wide.
1396 Type list of Signals, in
1398 o Output values, sorted, each m bits wide.
1400 Type list of Signals, out
1402 genlib.fsm module
1404 class migen.genlib.fsm.FSM(reset_state=None)
1405 Bases: migen.fhdl.module.Module
1406 Finite state machine
1408 Any Python objects can be used as states, e.g. strings.
1410 Parameters
1412 reset_state -- Reset state. Defaults to the first added
1413 state.
1414 Examples
1416 >>> self.active = Signal()
1418 >>> self.bitno = Signal(3)
1419 >>>
1420 >>> fsm = FSM(reset_state="START")
1421 >>> self.submodules += fsm
1422 >>>
1423 >>> fsm.act("START",
1424 ... self.active.eq(1),
1425 ... If(strobe,
1426 ... NextState("DATA")
1427 ... )
1428 ... )
1429 >>> fsm.act("DATA",
1430 ... self.active.eq(1),
1431 ... If(strobe,
1432 ... NextValue(self.bitno, self.bitno + 1),
1433 ... If(self.bitno == 7,
1434 ... NextState("END")
1435 ... )
1436 ... )
1437 ... )
1438 >>> fsm.act("END",
1439 ... self.active.eq(0),
1440 ... NextState("STOP")
1441 ... )
1442 act(state, *statements)
1444 Schedules statements to be executed in state. Statements
1445 may include:
1446 · combinatorial statements of form a.eq(b), equivalent
1448 to self.comb += a.eq(b) when the FSM is in the given
1449 state;
1450 · synchronous statements of form NextValue(a, b),
1452 equivalent to self.sync += a.eq(b) when the FSM is
1453 in the given state;
1454 · a statement of form NextState(new_state), selecting
1456 the next state;
1457 · If, Case, etc.
1459 ongoing(state)
1461 Returns a signal that has the value 1 when the FSM is in
1462 the given state, and 0 otherwise.
1463
1465 Sebastien Bourdeauducq
1466
1468 2011-2021, M-Labs Limited
14690.9 Mar 07, 2021 MIGEN(1)