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     generate_svd(soc, "build/software")
  31 ```
  32
  33 After you build your design, you will have a Sphinx documentation source available
  34 in the above directory.  To build this into a target document, use `sphinx-build`.
  35
  36 For example, if `sphinx-build` is in your path, you can run:
  37
  38 `sphinx-build -M html build/documentation/ build/documentation/_build`
  39
  40 `sphinx-build` may be located in `~/.local/bin/` depending on your installation environment.
  41
  42 You can then verify the contents by opening the file `build/documentation/_build/html/index.html`
  43
  44 ## Documenting your Registers
  45
  46 You can add documentation to your registers by defining your `CSRStorage` and `CSRStatus` registers with an additional `field` list.  For example:
  47
  48 ```python
  49 self.bitbang = CSRStorage(4, fields=[
  50     CSRField("mosi", description="Output value for MOSI..."
  51     CSRField("clk", description="Output value for SPI CLK..."
  52     CSRField("cs_n", description="Output value for SPI C..."
  53     CSRField("dir", description="Sets the dir...", values=[
  54         ("0", "OUT", "SPI pins are all output"),
  55         ("1", "IN", "SPI pins are all input"),
  56     ])
  57 ], description="""Bitbang controls for SPI output.  Only
  58     standard 1x SPI is supported, and as a result all
  59     four wires are ganged together.  This means that it
  60     is only possible to perform half-duplex operations,
  61     using this SPI core.""")
  62 ```
  63
  64 There are several interesting properties here:
  65
  66 * The first argument to a `CSRStorage` or `CSRStatus` is the bit width.
  67 * You can pass a list of `CSRField` objects, which will get turned into bit fields
  68 * Both `CSRStorage` and `CSRStatus` support a freeform `description` property that will be used to describe the overall register.
  69
  70 A `CSRField` object has the following properties:
  71
  72 * `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**
  73 * `size`: The size of this field.  This is optional, and defaults to `1`
  74 * `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.
  75 * `reset`: If specified, the value of this field at reset.  Defaults to `0`.
  76 * `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.
  77 * `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.
  78 * `access`: The accessibility of this field.  One of `CSRAccess.ReadWrite`, `CSRAccess.WriteOnly`, or `CSRAccess.ReadOnly`
  79 * `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:
  80
  81 ```python
  82     [
  83         ("0b0000", "disable the timer"),
  84         ("0b0001", "slow", "slow timer"),
  85         ("0b1xxx", "fast timer"),
  86     ]
  87 ```
  88
  89 ## Further Module Documentation
  90
  91 You can add additional documentation to your module with the `ModuleDoc` class.  Add it to your base object.
  92
  93 **To use further Module Documentation, your Module must inherit from `AutoDoc`**.  For example:
  94
  95 ```python
  96 from litex.soc.integration.doc import AutoDoc, ModuleDoc
  97 class DocExample(Module, AutoCSR, AutoDoc):
  98     def __init__(self):
  99         self.mydoc = ModuleDoc("Some documentation")
 100 ```
 101
 102 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:
 103
 104 ```python
 105     self.intro = ModuleDoc("""Introduce ModuleDoc
 106
 107     This is an example of how to document using ModuleDoc.  An additional
 108     section will get added to the output documentation for this module,
 109     with the title ``Introduce ModuleDoc`` and with this paragraph
 110     as a body""")
 111 ```
 112
 113 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.
 114
 115 ### External Documentation
 116
 117 You can have external documentation by passing `file` to the constructor.
 118 For example:
 119
 120 ```python
 121     self.extra_doc = ModuleDoc(file="extra_doc.rst")
 122 ```
 123
 124 This will be included at build-time.
 125
 126 ### Using Python Docstrings
 127
 128 You can also simply have your module inherit from `ModuleDoc`, in which case
 129 the documentation will be taken from the docstring.  For example:
 130
 131 ```python
 132 from litex.soc.integration.doc import AutoDoc, ModuleDoc
 133 class DocExample(Module, AutoCSR, AutoDoc, ModuleDoc):
 134     """
 135     Automatically Documented Module
 136
 137     This module will be automatically documented, and included in the
 138     generated module documentation output.  You can add additional
 139     ModuleDoc objects to this module, in order to add further subsections
 140     to the output docs.
 141     """
 142     def __init__(self):
 143         pass
 144 ```