Hardware
/
litex
mirror of https://github.com/enjoy-digital/litex.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: align to improve readability.

This commit is contained in:
Florent Kermarrec 2020-03-04 16:31:41 +01:00
parent 4f935714de
commit 4c83c975b1
3 changed files with 112 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
litex/soc/doc/__init__.py
View File

@ -35,9 +35,13 @@ def generate_svd(soc, buildpath, filename=None, name="soc", **kwargs):
svd.write(export.get_svd(soc, **kwargs))
def generate_docs(soc, base_dir, project_name="LiteX SoC Project",
author="Anonymous", sphinx_extensions=[], quiet=False, note_pulses=False,
from_scratch=True):
def generate_docs(soc, base_dir,
project_name = "LiteX SoC Project",
author = "Anonymous",
sphinx_extensions = [],
quiet = False,
note_pulses = False,
from_scratch = True):
"""Possible extra extensions:
[
'm2r',

101
litex/soc/doc/csr.py
View File

@ -34,7 +34,16 @@ class DocumentedCSR:
return reflow(docstring)
return None
def __init__(self, name, address, short_numbered_name="", short_name="", reset=0, offset=0, size=8, description=None, access="read-write", fields=[]):
def __init__(self, name, address,
short_numbered_name = "",
short_name = "",
reset = 0,
offset = 0,
size = 8,
description = None,
access = "read-write",
fields = []):
self.name = name
self.short_name = short_name
self.short_numbered_name = short_numbered_name
@ -81,10 +90,16 @@ class DocumentedCSRRegion:
print("{}: Unknown module: {}".format(self.name, csr))
elif isinstance(self.raw_csrs, Memory):
self.csrs.append(DocumentedCSR(
self.name.upper(), self.origin, short_numbered_name=self.name.upper(), short_name=self.name.upper(), reset=0, size=self.raw_csrs.width,
description="{} x {}-bit memory".format(self.raw_csrs.width, self.raw_csrs.depth)
name = self.name.upper(),
address = self.origin,
short_numbered_name = self.name.upper(),
short_name = self.name.upper(),
reset = 0,
size = self.raw_csrs.width,
description = "{} x {}-bit memory".format(self.raw_csrs.width, self.raw_csrs.depth)
))
print("{}@{:x}: Found memory that's {} x {} (but memories aren't documented yet)".format(self.name, self.origin, self.raw_csrs.width, self.raw_csrs.depth))
print("{}@{:x}: Found memory that's {} x {} (but memories aren't documented yet)".format(
self.name, self.origin, self.raw_csrs.width, self.raw_csrs.depth))
else:
print("{}@{:x}: Unexpected item on the CSR bus: {}".format(self.name, self.origin, self.raw_csrs))
@ -127,9 +142,15 @@ class DocumentedCSRRegion:
fields = []
for i, source in enumerate(sources):
if hasattr(source, "name") and source.name is not None:
fields.append(DocumentedCSRField(CSRField(source.name, offset=i, description="Level of the `{}` event".format(source.name))))
fields.append(DocumentedCSRField(CSRField(
name = source.name,
offset = i,
description = "Level of the `{}` event".format(source.name))))
else:
fields.append(DocumentedCSRField(CSRField("event{}".format(i), offset=i, description="Level of the `event{}` event".format(i))))
fields.append(DocumentedCSRField(CSRField(
name = "event{}".format(i),
offset = i,
description = "Level of the `event{}` event".format(i))))
dcsr.fields = fields
if dcsr.description is None:
dcsr.description = "This register contains the current raw level of the Event trigger. Writes to this register have no effect."
@ -138,9 +159,15 @@ class DocumentedCSRRegion:
fields = []
for i, source in enumerate(sources):
if hasattr(source, "name") and source.name is not None:
fields.append(DocumentedCSRField(CSRField(source.name, offset=i, description=source_description(source))))
fields.append(DocumentedCSRField(CSRField(
name = source.name,
offset = i,
description = source_description(source))))
else:
fields.append(DocumentedCSRField(CSRField("event{}".format(i), offset=i, description=source_description(source))))
fields.append(DocumentedCSRField(CSRField(
name = "event{}".format(i),
offset = i,
description = source_description(source))))
dcsr.fields = fields
if dcsr.description is None:
dcsr.description = "When an Event occurs, the corresponding bit will be set in this register. To clear the Event, set the corresponding bit in this register."
@ -149,9 +176,15 @@ class DocumentedCSRRegion:
fields = []
for i, source in enumerate(sources):
if hasattr(source, "name") and source.name is not None:
fields.append(DocumentedCSRField(CSRField(source.name, offset=i, description="Write a `1` to enable the `{}` Event".format(source.name))))
fields.append(DocumentedCSRField(CSRField(
name = source.name,
offset = i,
description = "Write a `1` to enable the `{}` Event".format(source.name))))
else:
fields.append(DocumentedCSRField(CSRField("event{}".format(i), offset=i, description="Write a `1` to enable the `{}` Event".format(i))))
fields.append(DocumentedCSRField(CSRField(
name = "event{}".format(i),
offset = i,
description = "Write a `1` to enable the `{}` Event".format(i))))
dcsr.fields = fields
if dcsr.description is None:
dcsr.description = "This register enables the corresponding Events. Write a `0` to this register to disable individual events."
@ -306,28 +339,49 @@ class DocumentedCSRRegion:
else:
d = bits_str + " " + reflow(d)
self.csrs.append(DocumentedCSR(
sub_name, self.current_address, short_numbered_name=name.upper(), short_name=csr.name.upper(), reset=(reset>>start)&((2**length)-1),
offset=start, size=self.csr_data_width,
description=d, fields=self.split_fields(fields, start, start + length), access=access
name = sub_name,
address = self.current_address,
short_numbered_name = name.upper(),
short_name = csr.name.upper(),
reset = (reset>>start)&((2**length)-1),
offset = start,
size = self.csr_data_width,
description = d,
fields = self.split_fields(fields, start, start + length),
access = access
))
else:
self.csrs.append(DocumentedCSR(
sub_name, self.current_address, short_numbered_name=name.upper(), short_name=csr.name.upper(), reset=(reset>>start)&((2**length)-1),
offset=start, size=self.csr_data_width,
description=bits_str, fields=self.split_fields(fields, start, start + length), access=access
name = sub_name,
address = self.current_address,
short_numbered_name = name.upper(),
short_name = csr.name.upper(),
reset = (reset>>start)&((2**length)-1),
offset = start,
size = self.csr_data_width,
description = bits_str,
fields = self.split_fields(fields, start, start + length),
access = access
))
self.current_address += 4
else:
self.csrs.append(DocumentedCSR(
full_name, self.current_address, short_numbered_name=csr.name.upper(), short_name=csr.name.upper(), reset=reset, size=size,
description=description, fields=fields, access=access
name = full_name,
address = self.current_address,
short_numbered_name = csr.name.upper(),
short_name = csr.name.upper(),
reset = reset,
size = size,
description = description,
fields = fields,
access = access
))
self.current_address += 4
def make_value_table(self, values):
ret = ""
max_value_width=len("Value")
max_description_width=len("Description")
max_value_width = len("Value")
max_description_width = len("Description")
for v in values:
(value, name, description) = (None, None, None)
if len(v) == 2:
@ -417,11 +471,10 @@ class DocumentedCSRRegion:
print(textwrap.indent(csr.description, prefix=" "), file=stream)
self.print_reg(csr, stream)
if len(csr.fields) > 0:
max_field_width=len("Field")
max_name_width=len("Name")
max_description_width=len("Description")
max_field_width = len("Field")
max_name_width = len("Name")
max_description_width = len("Description")
value_tables = {}
for f in csr.fields:
field = self.bit_range(f.offset, f.offset + f.size)
max_field_width = max(max_field_width, len(field))