Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

doc: switch to sphinx

  • Loading branch information...
commit 90546fd8117f3270afd2202e2662528df71c8a2b 1 parent 57a87b3
Sébastien Bourdeauducq authored March 09, 2012
1  .gitignore
@@ -3,3 +3,4 @@ __pycache__
3 3
 vpi/*.o
4 4
 vpi/migensim.vpi
5 5
 examples/*.vcd
  6
+doc/_build
130  doc/Makefile
... ...
@@ -0,0 +1,130 @@
  1
+# Makefile for Sphinx documentation
  2
+#
  3
+
  4
+# You can set these variables from the command line.
  5
+SPHINXOPTS    =
  6
+SPHINXBUILD   = sphinx-build
  7
+PAPER         =
  8
+BUILDDIR      = _build
  9
+
  10
+# Internal variables.
  11
+PAPEROPT_a4     = -D latex_paper_size=a4
  12
+PAPEROPT_letter = -D latex_paper_size=letter
  13
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
  14
+
  15
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
  16
+
  17
+help:
  18
+	@echo "Please use \`make <target>' where <target> is one of"
  19
+	@echo "  html       to make standalone HTML files"
  20
+	@echo "  dirhtml    to make HTML files named index.html in directories"
  21
+	@echo "  singlehtml to make a single large HTML file"
  22
+	@echo "  pickle     to make pickle files"
  23
+	@echo "  json       to make JSON files"
  24
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
  25
+	@echo "  qthelp     to make HTML files and a qthelp project"
  26
+	@echo "  devhelp    to make HTML files and a Devhelp project"
  27
+	@echo "  epub       to make an epub"
  28
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
  29
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
  30
+	@echo "  text       to make text files"
  31
+	@echo "  man        to make manual pages"
  32
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
  33
+	@echo "  linkcheck  to check all external links for integrity"
  34
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
  35
+
  36
+clean:
  37
+	-rm -rf $(BUILDDIR)/*
  38
+
  39
+html:
  40
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
  41
+	@echo
  42
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
  43
+
  44
+dirhtml:
  45
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
  46
+	@echo
  47
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
  48
+
  49
+singlehtml:
  50
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
  51
+	@echo
  52
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
  53
+
  54
+pickle:
  55
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
  56
+	@echo
  57
+	@echo "Build finished; now you can process the pickle files."
  58
+
  59
+json:
  60
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
  61
+	@echo
  62
+	@echo "Build finished; now you can process the JSON files."
  63
+
  64
+htmlhelp:
  65
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
  66
+	@echo
  67
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
  68
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
  69
+
  70
+qthelp:
  71
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
  72
+	@echo
  73
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
  74
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
  75
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Migen.qhcp"
  76
+	@echo "To view the help file:"
  77
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Migen.qhc"
  78
+
  79
+devhelp:
  80
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
  81
+	@echo
  82
+	@echo "Build finished."
  83
+	@echo "To view the help file:"
  84
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/Migen"
  85
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Migen"
  86
+	@echo "# devhelp"
  87
+
  88
+epub:
  89
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
  90
+	@echo
  91
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
  92
+
  93
+latex:
  94
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
  95
+	@echo
  96
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
  97
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
  98
+	      "(use \`make latexpdf' here to do that automatically)."
  99
+
  100
+latexpdf:
  101
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
  102
+	@echo "Running LaTeX files through pdflatex..."
  103
+	make -C $(BUILDDIR)/latex all-pdf
  104
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
  105
+
  106
+text:
  107
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
  108
+	@echo
  109
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
  110
+
  111
+man:
  112
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
  113
+	@echo
  114
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
  115
+
  116
+changes:
  117
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
  118
+	@echo
  119
+	@echo "The overview file is in $(BUILDDIR)/changes."
  120
+
  121
+linkcheck:
  122
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
  123
+	@echo
  124
+	@echo "Link check complete; look for any errors in the above output " \
  125
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
  126
+
  127
+doctest:
  128
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
  129
+	@echo "Testing of doctests in the sources finished, look at the " \
  130
+	      "results in $(BUILDDIR)/doctest/output.txt."
0  doc/_build/.keep_me
No changes.
0  doc/_static/.keep_me
No changes.
0  doc/_templates/.keep_me
No changes.
170  doc/asmi.txt
... ...
@@ -1,170 +0,0 @@
1  
- Advanced System Memory Infrastructure (ASMI)
2  
-==============================================
3  
-
4  
-Rationale
5  
-=========
6  
-The lagging of the DRAM semiconductor processes behind the logic
7  
-processes has led the industry into a subtle way of ever increasing
8  
-memory performance.
9  
-
10  
-Modern devices feature a DRAM core running at a fraction of the logic
11  
-frequency, whose wide data bus is serialized and deserialized to and
12  
-from the faster clock domain. Further, the presence of more banks
13  
-increases page hit rate and provides opportunities for parallel
14  
-execution of commands to different banks.
15  
-
16  
-A first-generation SDR-133 SDRAM chip runs both DRAM, I/O and logic at
17  
-133MHz and features 4 banks. A 16-bit chip has a 16-bit DRAM core.
18  
-
19  
-A newer DDR3-1066 chip still runs the DRAM core at 133MHz, but the logic
20  
-at 533MHz (4 times the DRAM frequency) and the I/O at 1066Mt/s (8 times
21  
-the DRAM frequency). A 16-bit chip has a 128-bit internal DRAM core.
22  
-Such a device features 8 banks. Note that the serialization also
23  
-introduces multiplied delays (e.g. CAS latency) when measured in number
24  
-of cycles of the logic clock.
25  
-
26  
-To take full advantage of these new architectures, the memory controller
27  
-should be able to peek ahead at the incoming requests and service
28  
-several of them in parallel, while respecting the various timing
29  
-specifications of each DRAM bank and avoiding conflicts for the shared
30  
-data lines. Going further in this direction, a controller able to
31  
-complete transfers out of order can provide even more performance by:
32  
-(1) grouping requests by DRAM row, in order to minimize time spent on
33  
-    precharging and activating banks.
34  
-(2) grouping requests by direction (read or write) in order to minimize
35  
-    delays introduced by bus turnaround and write recovery times.
36  
-(3) being able to complete a request that hits a page earlier than a
37  
-    concurrent one which requires the cycling of another bank.
38  
-
39  
-The first two techniques are explained with more details in [1].
40  
-
41  
-To enable the efficient implementation of these mechanisms, a new
42  
-communication protocol with the memory controller must be devised. Migen
43  
-and Milkymist SoC (-NG) implement their own bus, called ASMIbus, based
44  
-on the split-transaction principle.
45  
-
46  
-Topology
47  
-========
48  
-The ASMI consists of a memory controller (e.g. ASMIcon) containing a hub
49  
-that connects the multiple masters, handles transaction tags, and
50  
-presents a view of the pending requests to the rest of the memory
51  
-controller.
52  
-
53  
-Links between the masters and the hub are using the same ASMIbus protocol
54  
-described below.
55  
-
56  
-It is suggested that memory controllers use an interface to a PHY
57  
-compatible with DFI [2]. The DFI clock can be the same as the ASMIbus
58  
-clock, with optional serialization and deserialization happening across
59  
-the PHY, as specified in the DFI standard.
60  
-
61  
-+-------+    +---+
62  
-|Master1|<==>|   |                             +----------+
63  
-+-------+    |   +-------+    +-------+        | Off-chip |
64  
-             |Hub|ASMIcon|<-->|DDR PHY|<<====>>|  SDRAM   |
65  
-+-------+    |   +-------+    +-------+        |device(s) |
66  
-|Master2|<==>|   |                             +----------+
67  
-+-------+    +---+
68  
-
69  
-<====> ASMIbus links
70  
-<----> DFI (or similar) links
71  
-<<==>> PCB traces to external SDRAM chips
72  
-
73  
-Signals
74  
-=======
75  
-The ASMIbus consists of two parts: the control signals, and the data
76  
-signals.
77  
-
78  
-The control signals are used to issue requests.
79  
- * Master->Hub:
80  
-     - ADR communicates the memory address to be accessed. The unit is
81  
-       the word width of the particular implementation of ASMIbus.
82  
-     - WE is the write enable signal.
83  
-     - STB qualifies the transaction request, and should be asserted
84  
-       until ACK goes high.
85  
- * Hub->Master
86  
-     - TAG_ISSUE is an integer representing the transaction ("tag")
87  
-       attributed by the hub. The width of this signal is determined by
88  
-       the maximum number of in-flight transactions that the hub port
89  
-       can handle.
90  
-     - ACK is asserted when TAG_ISSUE is valid and the transaction has
91  
-       been registered by the hub. A hub may assert ACK even when STB is
92  
-       low, which means it is ready to accept any new transaction and
93  
-       will do as soon as STB goes high.
94  
-
95  
-The data signals are used to complete requests.
96  
- * Hub->Master
97  
-     - TAG_CALL is used to identify the transaction for which the data
98  
-       is "called". It takes the tag value that has been previously
99  
-       attributed by the hub to that transaction during the issue
100  
-       phase.
101  
-     - CALL qualifies TAG_CALL.
102  
-     - DATA_R returns data from the DRAM in the case of a read
103  
-       transaction. It is valid for one cycle after CALL has been
104  
-       asserted and TAG_CALL has identified the transaction.
105  
-       The value of this signal is undefined for the cycle after a write
106  
-       transaction data have been called.
107  
- * Master->Hub
108  
-     - DATA_W must supply data to the controller from the appropriate
109  
-       write transaction, on the cycle after they have been called using
110  
-       CALL and TAG_CALL.
111  
-     - DATA_WM are the byte-granular write data masks. They are used in
112  
-       combination with DATA_W to identify the bytes that should be
113  
-       modified in the memory. The DATA_WM bit should be high for its
114  
-       corresponding DATA_W byte to be written.
115  
-
116  
-In order to avoid duplicating the tag matching and tracking logic, the
117  
-master->hub data signals must be driven low when they are not in use, so
118  
-that they can be simply ORed together inside the memory controller. This
119  
-way, only masters have to track (their own) transactions for arbitrating
120  
-the data lines.
121  
-
122  
-Tags represent in-flight transactions. The hub can reissue a tag as soon
123  
-as the cycle when it appears on TAG_CALL.
124  
-
125  
-SDRAM burst length and clock ratios
126  
-===================================
127  
-A system using ASMI must set the SDRAM burst length B, the ASMIbus word
128  
-width W and the ratio between the ASMIbus clock frequency Fa and the
129  
-SDRAM I/O frequency Fi so that all data transfers last for exactly one
130  
-ASMIbus cycle.
131  
-
132  
-More explicitly, these relations must be verified:
133  
-B = Fi/Fa
134  
-W = B*[number of SDRAM I/O pins]
135  
-
136  
-For DDR memories, the I/O frequency is twice the logic frequency.
137  
-
138  
-Example transactions
139  
-====================
140  
-
141  
-Basic transaction:
142  
-CTL  <R A1>------------------
143  
-ISSUE< T1 >------------------
144  
-CALL ------------< T1 >------
145  
-DAT_R------------------<D A1>
146  
-DAT_W------------------------
147  
-
148  
-Two simple transactions:
149  
-CTL  <R A1>------<R A2>------------------------
150  
-ISSUE< T1 >------< T2 >------------------------
151  
-CALL ------------------< T1 >------< T2 >------
152  
-DAT_R------------------------<D A1>------<D A2>
153  
-DAT_W------------------------------------------
154  
-
155  
-Interleaved transactions:
156  
-CTL  <R A1>------<R A2><W A3><R A4><W A5>------------------------
157  
-ISSUE< T1 >------< T1 >< T2 >< T1 >< T1 >------------------------
158  
-CALL ------------< T1 >------< T1 >< T1 >------< T1 >< T2 >------
159  
-DAT_R------------------<D A1>------<D A2><D A4>------------------
160  
-DAT_W------------------------------------------------<D A5><D A3>
161  
-
162  
-<R Ax> Read address x
163  
-<W Ax> Write address x
164  
-< Tn > Tag n
165  
-<D Ax> Data to/from address x
166  
-
167  
-
168  
-[1] http://www.xilinx.com/txpatches/pub/documentation/misc/
169  
-    improving%20ddr%20sdram%20efficiency.pdf
170  
-[2] http://www.ddr-phy.org/
216  doc/conf.py
... ...
@@ -0,0 +1,216 @@
  1
+# -*- coding: utf-8 -*-
  2
+#
  3
+# Migen documentation build configuration file, created by
  4
+# sphinx-quickstart on Fri Mar  9 14:11:54 2012.
  5
+#
  6
+# This file is execfile()d with the current directory set to its containing dir.
  7
+#
  8
+# Note that not all possible configuration values are present in this
  9
+# autogenerated file.
  10
+#
  11
+# All configuration values have a default; values that are commented out
  12
+# serve to show the default.
  13
+
  14
+import sys, os
  15
+
  16
+# If extensions (or modules to document with autodoc) are in another directory,
  17
+# add these directories to sys.path here. If the directory is relative to the
  18
+# documentation root, use os.path.abspath to make it absolute, like shown here.
  19
+#sys.path.insert(0, os.path.abspath('.'))
  20
+
  21
+# -- General configuration -----------------------------------------------------
  22
+
  23
+# If your documentation needs a minimal Sphinx version, state it here.
  24
+#needs_sphinx = '1.0'
  25
+
  26
+# Add any Sphinx extension module names here, as strings. They can be extensions
  27
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
  28
+extensions = ['sphinx.ext.pngmath']
  29
+
  30
+# Add any paths that contain templates here, relative to this directory.
  31
+templates_path = ['_templates']
  32
+
  33
+# The suffix of source filenames.
  34
+source_suffix = '.rst'
  35
+
  36
+# The encoding of source files.
  37
+#source_encoding = 'utf-8-sig'
  38
+
  39
+# The master toctree document.
  40
+master_doc = 'index'
  41
+
  42
+# General information about the project.
  43
+project = u'Migen'
  44
+copyright = u'2012, Sebastien Bourdeauducq'
  45
+
  46
+# The version info for the project you're documenting, acts as replacement for
  47
+# |version| and |release|, also used in various other places throughout the
  48
+# built documents.
  49
+#
  50
+# The short X.Y version.
  51
+version = 'X'
  52
+# The full version, including alpha/beta/rc tags.
  53
+release = 'X'
  54
+
  55
+# The language for content autogenerated by Sphinx. Refer to documentation
  56
+# for a list of supported languages.
  57
+#language = None
  58
+
  59
+# There are two options for replacing |today|: either, you set today to some
  60
+# non-false value, then it is used:
  61
+#today = ''
  62
+# Else, today_fmt is used as the format for a strftime call.
  63
+#today_fmt = '%B %d, %Y'
  64
+
  65
+# List of patterns, relative to source directory, that match files and
  66
+# directories to ignore when looking for source files.
  67
+exclude_patterns = ['_build']
  68
+
  69
+# The reST default role (used for this markup: `text`) to use for all documents.
  70
+#default_role = None
  71
+
  72
+# If true, '()' will be appended to :func: etc. cross-reference text.
  73
+#add_function_parentheses = True
  74
+
  75
+# If true, the current module name will be prepended to all description
  76
+# unit titles (such as .. function::).
  77
+#add_module_names = True
  78
+
  79
+# If true, sectionauthor and moduleauthor directives will be shown in the
  80
+# output. They are ignored by default.
  81
+#show_authors = False
  82
+
  83
+# The name of the Pygments (syntax highlighting) style to use.
  84
+pygments_style = 'sphinx'
  85
+
  86
+# A list of ignored prefixes for module index sorting.
  87
+#modindex_common_prefix = []
  88
+
  89
+
  90
+# -- Options for HTML output ---------------------------------------------------
  91
+
  92
+# The theme to use for HTML and HTML Help pages.  See the documentation for
  93
+# a list of builtin themes.
  94
+html_theme = 'default'
  95
+
  96
+# Theme options are theme-specific and customize the look and feel of a theme
  97
+# further.  For a list of options available for each theme, see the
  98
+# documentation.
  99
+#html_theme_options = {}
  100
+
  101
+# Add any paths that contain custom themes here, relative to this directory.
  102
+#html_theme_path = []
  103
+
  104
+# The name for this set of Sphinx documents.  If None, it defaults to
  105
+# "<project> v<release> documentation".
  106
+#html_title = None
  107
+
  108
+# A shorter title for the navigation bar.  Default is the same as html_title.
  109
+#html_short_title = None
  110
+
  111
+# The name of an image file (relative to this directory) to place at the top
  112
+# of the sidebar.
  113
+#html_logo = None
  114
+
  115
+# The name of an image file (within the static path) to use as favicon of the
  116
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
  117
+# pixels large.
  118
+#html_favicon = None
  119
+
  120
+# Add any paths that contain custom static files (such as style sheets) here,
  121
+# relative to this directory. They are copied after the builtin static files,
  122
+# so a file named "default.css" will overwrite the builtin "default.css".
  123
+html_static_path = ['_static']
  124
+
  125
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
  126
+# using the given strftime format.
  127
+#html_last_updated_fmt = '%b %d, %Y'
  128
+
  129
+# If true, SmartyPants will be used to convert quotes and dashes to
  130
+# typographically correct entities.
  131
+#html_use_smartypants = True
  132
+
  133
+# Custom sidebar templates, maps document names to template names.
  134
+#html_sidebars = {}
  135
+
  136
+# Additional templates that should be rendered to pages, maps page names to
  137
+# template names.
  138
+#html_additional_pages = {}
  139
+
  140
+# If false, no module index is generated.
  141
+#html_domain_indices = True
  142
+
  143
+# If false, no index is generated.
  144
+#html_use_index = True
  145
+
  146
+# If true, the index is split into individual pages for each letter.
  147
+#html_split_index = False
  148
+
  149
+# If true, links to the reST sources are added to the pages.
  150
+#html_show_sourcelink = True
  151
+
  152
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
  153
+#html_show_sphinx = True
  154
+
  155
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
  156
+#html_show_copyright = True
  157
+
  158
+# If true, an OpenSearch description file will be output, and all pages will
  159
+# contain a <link> tag referring to it.  The value of this option must be the
  160
+# base URL from which the finished HTML is served.
  161
+#html_use_opensearch = ''
  162
+
  163
+# This is the file name suffix for HTML files (e.g. ".xhtml").
  164
+#html_file_suffix = None
  165
+
  166
+# Output file base name for HTML help builder.
  167
+htmlhelp_basename = 'Migendoc'
  168
+
  169
+
  170
+# -- Options for LaTeX output --------------------------------------------------
  171
+
  172
+# The paper size ('letter' or 'a4').
  173
+#latex_paper_size = 'letter'
  174
+
  175
+# The font size ('10pt', '11pt' or '12pt').
  176
+#latex_font_size = '10pt'
  177
+
  178
+# Grouping the document tree into LaTeX files. List of tuples
  179
+# (source start file, target name, title, author, documentclass [howto/manual]).
  180
+latex_documents = [
  181
+  ('index', 'Migen.tex', u'Migen manual',
  182
+   u'Sebastien Bourdeauducq', 'manual'),
  183
+]
  184
+
  185
+# The name of an image file (relative to this directory) to place at the top of
  186
+# the title page.
  187
+#latex_logo = None
  188
+
  189
+# For "manual" documents, if this is true, then toplevel headings are parts,
  190
+# not chapters.
  191
+#latex_use_parts = False
  192
+
  193
+# If true, show page references after internal links.
  194
+#latex_show_pagerefs = False
  195
+
  196
+# If true, show URL addresses after external links.
  197
+#latex_show_urls = False
  198
+
  199
+# Additional stuff for the LaTeX preamble.
  200
+latex_preamble = '\setcounter{tocdepth}{3}'
  201
+
  202
+# Documents to append as an appendix to all manuals.
  203
+#latex_appendices = []
  204
+
  205
+# If false, no module index is generated.
  206
+#latex_domain_indices = True
  207
+
  208
+
  209
+# -- Options for manual page output --------------------------------------------
  210
+
  211
+# One entry per manual page. List of tuples
  212
+# (source start file, name, description, authors, manual section).
  213
+man_pages = [
  214
+    ('index', 'migen', u'Migen manual',
  215
+     [u'Sebastien Bourdeauducq'], 1)
  216
+]
428  doc/index.rst
Source Rendered
... ...
@@ -0,0 +1,428 @@
  1
+Migen manual
  2
+############
  3
+
  4
+.. _introduction:
  5
+
  6
+Introduction
  7
+############
  8
+Migen is a Python-based tool that aims at automating further the VLSI design process.
  9
+
  10
+Migen makes it possible to apply modern software concepts such as object-oriented programming and metaprogramming to design hardware. This results in more elegant and easily maintained designs and reduces the incidence of human errors.
  11
+
  12
+Even though the Milkymist system-on-chip [mm]_ is technically successful, it suffers from several limitations stemming from its implementation in manually written Verilog HDL:
  13
+
  14
+.. [mm] http://www.milkymist.org
  15
+
  16
+#. 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:
  17
+
  18
+   #. Combinatorial statements
  19
+   #. Synchronous statements
  20
+   #. Initialization of registers at reset
  21
+
  22
+   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:
  23
+   
  24
+   #. wire vs. reg in Verilog
  25
+   #. forgetting to initialize a register at reset
  26
+   #. deciding whether a combinatorial statement must go into a process/always block or not
  27
+   #. simulation mismatches with combinatorial processes/always blocks
  28
+   #. and more...
  29
+   
  30
+   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.
  31
+
  32
+#. 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.
  33
+
  34
+#. 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:
  35
+
  36
+   #. Building highly flexible bus interconnect is not possible. Even arbitrating any given number of bus masters for commonplace protocols such as Wishbone is difficult with the tools at V*HDL puts at our disposal.
  37
+   #. 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.
  38
+   #. Building register banks for control, status and interrupt management of cores can also largely benefit from automation.
  39
+   #. 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 [mthesis]_ [mxcell]_ 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.
  40
+   #. 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.
  41
+
  42
+.. [mthesis] http://milkymist.org/thesis/thesis.pdf
  43
+.. [mxcell] http://www.xilinx.com/publications/archives/xcell/Xcell77.pdf p30-35
  44
+   
  45
+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 ;-)
  46
+
  47
+Migen is made up of several related components, which are described in this manual.
  48
+
  49
+The FHDL layer
  50
+##############
  51
+
  52
+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".
  53
+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.
  54
+
  55
+FHDL differs from MyHDL [myhdl]_ in fundamental ways. MyHDL follows the event-driven paradigm of traditional HDLs (see :ref:`introduction`) 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.
  56
+
  57
+.. [myhdl] http://www.myhdl.org
  58
+
  59
+FHDL is made of several elements, which are briefly explained below.
  60
+
  61
+Expressions
  62
+***********
  63
+
  64
+Bit vector (BV)
  65
+===============
  66
+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:
  67
+
  68
+* determine when to perform sign extension (FHDL uses the same rules as Verilog).
  69
+* determine the size of registers.
  70
+* determine how many bits should be used by each value in concatenations.
  71
+
  72
+Constant
  73
+========
  74
+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:
  75
+
  76
+* 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.
  77
+* 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.
  78
+
  79
+Signal
  80
+======
  81
+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.
  82
+
  83
+The main point of the signal object is that it is identified by its Python ID (as returned by the :py:func:`id` function), and nothing else. It is the responsibility of the V*HDL back-end to establish an injective mapping between Python IDs and the V*HDL namespace. It should perform name mangling to ensure this. The consequence of this is that signal objects can safely become members of arbitrary Python classes, or be passed as parameters to functions or methods that generate logic involving them.
  84
+
  85
+The properties of a signal object are:
  86
+
  87
+* a bit vector description
  88
+* a name, used as a hint for the V*HDL back-end name mangler.
  89
+* 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.
  90
+* 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.
  91
+  
  92
+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. For example, the following statements will create one or several signal named "bar": ::
  93
+
  94
+  bar = Signal()
  95
+  self.bar = Signal()
  96
+  self.baz.bar = Signal()
  97
+  bar = [Signal() for x in range(42)]
  98
+
  99
+In case of conflicts, Migen tries first to resolve the situation by prefixing the identifiers with names from the class and module hierarchy that created them. If the conflict persists (which can be the case if two signal objects are created with the same name in the same context), it will ultimately add number suffixes.
  100
+
  101
+Operators
  102
+=========
  103
+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: ::
  104
+
  105
+  a * b + c
  106
+
  107
+is equivalent to::
  108
+
  109
+  _Operator("+", [_Operator("*", [a, b]), c])
  110
+
  111
+Slices
  112
+======
  113
+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.
  114
+
  115
+Concatenations
  116
+==============
  117
+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).
  118
+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.
  119
+
  120
+Replications
  121
+============
  122
+The Replicate object represents the equivalent of {count{expression}} in Verilog.
  123
+
  124
+Statements
  125
+**********
  126
+
  127
+Assignment
  128
+==========
  129
+Assignments are represented with the _Assign object. Since using it directly would result in a cluttered syntax, the preferred technique for assignments is to use the eq() method provided by objects that can have a value assigned to them. They are signals, and their combinations with the slice and concatenation operators.
  130
+As an example, the statement: ::
  131
+
  132
+  a[0].eq(b)
  133
+
  134
+is equivalent to: ::
  135
+
  136
+  _Assign(_Slice(a, 0, 1), b)
  137
+
  138
+If
  139
+==
  140
+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.
  141
+
  142
+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.
  143
+
  144
+For convenience, there is also a Elif() method.
  145
+
  146
+Example: ::
  147
+
  148
+  If(tx_count16 == 0,
  149
+      tx_bitcount.eq(tx_bitcount + 1),
  150
+      If(tx_bitcount == 8,
  151
+          self.tx.eq(1)
  152
+      ).Elif(tx_bitcount == 9,
  153
+          self.tx.eq(1),
  154
+          tx_busy.eq(0)
  155
+      ).Else(
  156
+          self.tx.eq(tx_reg[0]),
  157
+          tx_reg.eq(Cat(tx_reg[1:], 0))
  158
+      )
  159
+  )
  160
+
  161
+Case
  162
+====
  163
+The Case object constructor takes as first parameter the expression to be tested, then a variable number of lists describing the various cases.
  164
+
  165
+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.
  166
+
  167
+Special elements
  168
+****************
  169
+
  170
+Instances
  171
+=========
  172
+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:
  173
+
  174
+* reusing legacy or third-party V*HDL code.
  175
+* using special FPGA features (DCM, ICAP, ...).
  176
+* implementing logic that cannot be expressed with FHDL (asynchronous circuits, ...).
  177
+* breaking down a Migen system into multiple sub-systems, possibly using different clock domains.
  178
+
  179
+The properties of the instance object are:
  180
+
  181
+* the type of the instance (i.e. name of the instantiated module).
  182
+* 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).
  183
+* a list of input ports (likewise).
  184
+* a list of (name, value) pairs for the parameters ("generics" in VHDL) of the module.
  185
+* the name of the clock port of the module (if any). If this is specified, the port will be connected to the system clock.
  186
+* the name of the reset port of the module (likewise).
  187
+* the name of the instance (can be mangled like signal names).
  188
+
  189
+Memories
  190
+========
  191
+Memories (on-chip SRAM) are supported using a mechanism similar to instances.
  192
+
  193
+A memory object has the following parameters:
  194
+
  195
+* the width, which is the number of bits in each word.
  196
+* the depth, which represents the number of words in the memory.
  197
+* an optional list of integers used to initialize the memory.
  198
+* a list of port descriptions.
  199
+
  200
+Each port description contains:
  201
+
  202
+* the address signal (mandatory).
  203
+* the data read signal (mandatory).
  204
+* the write enable signal (optional). If the port is using masked writes, the width of the write enable signal should match the number of sub-words.
  205
+* the data write signal (iff there is a write enable signal).
  206
+* whether reads are synchronous (default) or asynchronous.
  207
+* the read enable port (optional, ignored for asynchronous ports).
  208
+* the write granularity (default 0), which defines the number of bits in each sub-word. If it is set to 0, the port is using whole-word writes only and the width of the write enable signal must be 1. This parameter is ignored if there is no write enable signal.
  209
+* the mode of the port (default ``WRITE_FIRST``, ignored for asynchronous ports). It can be:
  210
+
  211
+  * ``READ_FIRST``: during a write, the previous value is read.
  212
+  * ``WRITE_FIRST``: the written value is returned.
  213
+  * ``NO_CHANGE``: the data read signal keeps its previous value on a write.
  214
+
  215
+Migen generates behavioural V*HDL code that should be compatible with all simulators and, if the number of ports is <= 2, most FPGA synthesizers. If a specific code is needed, the memory generator function can be overriden using the memory_handler parameter of the conversion function.
  216
+
  217
+Fragments
  218
+*********
  219
+A "fragment" is a unit of logic, which is composed of:
  220
+
  221
+* a list of combinatorial statements.
  222
+* a list of synchronous statements.
  223
+* a list of instances.
  224
+* a list of memories.
  225
+* a set of pads, which are signals intended to be connected to off-chip devices.
  226
+* a list of simulation functions (see :ref:`simulating`).
  227
+
  228
+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.
  229
+
  230
+Fragments can be passed to the back-end for conversion to Verilog.
  231
+
  232
+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.
  233
+
  234
+Conversion for synthesis
  235
+************************
  236
+
  237
+Any FHDL fragment (except, of course, its simulation functions) can be converted into synthesizable Verilog HDL. This is accomplished by using the ``convert`` function in the ``verilog`` module.
  238
+
  239
+Migen does not provide support for any specific synthesis tools or ASIC/FPGA technologies. Users must run themselves the generated code through the appropriate tool flow for hardware implementation.
  240
+
  241
+Bus support
  242
+###########
  243
+Migen Bus contains classes providing a common structure for master and slave interfaces of the following buses:
  244
+
  245
+* Wishbone [wishbone]_, the general purpose bus recommended by Opencores.
  246
+* CSR-2 (see :ref:`csr2`), a low-bandwidth, resource-sensitive bus designed for accessing the configuration and status registers of cores from software.
  247
+* ASMIbus (see :ref:`asmi`), a split-transaction bus optimized for use with a high-performance, out-of-order SDRAM controller.
  248
+* DFI [dfi]_ (partial), a standard interface protocol between memory controller logic and PHY interfaces.
  249
+
  250
+.. [wishbone] http://cdn.opencores.org/downloads/wbspec_b4.pdf
  251
+.. [dfi] http://www.ddr-phy.org/
  252
+
  253
+It also provides interconnect components for these buses, such as arbiters and address decoders. The strength of the Migen procedurally generated logic can be illustrated by the following example: ::
  254
+
  255
+  wbcon = wishbone.InterconnectShared(
  256
+      [cpu.ibus, cpu.dbus, ethernet.dma, audio.dma],
  257
+      [(0, norflash.bus), (1, wishbone2asmi.wishbone),
  258
+      (3, wishbone2csr.wishbone)])
  259
+
  260
+In this example, the interconnect component generates a 4-way round-robin arbiter, multiplexes the master bus signals into a shared bus, determines that the address decoding must occur on 2 bits, and connects all slave interfaces to the shared bus, inserting the address decoder logic in the bus cycle qualification signals and multiplexing the data return path. It can recognize the signals in each core's bus interface thanks to the common structure mandated by Migen Bus. All this happens automatically, using only that much user code. The resulting interconnect logic can be retrieved using ``wbcon.get_fragment()``, and combined with the fragments from the rest of the system.
  261
+
  262
+
  263
+Configuration and Status Registers
  264
+**********************************
  265
+
  266
+.. _csr2:
  267
+
  268
+CSR-2 bus
  269
+=========
  270
+The CSR-2 bus, is a low-bandwidth, resource-sensitive bus designed for accessing the configuration and status registers of cores from software.
  271
+
  272
+It is the successor of the CSR bus used in Milkymist SoC 1.x, with two modifications:
  273
+
  274
+* Up to 32 slave devices (instead of 16)
  275
+* Data words are 8 bits (instead of 32)
  276
+
  277
+Generating register banks
  278
+=========================
  279
+Migen Bank is a system comparable to wishbone-gen [wbgen]_, which automates the creation of configuration and status register banks and interrupt/event managers implemented in cores.
  280
+
  281
+.. [wbgen] http://www.ohwr.org/projects/wishbone-gen
  282
+
  283
+Bank takes a description made up of a list of registers and generates logic implementing it with a slave interface compatible with Migen Bus.
  284
+
  285
+A register can be "raw", which means that the core has direct access to it. It also means that the register width must be less or equal to the bus word width. In that case, the register object provides the following signals:
  286
+
  287
+* ``r``, which contains the data written from the bus interface.
  288
+* ``re``, which is the strobe signal for ``r``. It is active for one cycle, after or during a write from the bus. r is only valid when re is high.
  289
+* ``w``, which must provide at all times the value to be read from the bus.
  290
+
  291
+Registers that are not raw are managed by Bank and contain fields. If the sum of the widths of all fields attached to a register exceeds the bus word width, the register will automatically be sliced into words of the maximum size and implemented at consecutive bus addresses, MSB first. Field objects have two parameters, ``access_bus`` and ``access_dev``, determining respectively the access policies for the bus and core sides. They can take the values ``READ_ONLY``, ``WRITE_ONLY`` and ``READ_WRITE``.
  292
+If the device can read, the field object provides the r signal, which contains at all times the current value of the field (kept by the logic generated by Bank).
  293
+If the device can write, the field object provides the following signals:
  294
+
  295
+* ``w``, which provides the value to be written into the field.
  296
+* ``we``, which strobes the value into the field.
  297
+
  298
+As a special exception, fields that are read-only from the bus and write-only for the device do not use the ``we`` signal. Instead, the device must permanently drive valid data on the ``w`` signal.
  299
+
  300
+Generating interrupt controllers
  301
+================================
  302
+TODO: please document me!
  303
+
  304
+.. _asmi:
  305
+
  306
+Advanced System Memory Infrastructure
  307
+*************************************
  308
+
  309
+Rationale
  310
+=========
  311
+The lagging of the DRAM semiconductor processes behind the logic processes has led the industry into a subtle way of ever increasing memory performance.
  312
+
  313
+Modern devices feature a DRAM core running at a fraction of the logic frequency, whose wide data bus is serialized and deserialized to and from the faster clock domain. Further, the presence of more banks increases page hit rate and provides opportunities for parallel execution of commands to different banks.
  314
+
  315
+A first-generation SDR-133 SDRAM chip runs both DRAM, I/O and logic at 133MHz and features 4 banks. A 16-bit chip has a 16-bit DRAM core.
  316
+
  317
+A newer DDR3-1066 chip still runs the DRAM core at 133MHz, but the logic at 533MHz (4 times the DRAM frequency) and the I/O at 1066Mt/s (8 times the DRAM frequency). A 16-bit chip has a 128-bit internal DRAM core. Such a device features 8 banks. Note that the serialization also introduces multiplied delays (e.g. CAS latency) when measured in number of cycles of the logic clock.
  318
+
  319
+To take full advantage of these new architectures, the memory controller should be able to peek ahead at the incoming requests and service several of them in parallel, while respecting the various timing specifications of each DRAM bank and avoiding conflicts for the shared data lines. Going further in this direction, a controller able to complete transfers out of order can provide even more performance by:
  320
+
  321
+#. grouping requests by DRAM row, in order to minimize time spent on precharging and activating banks.
  322
+#. grouping requests by direction (read or write) in order to minimize delays introduced by bus turnaround and write recovery times.
  323
+#. being able to complete a request that hits a page earlier than a concurrent one which requires the cycling of another bank.
  324
+
  325
+The first two techniques are explained with more details in [drreorder]_.
  326
+
  327
+.. [drreorder] http://www.xilinx.com/txpatches/pub/documentation/misc/improving%20ddr%20sdram%20efficiency.pdf
  328
+
  329
+To enable the efficient implementation of these mechanisms, a new communication protocol with the memory controller must be devised. Migen and Milkymist SoC (-NG) implement their own bus, called ASMIbus, based on the split-transaction principle.
  330
+
  331
+Topology
  332
+========
  333
+The ASMI consists of a memory controller (e.g. ASMIcon) containing a hub that connects the multiple masters, handles transaction tags, and presents a view of the pending requests to the rest of the memory controller.
  334
+
  335
+Links between the masters and the hub are using the same ASMIbus protocol described below.
  336
+
  337
+It is suggested that memory controllers use an interface to a PHY compatible with DFI [dfi]_. The DFI clock can be the same as the ASMIbus clock, with optional serialization and deserialization happening across the PHY, as specified in the DFI standard.
  338
+
  339
+TODO: figure
  340
+
  341
+Signals
  342
+=======
  343
+The ASMIbus consists of two parts: the control signals, and the data signals.
  344
+
  345
+The control signals are used to issue requests.
  346
+
  347
+* Master-to-Hub:
  348
+
  349
+  * ``adr`` communicates the memory address to be accessed. The unit is the word width of the particular implementation of ASMIbus.
  350
+  * ``we`` is the write enable signal.
  351
+  * ``stb`` qualifies the transaction request, and should be asserted until ``ack`` goes high.
  352
+
  353
+* Hub-to-Master
  354
+
  355
+  * ``tag_issue`` is an integer representing the transaction ("tag") attributed by the hub. The width of this signal is determined by the maximum number of in-flight transactions that the hub port can handle.
  356
+  * ``ack`` is asserted when ``tag_issue`` is valid and the transaction has been registered by the hub. A hub may assert ACK even when ``stb`` is low, which means it is ready to accept any new transaction and will do as soon as ``stb`` goes high.
  357
+
  358
+The data signals are used to complete requests.
  359
+
  360
+* Hub-to-Master
  361
+
  362
+  * ``tag_call`` is used to identify the transaction for which the data is "called". It takes the tag value that has been previously attributed by the hub to that transaction during the issue phase.
  363
+  * ``call`` qualifies ``tag_call``.
  364
+  * ``data_r`` returns data from the DRAM in the case of a read transaction. It is valid for one cycle after CALL has been asserted and ``tag_call`` has identified the transaction. The value of this signal is undefined for the cycle after a write transaction data have been called.
  365
+
  366
+* Master-to-Hub
  367
+
  368
+  * ``data_w`` must supply data to the controller from the appropriate write transaction, on the cycle after they have been called using ``call`` and ``tag_call``.
  369
+  * ``data_wm`` are the byte-granular write data masks. They are used in combination with ``data_w`` to identify the bytes that should be modified in the memory. The ``data_wm`` bit should be high for its corresponding ``data_w`` byte to be written.
  370
+
  371
+In order to avoid duplicating the tag matching and tracking logic, the master-to-hub data signals must be driven low when they are not in use, so that they can be simply ORed together inside the memory controller. This way, only masters have to track (their own) transactions for arbitrating the data lines.
  372
+
  373
+Tags represent in-flight transactions. The hub can reissue a tag as soon as the cycle when it appears on ``tag_call``.
  374
+
  375
+SDRAM burst length and clock ratios
  376
+===================================
  377
+A system using ASMI must set the SDRAM burst length B, the ASMIbus word width W and the ratio between the ASMIbus clock frequency Fa and the SDRAM I/O frequency Fi so that all data transfers last for exactly one ASMIbus cycle.
  378
+
  379
+More explicitly, these relations must be verified:
  380
+
  381
+B = Fi/Fa
  382
+
  383
+W = B*[number of SDRAM I/O pins]
  384
+
  385
+For DDR memories, the I/O frequency is twice the logic frequency.
  386
+
  387
+Example transactions
  388
+====================
  389
+TODO: please document me!
  390
+
  391
+Using ASMI with Migen
  392
+=====================
  393
+TODO: please document me!
  394
+
  395
+Dataflow high-level synthesis
  396
+#############################
  397
+.. WARNING::
  398
+   This is experimental and incomplete.
  399
+
  400
+Many hardware acceleration problems can be expressed in the dataflow paradigm, that is, using a directed graph representing the flow of data between actors.
  401
+
  402
+Actors in Migen are written directly in FHDL. This maximizes the flexibility: for example, an actor can implement a DMA master to read data from system memory. It is conceivable that a CAL [cal]_ to FHDL compiler be implemented at some point, to support higher level descriptions of some actors and reuse of third-party RVC-CAL applications. [orcc]_ [orcapps]_ [opendf]_
  403
+
  404
+.. [cal] http://opendf.svn.sourceforge.net/viewvc/opendf/trunk/doc/GentleIntro/GentleIntro.pdf
  405
+.. [orcc] http://orcc.sourceforge.net/
  406
+.. [orcapps] http://orc-apps.sourceforge.net/
  407
+.. [opendf] http://opendf.sourceforge.net/
  408
+
  409
+Actors communicate by exchanging tokens, whose flow is typically controlled using handshake signals (strobe/ack).
  410
+
  411
+Each actor has a "scheduling model". It can be:
  412
+
  413
+* N-sequential: the actor fires when tokens are available at all its inputs, and it produces one output token after N cycles. It cannot accept new input tokens until it has produced its output. A multicycle integer divider would use this model.
  414
+* N-pipelined: similar to the sequential model, but the actor can always accept new input tokens. It produces an output token N cycles of latency after accepting input tokens. A pipelined multiplier would use this model.
  415
+* Dynamic: the general case, when no simple hypothesis can be made on the token flow behaviour of the actor. An actor accessing system memory on a shared bus would use this model.
  416
+
  417
+Migen Flow automatically generates handshake logic for the first two scheduling models. In the third case, the FHDL descriptions for the logic driving the handshake signals must be provided by the actor.
  418
+
  419
+An actor can be a composition of other actors.
  420
+
  421
+Actor graphs are managed using the NetworkX [networkx]_ library.
  422
+
  423
+.. [networkx] http://networkx.lanl.gov/
  424
+
  425
+.. _simulating:
  426
+
  427
+Simulating a Migen design
  428
+#########################
481  doc/migen.txt
... ...
@@ -1,481 +0,0 @@
1  
-             Migen (Milkymist Generator)
2  
-a Python toolbox for building complex digital hardware
3  
-======================================================
4  
-
5  
-Background
6  
-==========
7  
-Even though the Milkymist system-on-chip [1] is technically successful,
8  
-it suffers from several limitations stemming from its implementation in
9  
-manually written Verilog HDL:
10  
-
11  
-(1) The "event-driven" paradigm of today's dominant hardware descriptions
12  
-languages (Verilog and VHDL, collectively referred to as "V*HDL" in the
13  
-rest of this document) is often too general. Today's FPGA architectures
14  
-are optimized for the implementation of fully synchronous circuits. This
15  
-means that the bulk of the code for an efficient FPGA design falls into
16  
-three categories:
17  
-  (a) Combinatorial statements
18  
-  (b) Synchronous statements
19  
-  (c) Initialization of registers at reset
20  
-V*HDL do not follow this organization. This means that a lot of
21  
-repetitive manual coding is needed, which brings sources of human errors,
22  
-petty issues, and confusion for beginners:
23  
-  - wire vs. reg in Verilog
24  
-  - forgetting to initialize a register at reset
25  
-  - deciding whether a combinatorial statement must go into a
26  
-    process/always block or not
27  
-  - simulation mismatches with combinatorial processes/always blocks
28  
-  - and more...
29  
-A little-known fact about FPGAs is that many of them have to ability to
30  
-initialize their registers from the bitstream contents. This can be done
31  
-in a portable and standard way using an "initial" block in Verilog, and
32  
-by affecting a value at the signal declaration in VHDL. This renders an
33  
-explicit reset signal unnecessary in practice in some cases, which opens
34  
-the way for further design optimization. However, this form of
35  
-initialization is entirely not synthesizable for ASIC targets, and it is
36  
-not easy to switch between the two forms of reset using V*HDL.
37  
-
38  
-(2) V*HDL support for composite types is very limited. Signals having a
39  
-record type in VHDL are unidirectional, which makes them clumsy to use
40  
-e.g. in bus interfaces. There is no record type support in Verilog, which
41  
-means that a lot of copy-and-paste has to be done when forwarding grouped
42  
-signals.
43  
-
44  
-(3) V*HDL support for procedurally generated logic is extremely limited.
45  
-The most advanced forms of procedural generation of synthesizable logic
46  
-that V*HDL offers are CPP-style directives in Verilog, combinatorial
47  
-functions, and generate statements. Nothing really fancy, and it shows.
48  
-To give a few examples:
49  
-  - Building highly flexible bus interconnect is not possible. Even
50  
-arbitrating any given number of bus masters for commonplace protocols
51  
-such as Wishbone cannot be done with the tools at V*HDL puts at our
52  
-disposal. This requires manual recoding of parts of the arbiter to add or
53  
-remove a master, which is tedious and often cause frustrating errors.
54  
-Each occurence of the latter can easily cause one or two hours of lost
55  
-productivity when combined with the long compilation times of moderately
56  
-complex system-on-chip designs.
57  
-  - Building a memory infrastructure (including bus interconnect, bridges
58  
-and caches) that can automatically adapt itself at compile-time to any
59  
-word size of the SDRAM is clumsy and tedious.
60  
-  - Building register banks for control, status and interrupt management
61  
-of cores can also largely benefit from automation.
62  
-  - Many hardware acceleration problems can fit into the dataflow
63  
-programming model. Manual dataflow implementation in V*HDL has, again, a
64  
-lot of redundancy and potential for human errors. See the Milkymist
65  
-texture mapping unit [3][4] for an example of this. The amount of detail
66  
-to deal with manually also makes the design space exploration difficult,
67  
-and therefore hinders the design of efficient architectures.
68  
-  - Pre-computation of values, such as filter coefficients for DSP or
69  
-even simply trigonometric tables, must often be done using external tools
70  
-whose results are copy-and-pasted (in the best cases, automatically) into
71  
-the V*HDL source.
72  
-
73  
-Enter Migen, a Python toolbox for building complex digital hardware. We
74  
-could have designed a brand new programming language, but that would have
75  
-been reinventing the wheel instead of being able to benefit from Python's
76  
-rich features and immense library. The price to pay is a slightly
77  
-cluttered syntax at times when writing descriptions in FHDL, but we
78  
-believe this is totally acceptable, particularly when compared to VHDL
79  
-;-)
80  
-
81  
-Migen is made up of several related components, which are briefly
82  
-described below.
83  
-
84  
-Migen FHDL
85  
-==========
86  
-The Fragmented Hardware Description Language (FHDL) is the lowest layer
87  
-of Migen. It consists of a formal system to describe signals, and
88  
-combinatorial and synchronous statements operating on them. The formal
89  
-system itself is low level and close to the synthesizable subset of
90  
-Verilog, and we then rely on Python algorithms to build complex
91  
-structures by combining FHDL elements and encapsulating them in
92  
-"fragments".
93  
-The FHDL module also contains a back-end to produce synthesizable
94  
-Verilog, and some basic analysis functions. It would be possible to
95  
-develop a VHDL back-end as well, though more difficult than for Verilog -
96  
-we are "cheating" a bit now as Verilog provides most of the FHDL
97  
-semantics.
98  
-
99  
-FHDL differs from MyHDL [2] in fundamental ways. MyHDL follows the
100  
-event-driven paradigm of traditional HDLs (see Background, #1) while FHDL
101  
-separates the code into combinatorial statements, synchronous statements,
102  
-and reset values. In MyHDL, the logic is described directly in the Python
103  
-AST. The converter to Verilog or VHDL then examines the Python AST and
104  
-recognizes a subset of Python that it translates into V*HDL statements.
105  
-This seriously impedes the capability of MyHDL to generate logic
106  
-procedurally. With FHDL, you manipulate a custom AST from Python, and you
107  
-can more easily design algorithms that operate on it.
108  
-
109  
-FHDL is made of several elements, which are briefly explained below.
110  
-
111  
-BV
112  
---
113  
-The bit vector (BV) object defines if a constant or signal is signed or
114  
-unsigned, and how many bits it has. This is useful e.g. to:
115  
- - determine when to perform sign extension (FHDL uses the same rules as
116  
-Verilog).
117  
- - determine the size of registers.
118  
- - determine how many bits should be used by each value in
119  
-concatenations.
120  
-
121  
-Constant
122  
---------
123  
-This object should be self-explanatory. All constant objects contain a BV
124  
-object and a value. If no BV object is specified, one will be made up
125  
-using the following rules:
126  
-  - If the value is positive, the BV is unsigned and has the minimum
127  
-number of bits needed to represent the constant's value in the canonical
128  
-base-2 system.
129  
-  - If the value is negative, the BV is signed, and has the minimum
130  
-number of bits needed to represent the constant's value in the canonical
131  
-two's complement, base-2 system.
132  
-
133  
-Signal
134  
-------
135  
-The signal object represents a value that is expected to change in the
136  
-circuit. It does exactly what Verilog's "wire" and "reg" and VHDL's
137  
-"signal" and "variable" do.
138  
-
139  
-The main point of the signal object is that it is identified by its
140  
-Python ID (as returned by the id() function), and nothing else. It is the
141  
-responsibility of the V*HDL back-end to establish an injective mapping
142  
-between Python IDs and the V*HDL namespace. It should perform name
143  
-mangling to ensure this. The consequence of this is that signal objects
144  
-can safely become members of arbitrary Python classes, or be passed as
145  
-parameters to functions or methods that generate logic involving them.
146  
-
147  
-The properties of a signal object are:
148  
-  - a bit vector description
149  
-  - a name, used as a hint for the V*HDL back-end name mangler.
150  
-  - a boolean "variable". If true, the signal will behave like a VHDL
151  
-variable, or a Verilog reg that uses blocking assignment. This parameter
152  
-only has an effect when the signal's value is modified in a synchronous
153  
-statement.
154  
-  - the signal's reset value. It must be an integer, and defaults to 0.
155  
-When the signal's value is modified with a synchronous statement, the
156  
-reset value is the initialization value of the associated register.
157  
-When the signal is assigned to in a conditional combinatorial statement
158  
-(If or Case), the reset value is the value that the signal has when no
159  
-condition that causes the signal to be driven is verified. This enforces
160  
-the absence of latches in designs. If the signal is permanently driven
161  
-using a combinatorial statement, the reset value has no effect.
162  
-  
163  
-The sole purpose of the name property is to make the generated V*HDL code
164  
-easier to understand and debug. From a purely functional point of view,
165  
-it is perfectly OK to have several signals with the same name property.
166  
-The back-end will generate a unique name for each object. If no name
167  
-property is specified, Migen will analyze the code that created the
168  
-signal object, and try to extract the variable or member name from there.
169  
-It then uses the module name that created the signal, a underscore, and
170  
-the variable name. For example, if we are in module "foo", the following
171  
-statements will create one or several signal(s) named "foo_bar":
172  
-  bar = Signal()
173  
-  self.bar = Signal()
174  
-  self.baz.bar = Signal()
175  
-  bar = [Signal() for x in range(42)]
176  
-
177  
-Operators
178  
----------
179  
-Operators are represented by the _Operator object, which generally should
180  
-not be used directly. Instead, most FHDL objects overload the usual
181  
-Python logic and arithmetic operators, which allows a much lighter syntax
182  
-to be used. For example, the expression:
183  
-  a * b + c
184  
-is equivalent to:
185  
-  _Operator('+', [_Operator('*', [a, b]), c])
186  
-  
187  
-Slices
188  
-------
189  
-Likewise, slices are represented by the _Slice object, which often should
190  
-not be used in favor of the Python slice operation [x:y].
191  
-Implicit indices using the forms [x], [x:] and [:y] are supported.
192  
-Beware! Slices work like Python slices, not like VHDL or Verilog slices.
193  
-The first bound is the index of the LSB and is inclusive. The second
194  
-bound is the index of MSB and is exclusive. In V*HDL, bounds are MSB:LSB
195  
-and both are inclusive.
196  
-
197  
-Concatenations
198  
---------------
199  
-Concatenations are done using the Cat object. To make the syntax lighter,
200  
-its constructor takes a variable number of arguments, which are the
201  
-signals to be concatenated together (you can use the Python '*' operator
202  
-to pass a list instead).
203  
-To be consistent with slices, the first signal is connected to the bits
204  
-with the lowest indices in the result. This is the opposite of the way
205  
-the '{}' construct works in Verilog.
206  
-
207  
-Replications
208  
-------------
209  
-The Replicate object represents the equivalent of {count{expression}} in
210  
-Verilog.
211  
-
212  
-Assignments
213  
------------
214  
-Assignments are represented with the _Assign object. Since using it
215  
-directly would result in a cluttered syntax, the preferred technique for
216  
-assignments is to use the eq() method provided by objects that can have a
217  
-value assigned to them. They are signals, and their combinations with the
218  
-slice and concatenation operators.
219  
-As an example, the statement:
220  
-  a[0].eq(b)
221  
-is equivalent to:
222  
-  _Assign(_Slice(a, 0, 1), b)
223  
-
224  
-If statement
225  
-------------
226  
-The If object takes a first parameter which must be an expression
227  
-(combination of the Constant, Signal, _Operator, _Slice, etc. objects)
228  
-representing the condition, then a variable number of parameters
229  
-representing the statements (_Assign, If, Case, etc. objects) to be
230  
-executed when the condition is verified.
231  
-
232  
-The If object defines a Else() method, which when called defines the
233  
-statements to be executed when the condition is not true. Those
234  
-statements are passed as parameters to the variadic method.
235  
-
236  
-For convenience, there is also a Elif() method.
237  
-
238  
-Example:
239  
-If(tx_count16 == 0,
240  
-    tx_bitcount.eq(tx_bitcount + 1),
241  
-    If(tx_bitcount == 8,
242  
-        self.tx.eq(1)
243  
-    ).Elif(tx_bitcount == 9,
244  
-        self.tx.eq(1),
245  
-        tx_busy.eq(0)