litex/doc/socdoc.md

Litex Documentation: Document your LiteX SoC Automatically

Litex lets you take a synthesized SoC and generate full register-level documentation. Additionally, it will generate .svd files, suitable for use with various header generation programs.

Required Software

You must have sphinx and sphinx.wavedrom installed in order to build the documentation. These can be installed with pip:

$ pip3 install sphinxcontrib-wavedrom sphinx

Usage

To document your modules, import the doc module and call doc.generate_docs(soc, path). You can also generate an SVD file. For example:

from litex.soc.doc import generate_docs, generate_svd

...
    soc = BaseSoC(platform)
    builder = Builder(soc)
    vns = builder.build()
    soc.do_exit(vns)
    generate_docs(soc, "build/documentation",
                        project_name="My SoC",
                        author="LiteX User")
    generate_svd(soc, "build/software")

After you build your design, you will have a Sphinx documentation source available in the above directory. To build this into a target document, use sphinx-build.

For example, if sphinx-build is in your path, you can run:

sphinx-build -M html build/documentation/ build/documentation/_build

sphinx-build may be located in ~/.local/bin/ depending on your installation environment.

You can then verify the contents by opening the file build/documentation/_build/html/index.html

Documenting your Registers

You can add documentation to your registers by defining your CSRStorage and CSRStatus registers with an additional field list. For example:

self.bitbang = CSRStorage(4, fields=[
    CSRField("mosi", description="Output value for MOSI..."
    CSRField("clk", description="Output value for SPI CLK..."
    CSRField("cs_n", description="Output value for SPI C..."
    CSRField("dir", description="Sets the dir...", values=[
        ("0", "OUT", "SPI pins are all output"),
        ("1", "IN", "SPI pins are all input"),
    ])
], description="""Bitbang controls for SPI output.  Only
    standard 1x SPI is supported, and as a result all
    four wires are ganged together.  This means that it
    is only possible to perform half-duplex operations,
    using this SPI core.""")

There are several interesting properties here:

• The first argument to a CSRStorage or CSRStatus is the bit width.
• You can pass a list of CSRField objects, which will get turned into bit fields
• Both CSRStorage and CSRStatus support a freeform description property that will be used to describe the overall register.

A CSRField object has the following properties:

• 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
• size: The size of this field. This is optional, and defaults to 1
• 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.
• reset: If specified, the value of this field at reset. Defaults to 0.
• 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.
• 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.
• access: The accessibility of this field. One of CSRAccess.ReadWrite, CSRAccess.WriteOnly, or CSRAccess.ReadOnly
• 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:

    [
        ("0b0000", "disable the timer"),
        ("0b0001", "slow", "slow timer"),
        ("0b1xxx", "fast timer"),
    ]

Further Module Documentation

You can add additional documentation to your module with the ModuleDoc class. Add it to your base object.

To use further Module Documentation, your Module must inherit from AutoDoc. For example:

from litex.soc.integration.doc import AutoDoc, ModuleDoc
class DocExample(Module, AutoCSR, AutoDoc):
    def __init__(self):
        self.mydoc = ModuleDoc("Some documentation")

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:

    self.intro = ModuleDoc("""Introduce ModuleDoc

    This is an example of how to document using ModuleDoc.  An additional
    section will get added to the output documentation for this module,
    with the title ``Introduce ModuleDoc`` and with this paragraph
    as a body""")

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.

Additional Sphinx Extensions

The generate_docs() call produces Sphinx output. By default it only includes additional extensions for sphinxcontrib.wavedrom, which is required to display register listings. You can add additional modules by passing an array to generate_docs(). For example, to add mathjax support:

    generate_docs("build/documentation", sphinx_extensions=['sphinx.ext.mathjax'])

You may need to pass additional configuration to conf.py. In this case, pass it as sphinx_extra_config. For example:

    generate_docs("build/documentation",
            sphinx_extensions=['sphinx_math_dollar', 'sphinx.ext.mathjax'],
            sphinx_extra_config=r"""
   mathjax_config = {
       'tex2jax': {
           'inlineMath': [ ["\\(","\\)"] ],
           'displayMath': [["\\[","\\]"] ],
       },
   }""")

By default, socdoc unconditionally overwrites all files in the output directory, including the sphinx conf.py file. To disable this feature so you can customize your own conf.py file, pass from_scratch=False:

    generate_docs("build/documentation", from_scratch=False)

In this case, conf.py will only be created if it does not already exist.

External Documentation

You can have external documentation by passing file to the constructor. For example:

    self.extra_doc = ModuleDoc(file="extra_doc.rst")

This will be included at build-time.

Using Python Docstrings

You can also simply have your module inherit from ModuleDoc, in which case the documentation will be taken from the docstring. For example:

from litex.soc.integration.doc import AutoDoc, ModuleDoc
class DocExample(Module, AutoCSR, AutoDoc, ModuleDoc):
    """
    Automatically Documented Module

    This module will be automatically documented, and included in the
    generated module documentation output.  You can add additional
    ModuleDoc objects to this module, in order to add further subsections
    to the output docs.
    """
    def __init__(self):
        pass