--- /dev/null
+ Migen (Milkymist Generator)
+a Python toolbox for building complex digital hardware
+======================================================
+
+Background
+==========
+Even though the Milkymist system-on-chip [1] is technically successful,
+it suffers from several limitations stemming from its implementation in
+manually written Verilog HDL:
+
+(1) The "event-driven" paradigm of today's dominant hardware descriptions
+languages (Verilog and VHDL, collectively referred to as "V*HDL" in the
+rest of this document) is often too general. Today's FPGA architectures
+are optimized for the implementation of fully synchronous circuits. This
+means that the bulk of the code for an efficient FPGA design falls into
+three categories:
+ (a) Combinatorial statements
+ (b) Synchronous statements
+ (c) Initialization of registers at reset
+V*HDL do not follow this organization. This means that a lot of
+repetitive manual coding is needed, which brings sources of human errors,
+petty issues, and confusion for beginners:
+ - wire vs. reg in Verilog
+ - forgetting to initialize a register at reset
+ - deciding whether a combinatorial statement must go into a
+ process/always block or not
+ - simulation mismatches with combinatorial processes/always blocks
+ - and more...
+A little-known fact about FPGAs is that many of them have to ability to
+initialize their registers from the bitstream contents. This can be done
+in a portable and standard way using an "initial" block in Verilog, and
+by affecting a value at the signal declaration in VHDL. This renders an
+explicit reset signal unnecessary in practice in some cases, which opens
+the way for further design optimization. However, this form of
+initialization is entirely not synthesizable for ASIC targets, and it is
+not easy to switch between the two forms of reset using V*HDL.
+
+(2) V*HDL support for composite types is very limited. Signals having a
+record type in VHDL are unidirectional, which makes them clumsy to use
+e.g. in bus interfaces. There is no record type support in Verilog, which
+means that a lot of copy-and-paste has to be done when forwarding grouped
+signals.
+
+(3) V*HDL support for procedurally generated logic is extremely limited.
+The most advanced forms of procedural generation of synthesizable logic
+that V*HDL offers are CPP-style directives in Verilog, combinatorial
+functions, and generate statements. Nothing really fancy, and it shows.
+To give a few examples:
+ - Building highly flexible bus interconnect is not possible. Even
+arbitrating any given number of bus masters for commonplace protocols
+such as Wishbone cannot be done with the tools at V*HDL puts at our
+disposal. This requires manual recoding of parts of the arbiter to add or
+remove a master, which is tedious and often cause frustrating errors.
+Each occurence of the latter can easily cause one or two hours of lost
+productivity when combined with the long compilation times of moderately
+complex system-on-chip designs.
+ - Building a memory infrastructure (including bus interconnect, bridges
+and caches) that can automatically adapt itself at compile-time to any
+word size of the SDRAM is clumsy and tedious.
+ - Building register banks for control, status and interrupt management
+of cores can also largely benefit from automation.
+ - Many hardware acceleration problems can fit into the dataflow
+programming model. Manual dataflow implementation in V*HDL has, again, a
+lot of redundancy and potential for human errors. See the Milkymist
+texture mapping unit [3][4] for an example of this. The amount of detail
+to deal with manually also makes the design space exploration difficult,
+and therefore hinders the design of efficient architectures.
+ - Pre-computation of values, such as filter coefficients for DSP or
+even simply trigonometric tables, must often be done using external tools
+whose results are copy-and-pasted (in the best cases, automatically) into
+the V*HDL source.
+
+Enter Migen, a Python toolbox for building complex digital hardware. We
+could have designed a brand new programming language, but that would have
+been reinventing the wheel instead of being able to benefit from Python's
+rich features and immense library. The price to pay is a slightly
+cluttered syntax at times when writing descriptions in FHDL, but we
+believe this is totally acceptable, particularly when compared to VHDL
+;-)
+
+Migen is made up of several related components, which are described
+below.
+
+Migen FHDL
+==========
+The Fragmented Hardware Description Language (FHDL) is the lowest layer
+of Migen. It consists of a formal system to describe signals, and
+combinatorial and synchronous statements operating on them. The formal
+system itself is low level and close to the synthesizable subset of
+Verilog, and we then rely on Python algorithms to build complex
+structures by combining FHDL elements and encapsulating them in
+"fragments".
+The FHDL module also contains a back-end to produce synthesizable
+Verilog, and some basic analysis functions. It would be possible to
+develop a VHDL back-end as well, though more difficult than for Verilog -
+we are "cheating" a bit now as Verilog provides most of the FHDL
+semantics.
+
+FHDL differs from MyHDL [2] in fundamental ways. MyHDL follows the
+event-driven paradigm of traditional HDLs (see Background, #1) while FHDL
+separates the code into combinatorial statements, synchronous statements,
+and reset values. In MyHDL, the logic is described directly in the Python
+AST. The converter to Verilog or VHDL then examines the Python AST and
+recognizes a subset of Python that it translates into V*HDL statements.
+This seriously impedes the capability of MyHDL to generate logic
+procedurally. With FHDL, you manipulate a custom AST from Python, and you
+can more easily design algorithms that operate on it.
+
+FHDL is made of several elements, which are briefly explained below.
+
+BV
+--
+The bit vector (BV) object defines if a constant or signal is signed or
+unsigned, and how many bits it has. This is useful e.g. to:
+ - determine when to perform sign extension (FHDL uses the same rules as
+Verilog).
+ - determine the size of registers.
+ - determine how many bits should be used by each value in
+concatenations.
+
+Constant
+--------
+This object should be self-explanatory. All constant objects contain a BV
+object and a value. If no BV object is specified, one will be made up
+using the following rules:
+ - If the value is positive, the BV is unsigned and has the minimum
+number of bits needed to represent the constant's value in the canonical
+base-2 system.
+ - If the value is negative, the BV is signed, and has the minimum
+number of bits needed to represent the constant's value in the canonical
+two's complement, base-2 system.
+
+Signal
+------
+The signal object represents a value that is expected to change in the
+circuit. It does exactly what Verilog's "wire" and "reg" and VHDL's
+"signal" and "variable" do.
+
+The main point of the signal object is that it is identified by its
+Python ID (as returned by the id() function), and nothing else. It is the
+responsibility of the V*HDL back-end to establish an injective mapping
+between Python IDs and the V*HDL namespace. It should perform name
+mangling to ensure this. The consequence of this is that signal objects
+can safely become members of arbitrary Python classes, or be passed as
+parameters to functions or methods that generate logic involving them.
+
+The properties of a signal object are:
+ - a bit vector description
+ - a name, used as a hint for the V*HDL back-end name mangler.
+ - a boolean "variable". If true, the signal will behave like a VHDL
+variable, or a Verilog reg that uses blocking assignment. This parameter
+only has an effect when the signal's value is modified in a synchronous
+statement.
+ - the signal's reset value. It must be an integer, and defaults to 0.
+When the signal's value is modified with a synchronous statement, the
+reset value is the initialization value of the associated register.
+When the signal is assigned to in a conditional combinatorial statement
+(If or Case), the reset value is the value that the signal has when no
+condition that causes the signal to be driven is verified. This enforces
+the absence of latches in designs. If the signal is permanently driven
+using a combinatorial statement, the reset value has no effect.
+
+The sole purpose of the name property is to make the generated V*HDL code
+easier to understand and debug. From a purely functional point of view,
+it is perfectly OK to have several signals with the same name property.
+The back-end will generate a unique name for each object. If no name
+property is specified, Migen will analyze the code that created the
+signal object, and try to extract the variable or member name from there.
+It then uses the module name that created the signal, a underscore, and
+the variable name. For example, if we are in module "foo", the following
+statements will create one or several signal(s) named "foo_bar":
+ bar = Signal()
+ self.bar = Signal()
+ self.baz.bar = Signal()
+ bar = [Signal() for x in range(42)]
+
+Operators
+---------
+Operators are represented by the _Operator object, which generally should
+not be used directly. Instead, most FHDL objects overload the usual
+Python logic and arithmetic operators, which allows a much lighter syntax
+to be used. For example, the expression:
+ a * b + c
+is equivalent to:
+ _Operator('+', [_Operator('*', [a, b]), c])
+
+Slices
+------
+Likewise, slices are represented by the _Slice object, which often should
+not be used in favor of the Python slice operation [x:y].
+Implicit indices using the forms [x], [x:] and [:y] are supported.
+Beware! Slices work like Python slices, not like VHDL or Verilog slices.
+The first bound is the index of the LSB and is inclusive. The second
+bound is the index of MSB and is exclusive. In V*HDL, bounds are MSB:LSB
+and both are inclusive.
+
+Concatenations
+--------------
+Concatenations are done using the Cat object. To make the syntax lighter,
+its constructor takes a variable number of arguments, which are the
+signals to be concatenated together (you can use the Python '*' operator
+to pass a list instead).
+To be consistent with slices, the first signal is connected to the bits
+with the lowest indices in the result. This is the opposite of the way
+the '{}' construct works in Verilog.
+
+Replications
+------------
+The Replicate object represents the equivalent of {count{expression}} in
+Verilog.
+
+Assignments
+-----------
+Assignments are represented with the _Assign object. Since using it
+directly would result in a cluttered syntax, the preferred technique for
+assignments is to use the be() method provided by objects that can have a
+value assigned to them. They are signals, and their combinations with the
+slice and concatenation operators.
+As an example, the statement:
+ a[0].be(b)
+is equivalent to:
+ _Assign(_Slice(a, 0, 1), b)
+
+If statement
+------------
+The If object takes a first parameter which must be an expression
+(combination of the Constant, Signal, _Operator, _Slice, etc. objects)
+representing the condition, then a variable number of parameters
+representing the statements (_Assign, If, Case, etc. objects) to be
+executed when the condition is verified.
+
+The If object defines a Else() method, which when called defines the
+statements to be executed when the condition is not true. Those
+statements are passed as parameters to the variadic method.
+
+For convenience, there is also a Elif() method.
+
+Example:
+If(tx_count16 == 0,
+ tx_bitcount.be(tx_bitcount + 1),
+ If(tx_bitcount == 8,
+ self.tx.be(1)
+ ).Elif(tx_bitcount == 9,
+ self.tx.be(1),
+ tx_busy.be(0)
+ ).Else(
+ self.tx.be(tx_reg[0]),
+ tx_reg.be(Cat(tx_reg[1:], 0))
+ )
+)
+
+Case statement
+--------------
+The Case object constructor takes as first parameter the expression to be
+tested, then a variable number of lists describing the various cases.
+
+Each list contains an expression (typically a constant) describing the
+value to be matched, followed by the statements to be executed when there
+is a match. The head of the list can be the an instance of the Default
+object.
+
+Instances
+---------
+Instance objects represent the parametrized instantiation of a V*HDL
+module, and the connection of its ports to FHDL signals. They are useful
+in a number of cases:
+ - reusing legacy or third-party V*HDL code.
+ - using special FPGA features (DCM, ICAP, ...).
+ - implementing logic that cannot be expressed with FHDL (asynchronous
+ circuits, ...).
+ - breaking down a Migen system into multiple sub-systems, possibly
+ using different clock domains.
+
+The properties of the instance object are:
+ - the type of the instance (i.e. name of the instantiated module).
+ - a list of output ports of the instantiated module. Each element of
+ the list is a pair containing a string, which is the name of the
+ module's port, and either an existing signal (on which the port will
+ be connected to) or a BV (which will cause the creation of a new
+ signal).
+ - a list of input ports (likewise).
+ - a list of (name, value) pairs for the parameters ("generics" in VHDL)
+ of the module.
+ - the name of the clock port of the module (if any). If this is
+ specified, the port will be connected to the system clock.
+ - the name of the reset port of the module (likewise).
+ - the name of the instance (can be mangled like signal names).
+
+Memories
+--------
+Memories (on-chip SRAM) are not supported, but will be soon, using a
+mechanism similar to instances. (TODO)
+
+Fragments
+---------
+A "fragment" is a unit of logic, which is composed of:
+ - a list of combinatorial statements.
+ - a list of synchronous statements.
+ - a list of instances.
+ - a list of memories.
+ - a set of pads, which are signals intended to be connected to
+ off-chip devices.
+
+Fragments can reference arbitrary signals, including signals that are
+referenced in other fragments. Fragments can be combined using the "+"
+operator, which returns a new fragment containing the concatenation of
+each pair of lists.
+
+Fragments can be passed to the back-end for conversion to Verilog.
+
+By convention, classes that generate logic implement a method called
+"get_fragment". When called, this method builds a new fragment
+implementing the desired functionality of the class, and returns it. This
+convention allows fragments to be built automatically by combining the
+fragments from all relevant objects in the local scope, by using the
+autofragment module.
+
+Migen Core Logic
+================
+
+Migen Bus
+=========
+
+ - Wishbone [5], the general purpose bus recommended by Opencores.
+ - CSR-NG, a low-bandwidth, resource-sensitive bus designed for
+ accessing the configuration and status registers of cores from
+ software.
+ - FastMemoryLink-NG, a split-transaction bus optimized for use with a
+ high-performance, out-of-order SDRAM controller. (TODO)
+
+Migen Bank
+==========
+
+
+Migen Flow
+==========
+
+(TODO: there is no implementation of Migen Flow in the repository yet)
+
+
+References:
+[1] http://milkymist.org
+[2] http://www.myhdl.org
+[3] http://milkymist.org/thesis/thesis.pdf
+[4] http://www.xilinx.com/publications/archives/xcell/Xcell77.pdf p30-35
+[5] http://cdn.opencores.org/downloads/wbspec_b4.pdf
+
+Practical information
+=====================
+Code repository:
+https://github.com/milkymist/migen
+Experimental version of the Milkymist SoC based on Migen:
+https://github.com/milkymist/milkymist-ng
+
+Migen is designed for Python 3.2.
+
+Send questions, comments and patches to devel [AT] lists.milkymist.org
+We are also on IRC: #milkymist on the Freenode network.
+
+Migen is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free
+Software Foundation, version 3 of the License. This program is
+distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+Unless otherwise noted, Migen's source code is copyright (C) 2011
+Sebastien Bourdeauducq. Authors retain ownership of their contributions.
projects / litex.git / commitdiff