litex/doc/socdoc.md

183 lines
7.1 KiB
Markdown

# 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:
```python
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:
```python
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:
```python
[
("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:
```python
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:
```python
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:
```python
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:
```python
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`:
```python
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:
```python
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:
```python
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
```