doc/socdoc.md

   1 # Litex Documentation: Document your LiteX SoC Automatically
   2
   3 Litex lets you take a synthesized SoC and generate full
   4 register-level documentation.  Additionally, it will generate `.svd` files,
   5 suitable for use with various header generation programs.
   6
   7 ## Required Software
   8
   9 You must have `sphinx` and `sphinx.wavedrom` installed in order to build
  10 the documentation.  These can be installed with pip:
  11
  12 ```
  13 $ pip3 install sphinxcontrib-wavedrom sphinx
  14 ```
  15
  16 ## Usage
  17
  18 To document your modules, import the `doc` module and call `doc.generate_docs(soc, path)`.
  19 You can also generate an SVD file.  For example:
  20
  21 ```python
  22 from litex.soc.doc import generate_docs, generate_svd
  23
  24 ...
  25     soc = BaseSoC(platform)
  26     builder = Builder(soc)
  27     vns = builder.build()
  28     soc.do_exit(vns)
  29     generate_docs(soc, "build/documentation",
  30                         project_name="My SoC",
  31                         author="LiteX User")
  32     generate_svd(soc, "build/software")
  33 ```
  34
  35 After you build your design, you will have a Sphinx documentation source available
  36 in the above directory.  To build this into a target document, use `sphinx-build`.
  37
  38 For example, if `sphinx-build` is in your path, you can run:
  39
  40 `sphinx-build -M html build/documentation/ build/documentation/_build`
  41
  42 `sphinx-build` may be located in `~/.local/bin/` depending on your installation environment.
  43
  44 You can then verify the contents by opening the file `build/documentation/_build/html/index.html`
  45
  46 ## Documenting your Registers
  47
  48 You can add documentation to your registers by defining your `CSRStorage` and `CSRStatus` registers with an additional `field` list.  For example:
  49
  50 ```python
  51 self.bitbang = CSRStorage(4, fields=[
  52     CSRField("mosi", description="Output value for MOSI..."
  53     CSRField("clk", description="Output value for SPI CLK..."
  54     CSRField("cs_n", description="Output value for SPI C..."
  55     CSRField("dir", description="Sets the dir...", values=[
  56         ("0", "OUT", "SPI pins are all output"),
  57         ("1", "IN", "SPI pins are all input"),
  58     ])
  59 ], description="""Bitbang controls for SPI output.  Only
  60     standard 1x SPI is supported, and as a result all
  61     four wires are ganged together.  This means that it
  62     is only possible to perform half-duplex operations,
  63     using this SPI core.""")
  64 ```
  65
  66 There are several interesting properties here:
  67
  68 * The first argument to a `CSRStorage` or `CSRStatus` is the bit width.
  69 * You can pass a list of `CSRField` objects, which will get turned into bit fields
  70 * Both `CSRStorage` and `CSRStatus` support a freeform `description` property that will be used to describe the overall register.
  71
  72 A `CSRField` object has the following properties:
  73
  74 * `name`: The short name of the register.  This should be just a few characters long, as it will be used in the register diagram as well as accessor objects.  **Required**
  75 * `size`: The size of this field.  This is optional, and defaults to `1`
  76 * `offset`: The offset of this particular field.  If unspecified, defaults to following the previous field.  Use this to add gaps to your register definitions, for example to have reserved fields.
  77 * `reset`: If specified, the value of this field at reset.  Defaults to `0`.
  78 * `description`: A textual description of this register.  This is optional, but should be specified because it provides critical information to the user about what this field does.
  79 * `pulse`: If `True`, then this value is `1` only for one clock cycle after the user writes a `1` to this field.  This is especially useful for `START` bits used to initiate operations, or `RESET` bits used to clear an operation.
  80 * `access`: The accessibility of this field.  One of `CSRAccess.ReadWrite`, `CSRAccess.WriteOnly`, or `CSRAccess.ReadOnly`
  81 * `values`: If present, a list of tuples of values.  The first field is the numeric value, with `x` for `don't care`.  The second field, if present, is the short name of the value.  The final field is a textual description of the value.  For example:
  82
  83 ```python
  84     [
  85         ("0b0000", "disable the timer"),
  86         ("0b0001", "slow", "slow timer"),
  87         ("0b1xxx", "fast timer"),
  88     ]
  89 ```
  90
  91 ## Further Module Documentation
  92
  93 You can add additional documentation to your module with the `ModuleDoc` class.  Add it to your base object.
  94
  95 **To use further Module Documentation, your Module must inherit from `AutoDoc`**.  For example:
  96
  97 ```python
  98 from litex.soc.integration.doc import AutoDoc, ModuleDoc
  99 class DocExample(Module, AutoCSR, AutoDoc):
 100     def __init__(self):
 101         self.mydoc = ModuleDoc("Some documentation")
 102 ```
 103
 104 You may pass a single string to the constructor, in which case the first line becomes the title, or you may pass a separate `title` and `body` parameters to the constructor.  For example:
 105
 106 ```python
 107     self.intro = ModuleDoc("""Introduce ModuleDoc
 108
 109     This is an example of how to document using ModuleDoc.  An additional
 110     section will get added to the output documentation for this module,
 111     with the title ``Introduce ModuleDoc`` and with this paragraph
 112     as a body""")
 113 ```
 114
 115 Note that the default documentation format is `rst`. You can switch to markdown by passing `format="markdown"` to the constructor, however support is not very good.
 116
 117 ### Additional Sphinx Extensions
 118
 119 The `generate_docs()` call produces Sphinx output. By default it only includes
 120 additional extensions for `sphinxcontrib.wavedrom`, which is required to display
 121 register listings. You can add additional modules by passing an array to
 122 `generate_docs()`. For example, to add `mathjax` support:
 123
 124 ```python
 125     generate_docs("build/documentation", sphinx_extensions=['sphinx.ext.mathjax'])
 126 ```
 127
 128 By default, `socdoc` unconditionally overwrites all files in the output
 129 directory, including the sphinx `conf.py` file. To disable this feature
 130 so you can customize your own `conf.py` file, pass `from_scratch=False`:
 131
 132 ```python
 133     generate_docs("build/documentation", from_scratch=False)
 134 ```
 135
 136 In this case, `conf.py` will only be created if it does not already exist.
 137
 138 ### External Documentation
 139
 140 You can have external documentation by passing `file` to the constructor.
 141 For example:
 142
 143 ```python
 144     self.extra_doc = ModuleDoc(file="extra_doc.rst")
 145 ```
 146
 147 This will be included at build-time.
 148
 149 ### Using Python Docstrings
 150
 151 You can also simply have your module inherit from `ModuleDoc`, in which case
 152 the documentation will be taken from the docstring.  For example:
 153
 154 ```python
 155 from litex.soc.integration.doc import AutoDoc, ModuleDoc
 156 class DocExample(Module, AutoCSR, AutoDoc, ModuleDoc):
 157     """
 158     Automatically Documented Module
 159
 160     This module will be automatically documented, and included in the
 161     generated module documentation output.  You can add additional
 162     ModuleDoc objects to this module, in order to add further subsections
 163     to the output docs.
 164     """
 165     def __init__(self):
 166         pass
 167 ```