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)) svd.write(export.get_svd(soc, **kwargs))
def generate_docs(soc, base_dir, project_name="LiteX SoC Project", def generate_docs(soc, base_dir,
author="Anonymous", sphinx_extensions=[], quiet=False, note_pulses=False, project_name = "LiteX SoC Project",
from_scratch=True): author = "Anonymous",
sphinx_extensions = [],
quiet = False,
note_pulses = False,
from_scratch = True):
"""Possible extra extensions: """Possible extra extensions:
[ [
'm2r', 'm2r',

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

@ -34,7 +34,16 @@ class DocumentedCSR:
return reflow(docstring) return reflow(docstring)
return None 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.name = name
self.short_name = short_name self.short_name = short_name
self.short_numbered_name = short_numbered_name self.short_numbered_name = short_numbered_name
@ -81,10 +90,16 @@ class DocumentedCSRRegion:
print("{}: Unknown module: {}".format(self.name, csr)) print("{}: Unknown module: {}".format(self.name, csr))
elif isinstance(self.raw_csrs, Memory): elif isinstance(self.raw_csrs, Memory):
self.csrs.append(DocumentedCSR( 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, name = self.name.upper(),
description="{} x {}-bit memory".format(self.raw_csrs.width, self.raw_csrs.depth) 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: else:
print("{}@{:x}: Unexpected item on the CSR bus: {}".format(self.name, self.origin, self.raw_csrs)) print("{}@{:x}: Unexpected item on the CSR bus: {}".format(self.name, self.origin, self.raw_csrs))
@ -127,9 +142,15 @@ class DocumentedCSRRegion:
fields = [] fields = []
for i, source in enumerate(sources): for i, source in enumerate(sources):
if hasattr(source, "name") and source.name is not None: 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: 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 dcsr.fields = fields
if dcsr.description is None: 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." 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 = [] fields = []
for i, source in enumerate(sources): for i, source in enumerate(sources):
if hasattr(source, "name") and source.name is not None: 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: 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 dcsr.fields = fields
if dcsr.description is None: 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." 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 = [] fields = []
for i, source in enumerate(sources): for i, source in enumerate(sources):
if hasattr(source, "name") and source.name is not None: 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: 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 dcsr.fields = fields
if dcsr.description is None: if dcsr.description is None:
dcsr.description = "This register enables the corresponding Events. Write a `0` to this register to disable individual events." 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: else:
d = bits_str + " " + reflow(d) d = bits_str + " " + reflow(d)
self.csrs.append(DocumentedCSR( 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), name = sub_name,
offset=start, size=self.csr_data_width, address = self.current_address,
description=d, fields=self.split_fields(fields, start, start + length), access=access 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: else:
self.csrs.append(DocumentedCSR( 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), name = sub_name,
offset=start, size=self.csr_data_width, address = self.current_address,
description=bits_str, fields=self.split_fields(fields, start, start + length), access=access 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 self.current_address += 4
else: else:
self.csrs.append(DocumentedCSR( self.csrs.append(DocumentedCSR(
full_name, self.current_address, short_numbered_name=csr.name.upper(), short_name=csr.name.upper(), reset=reset, size=size, name = full_name,
description=description, fields=fields, access=access 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 self.current_address += 4
def make_value_table(self, values): def make_value_table(self, values):
ret = "" ret = ""
max_value_width=len("Value") max_value_width = len("Value")
max_description_width=len("Description") max_description_width = len("Description")
for v in values: for v in values:
(value, name, description) = (None, None, None) (value, name, description) = (None, None, None)
if len(v) == 2: if len(v) == 2:
@ -417,11 +471,10 @@ class DocumentedCSRRegion:
print(textwrap.indent(csr.description, prefix=" "), file=stream) print(textwrap.indent(csr.description, prefix=" "), file=stream)
self.print_reg(csr, stream) self.print_reg(csr, stream)
if len(csr.fields) > 0: if len(csr.fields) > 0:
max_field_width=len("Field") max_field_width = len("Field")
max_name_width=len("Name") max_name_width = len("Name")
max_description_width=len("Description") max_description_width = len("Description")
value_tables = {} value_tables = {}
for f in csr.fields: for f in csr.fields:
field = self.bit_range(f.offset, f.offset + f.size) field = self.bit_range(f.offset, f.offset + f.size)
max_field_width = max(max_field_width, len(field)) max_field_width = max(max_field_width, len(field))