docs: Use doctools (#1258)
The extensions have been moved to docs tools. The source code is available at https://github.com/analogdevicesinc/doctools And is installed as before: (cd docs ; pip install -r requirements.txt --upgrade) Since the package is listed on the requirements.txt file. Also, add index for library and projects Signed-off-by: Jorge Marques <jorge.marques@analog.com>main
Jorge Marques
GitHub
parent
af64c55613
commit
be0e2809e9
|
|
@ -47,9 +47,13 @@ This repository supports reference designs for different [Analog Devices boards]
|
||||||
|
|
||||||
### Building documentation
|
### Building documentation
|
||||||
|
|
||||||
|
Ensure pip is newer than version 23.
|
||||||
|
```
|
||||||
|
pip install pip --upgrade
|
||||||
|
```
|
||||||
Install the documentation tools.
|
Install the documentation tools.
|
||||||
```
|
```
|
||||||
(cd docs ; pip install -r requirements.txt)
|
(cd docs ; pip install -r requirements.txt --upgrade)
|
||||||
```
|
```
|
||||||
Build the libraries (recommended).
|
Build the libraries (recommended).
|
||||||
```
|
```
|
||||||
|
|
|
||||||
45
docs/conf.py
45
docs/conf.py
|
|
@ -1,33 +1,33 @@
|
||||||
# Configuration file for the Sphinx documentation builder.
|
# -- Project information ------------------------------------------------------
|
||||||
#
|
|
||||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
|
||||||
|
|
||||||
# -- Project information -----------------------------------------------------
|
repository = 'hdl'
|
||||||
|
project = 'HDL'
|
||||||
|
copyright = '2024, Analog Devices, Inc.'
|
||||||
|
author = 'Analog Devices, Inc.'
|
||||||
|
|
||||||
project = 'HDL, Analog Devices'
|
# -- General configuration ----------------------------------------------------
|
||||||
copyright = '2023, Analog Devices Inc'
|
|
||||||
author = 'Analog Devices Inc'
|
|
||||||
release = 'v0.1'
|
|
||||||
|
|
||||||
# -- General configuration ---------------------------------------------------
|
|
||||||
|
|
||||||
import os, sys
|
|
||||||
|
|
||||||
sys.path.append(os.path.abspath("./extensions"))
|
|
||||||
|
|
||||||
extensions = [
|
extensions = [
|
||||||
"sphinx.ext.todo",
|
"sphinx.ext.todo",
|
||||||
"sphinx.ext.viewcode",
|
"sphinx.ext.intersphinx",
|
||||||
"sphinxcontrib.wavedrom",
|
"sphinxcontrib.wavedrom",
|
||||||
"adi_links",
|
"adi_doctools"
|
||||||
"adi_hdl_parser"
|
|
||||||
]
|
]
|
||||||
|
|
||||||
templates_path = ['sources/template']
|
needs_extensions = {
|
||||||
|
'adi_doctools': '0.3'
|
||||||
|
}
|
||||||
|
|
||||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||||
|
source_suffix = '.rst'
|
||||||
|
|
||||||
# -- Custom extensions configuration -------------------------------------------
|
# -- External docs configuration ----------------------------------------------
|
||||||
|
|
||||||
|
intersphinx_mapping = {
|
||||||
|
'doctools': ('https://analogdevicesinc.github.io/doctools', None)
|
||||||
|
}
|
||||||
|
|
||||||
|
# -- Custom extensions configuration ------------------------------------------
|
||||||
|
|
||||||
hide_collapsible_content = True
|
hide_collapsible_content = True
|
||||||
validate_links = False
|
validate_links = False
|
||||||
|
|
@ -39,8 +39,7 @@ todo_emit_warnings = True
|
||||||
|
|
||||||
# -- Options for HTML output --------------------------------------------------
|
# -- Options for HTML output --------------------------------------------------
|
||||||
|
|
||||||
html_theme = 'furo'
|
html_theme = 'cosmic'
|
||||||
html_static_path = ['sources']
|
html_static_path = ['sources']
|
||||||
source_suffix = '.rst'
|
|
||||||
html_css_files = ["custom.css"]
|
html_css_files = ["custom.css"]
|
||||||
html_favicon = "sources/icon.svg"
|
html_favicon = "sources/icon.svg"
|
||||||
|
|
|
||||||
|
|
@ -1,994 +0,0 @@
|
||||||
###############################################################################
|
|
||||||
## Copyright (C) 2022-2023 Analog Devices, Inc. All rights reserved.
|
|
||||||
### SPDX short identifier: ADIBSD
|
|
||||||
###############################################################################
|
|
||||||
|
|
||||||
import os.path
|
|
||||||
import contextlib
|
|
||||||
import re
|
|
||||||
from docutils import nodes
|
|
||||||
from docutils.statemachine import ViewList
|
|
||||||
from docutils.parsers.rst import Directive, directives
|
|
||||||
from sphinx.util.nodes import nested_parse_with_titles
|
|
||||||
from sphinx.util import logging
|
|
||||||
from lxml import etree
|
|
||||||
from adi_hdl_static import hdl_strings
|
|
||||||
from adi_hdl_render import hdl_component
|
|
||||||
from uuid import uuid4
|
|
||||||
from hashlib import sha1
|
|
||||||
|
|
||||||
logger = logging.getLogger(__name__)
|
|
||||||
|
|
||||||
dft_hide_collapsible_content = True
|
|
||||||
|
|
||||||
class node_base(nodes.Element, nodes.General):
|
|
||||||
"""
|
|
||||||
Adapted from
|
|
||||||
https://github.com/pradyunsg/sphinx-inline-tabs
|
|
||||||
https://github.com/dgarcia360/sphinx-collapse
|
|
||||||
"""
|
|
||||||
|
|
||||||
@staticmethod
|
|
||||||
def visit(translator, node):
|
|
||||||
attributes = node.attributes.copy()
|
|
||||||
|
|
||||||
attributes.pop("ids")
|
|
||||||
attributes.pop("classes")
|
|
||||||
attributes.pop("names")
|
|
||||||
attributes.pop("dupnames")
|
|
||||||
attributes.pop("backrefs")
|
|
||||||
|
|
||||||
text = translator.starttag(node, node.tagname, **attributes)
|
|
||||||
translator.body.append(text.strip())
|
|
||||||
|
|
||||||
@staticmethod
|
|
||||||
def depart(translator, node):
|
|
||||||
if node.endtag:
|
|
||||||
translator.body.append(f"</{node.tagname}>")
|
|
||||||
|
|
||||||
@staticmethod
|
|
||||||
def default(translator, node):
|
|
||||||
pass
|
|
||||||
|
|
||||||
class node_div(node_base):
|
|
||||||
tagname = 'div'
|
|
||||||
endtag = 'true'
|
|
||||||
|
|
||||||
class node_input(node_base):
|
|
||||||
tagname = 'input'
|
|
||||||
endtag = 'false'
|
|
||||||
|
|
||||||
class node_label(node_base):
|
|
||||||
tagname = 'label'
|
|
||||||
endtag = 'true'
|
|
||||||
|
|
||||||
class node_icon(node_base):
|
|
||||||
tagname = 'div'
|
|
||||||
endtag = 'false'
|
|
||||||
|
|
||||||
def dot_fix(string):
|
|
||||||
if (string.rfind('.') != len(string)-1):
|
|
||||||
return string + '.'
|
|
||||||
else:
|
|
||||||
return string
|
|
||||||
|
|
||||||
def pretty_dep(string):
|
|
||||||
if string is None:
|
|
||||||
return ''
|
|
||||||
return string.replace("'MODELPARAM_VALUE.",'').replace("'",'')
|
|
||||||
|
|
||||||
class directive_base(Directive):
|
|
||||||
has_content = True
|
|
||||||
add_index = True
|
|
||||||
current_doc = ''
|
|
||||||
final_argument_whitespace = True
|
|
||||||
|
|
||||||
@staticmethod
|
|
||||||
def get_descriptions(content):
|
|
||||||
items = {}
|
|
||||||
key = ''
|
|
||||||
for line in content:
|
|
||||||
if line.startswith('* -'):
|
|
||||||
key = line[line.find('* -')+3:].split()[0]
|
|
||||||
items[key] = []
|
|
||||||
else:
|
|
||||||
items[key].append(line)
|
|
||||||
for key in items:
|
|
||||||
items[key] = ' '.join(items[key]).replace('-', '', 1).strip()
|
|
||||||
return items
|
|
||||||
|
|
||||||
def column_entry(self, row, text, node_type, classes=[]):
|
|
||||||
entry = nodes.entry(classes=classes)
|
|
||||||
if node_type == 'literal':
|
|
||||||
entry += nodes.literal(text=text)
|
|
||||||
elif node_type == 'paragraph':
|
|
||||||
entry += nodes.paragraph(text=text)
|
|
||||||
elif node_type == 'reST':
|
|
||||||
rst = ViewList()
|
|
||||||
rst.append(text, f"virtual_{str(uuid4())}", 0)
|
|
||||||
node = nodes.section()
|
|
||||||
node.document = self.state.document
|
|
||||||
nested_parse_with_titles(self.state, rst, node)
|
|
||||||
entry += node
|
|
||||||
elif node_type == 'default_value':
|
|
||||||
if text[0:2] != '0x':
|
|
||||||
rst = ViewList()
|
|
||||||
rst.append(text, f"virtual_{str(uuid4())}", 0)
|
|
||||||
node = nodes.section()
|
|
||||||
node.document = self.state.document
|
|
||||||
nested_parse_with_titles(self.state, rst, node)
|
|
||||||
entry += node
|
|
||||||
else:
|
|
||||||
entry += nodes.literal(text=text)
|
|
||||||
else:
|
|
||||||
return
|
|
||||||
row += entry
|
|
||||||
|
|
||||||
def column_entries(self, rows, items):
|
|
||||||
row = nodes.row()
|
|
||||||
for item in items:
|
|
||||||
if len(item) == 3:
|
|
||||||
self.column_entry(row, item[0], item[1], classes=item[2])
|
|
||||||
else:
|
|
||||||
self.column_entry(row, item[0], item[1])
|
|
||||||
rows.append(row)
|
|
||||||
|
|
||||||
def generic_table(self, description):
|
|
||||||
tgroup = nodes.tgroup(cols=2)
|
|
||||||
for _ in range(2):
|
|
||||||
colspec = nodes.colspec(colwidth=1)
|
|
||||||
tgroup.append(colspec)
|
|
||||||
table = nodes.table()
|
|
||||||
table += tgroup
|
|
||||||
|
|
||||||
self.table_header(tgroup, ["Name", "Description"])
|
|
||||||
|
|
||||||
rows = []
|
|
||||||
for key in description:
|
|
||||||
row = nodes.row()
|
|
||||||
entry = nodes.entry()
|
|
||||||
entry += nodes.literal(text="{:s}".format(key))
|
|
||||||
row += entry
|
|
||||||
entry = nodes.entry()
|
|
||||||
rst = ViewList()
|
|
||||||
rst.append(description[key], f"virtual_{str(uuid4())}", 0)
|
|
||||||
node = nodes.section()
|
|
||||||
node.document = self.state.document
|
|
||||||
nested_parse_with_titles(self.state, rst, node)
|
|
||||||
entry += node
|
|
||||||
row += entry
|
|
||||||
rows.append(row)
|
|
||||||
|
|
||||||
tbody = nodes.tbody()
|
|
||||||
tbody.extend(rows)
|
|
||||||
tgroup += tbody
|
|
||||||
|
|
||||||
return table
|
|
||||||
|
|
||||||
@staticmethod
|
|
||||||
def table_header(tgroup, columns):
|
|
||||||
thead = nodes.thead()
|
|
||||||
tgroup += thead
|
|
||||||
row = nodes.row()
|
|
||||||
|
|
||||||
for header_name in columns:
|
|
||||||
entry = nodes.entry()
|
|
||||||
entry += nodes.paragraph(text=header_name)
|
|
||||||
row += entry
|
|
||||||
|
|
||||||
thead.append(row)
|
|
||||||
|
|
||||||
def collapsible(self, section, text=""):
|
|
||||||
env = self.state.document.settings.env
|
|
||||||
|
|
||||||
_id = sha1(text.encode('utf-8')).hexdigest()
|
|
||||||
container = nodes.container(
|
|
||||||
"",
|
|
||||||
is_div=True,
|
|
||||||
classes=['collapsible']
|
|
||||||
)
|
|
||||||
checked = {"checked": ''} if not env.config.hide_collapsible_content else {}
|
|
||||||
input_ = node_input(
|
|
||||||
type="checkbox",
|
|
||||||
**checked,
|
|
||||||
ids=[_id],
|
|
||||||
name=_id,
|
|
||||||
classes=['collapsible_input']
|
|
||||||
)
|
|
||||||
label = node_label(
|
|
||||||
**{"for": _id}
|
|
||||||
)
|
|
||||||
icon = node_icon(
|
|
||||||
classes=['icon']
|
|
||||||
)
|
|
||||||
content = nodes.container(
|
|
||||||
"",
|
|
||||||
is_div=True,
|
|
||||||
classes=['collapsible_content']
|
|
||||||
)
|
|
||||||
label += nodes.paragraph(text=text)
|
|
||||||
label += icon
|
|
||||||
|
|
||||||
container += input_
|
|
||||||
container += label
|
|
||||||
container += content
|
|
||||||
|
|
||||||
section += container
|
|
||||||
|
|
||||||
return (content, label)
|
|
||||||
|
|
||||||
class directive_collapsible(directive_base):
|
|
||||||
option_spec = {'path': directives.unchanged}
|
|
||||||
required_arguments = 1
|
|
||||||
optional_arguments = 0
|
|
||||||
|
|
||||||
def run(self):
|
|
||||||
self.assert_has_content()
|
|
||||||
|
|
||||||
env = self.state.document.settings.env
|
|
||||||
self.current_doc = env.doc2path(env.docname)
|
|
||||||
|
|
||||||
node = node_div()
|
|
||||||
|
|
||||||
content, _ = self.collapsible(node, self.arguments[0].strip())
|
|
||||||
self.state.nested_parse(self.content, self.content_offset, content)
|
|
||||||
|
|
||||||
return [ node ]
|
|
||||||
|
|
||||||
class directive_interfaces(directive_base):
|
|
||||||
option_spec = {'path': directives.unchanged}
|
|
||||||
required_arguments = 0
|
|
||||||
optional_arguments = 0
|
|
||||||
|
|
||||||
def tables(self, subnode, content, component):
|
|
||||||
description = self.get_descriptions(content)
|
|
||||||
|
|
||||||
if component is None:
|
|
||||||
return self.generic_table(description)
|
|
||||||
|
|
||||||
bs = component['bus_interface']
|
|
||||||
for tag in bs:
|
|
||||||
section = nodes.section(
|
|
||||||
ids=[f"bus-interface-{tag}"]
|
|
||||||
)
|
|
||||||
title = nodes.title(text=tag)
|
|
||||||
section += title
|
|
||||||
|
|
||||||
if bs[tag]['dependency'] is not None:
|
|
||||||
section += [nodes.inline(text="Enabled if "),
|
|
||||||
nodes.literal(text=pretty_dep(bs[tag]['dependency'])),
|
|
||||||
nodes.inline(text=".")]
|
|
||||||
if tag in description:
|
|
||||||
rst = ViewList()
|
|
||||||
rst.append(description[tag], f"virtual_{str(uuid4())}", 0)
|
|
||||||
node = nodes.section()
|
|
||||||
node.document = self.state.document
|
|
||||||
nested_parse_with_titles(self.state, rst, node)
|
|
||||||
section += node
|
|
||||||
|
|
||||||
content, _ = self.collapsible(section, f"Ports of {tag} bus.")
|
|
||||||
|
|
||||||
tgroup = nodes.tgroup(cols=3)
|
|
||||||
for _ in range(3):
|
|
||||||
colspec = nodes.colspec(colwidth=1)
|
|
||||||
tgroup.append(colspec)
|
|
||||||
table = nodes.table()
|
|
||||||
table += tgroup
|
|
||||||
|
|
||||||
self.table_header(tgroup, ["Physical Port", "Logical Port", "Direction"])
|
|
||||||
|
|
||||||
rows = []
|
|
||||||
pm = bs[tag]['port_map']
|
|
||||||
for key in pm:
|
|
||||||
self.column_entries(rows, [
|
|
||||||
[key, 'literal'],
|
|
||||||
[pm[key]['logical_port'], 'literal'],
|
|
||||||
[pm[key]['direction'], 'paragraph'],
|
|
||||||
])
|
|
||||||
|
|
||||||
tbody = nodes.tbody()
|
|
||||||
tbody.extend(rows)
|
|
||||||
tgroup += tbody
|
|
||||||
content += table
|
|
||||||
|
|
||||||
subnode += section
|
|
||||||
|
|
||||||
section = nodes.section(ids=[f"ports"])
|
|
||||||
title = nodes.title(text="Ports")
|
|
||||||
section += title
|
|
||||||
content, _ = self.collapsible(section, f"Ports table.")
|
|
||||||
|
|
||||||
tgroup = nodes.tgroup(cols=4)
|
|
||||||
for _ in range(4):
|
|
||||||
colspec = nodes.colspec(colwidth=1)
|
|
||||||
tgroup.append(colspec)
|
|
||||||
table = nodes.table()
|
|
||||||
table += tgroup
|
|
||||||
|
|
||||||
self.table_header(tgroup, ["Physical Port", "Direction", "Dependency", "Description"])
|
|
||||||
|
|
||||||
rows = []
|
|
||||||
pr = component['ports']
|
|
||||||
dm = component['bus_domain']
|
|
||||||
for key in pr:
|
|
||||||
row = nodes.row()
|
|
||||||
self.column_entry(row, key, 'literal')
|
|
||||||
self.column_entry(row, pr[key]['direction'], 'paragraph')
|
|
||||||
self.column_entry(row, pretty_dep(pr[key]['dependency']), 'paragraph')
|
|
||||||
if 'clk' in key or 'clock' in key:
|
|
||||||
domain = 'clock domain'
|
|
||||||
elif 'reset':
|
|
||||||
domain = 'reset signal'
|
|
||||||
else:
|
|
||||||
domain = 'domain'
|
|
||||||
if key in dm:
|
|
||||||
bus = 'Buses' if len(dm[key]) > 1 else 'Bus'
|
|
||||||
plr = 'are' if len(dm[key]) > 1 else 'is'
|
|
||||||
in_domain = f"{bus} ``{'``, ``'.join(dm[key])}`` {plr} synchronous to this {domain}."
|
|
||||||
else:
|
|
||||||
in_domain = ""
|
|
||||||
if key in description:
|
|
||||||
self.column_entry(row, " ".join([description[key], in_domain]), 'reST', classes=['description'])
|
|
||||||
else:
|
|
||||||
self.column_entry(row, in_domain, 'reST', classes=['description'])
|
|
||||||
rows.append(row)
|
|
||||||
|
|
||||||
tbody = nodes.tbody()
|
|
||||||
tbody.extend(rows)
|
|
||||||
tgroup += tbody
|
|
||||||
content += table
|
|
||||||
|
|
||||||
subnode += section
|
|
||||||
|
|
||||||
for tag in description:
|
|
||||||
if tag not in bs and tag not in pr:
|
|
||||||
logger.warning(f"Signal {tag} defined in the directive does not exist in the IP-XACT (component.xml)!")
|
|
||||||
|
|
||||||
return subnode
|
|
||||||
|
|
||||||
def run(self):
|
|
||||||
env = self.state.document.settings.env
|
|
||||||
self.current_doc = env.doc2path(env.docname)
|
|
||||||
|
|
||||||
node = node_div()
|
|
||||||
|
|
||||||
if 'path' in self.options:
|
|
||||||
lib_name = self.options['path']
|
|
||||||
else:
|
|
||||||
lib_name = env.docname.replace('/index', '')
|
|
||||||
|
|
||||||
if lib_name in env.component:
|
|
||||||
self.tables(node, self.content, env.component[lib_name])
|
|
||||||
else:
|
|
||||||
self.tables(node, self.content, None)
|
|
||||||
|
|
||||||
return [ node ]
|
|
||||||
|
|
||||||
class directive_regmap(directive_base):
|
|
||||||
option_spec = {'name': directives.unchanged, 'no-type-info': directives.unchanged}
|
|
||||||
required_arguments = 0
|
|
||||||
optional_arguments = 0
|
|
||||||
|
|
||||||
def tables(self, subnode, obj):
|
|
||||||
section = nodes.section(ids=[f"register-map-{obj['title']}"])
|
|
||||||
title = nodes.title(text=f"{obj['title']} ({obj['title']})")
|
|
||||||
|
|
||||||
section += title
|
|
||||||
content, _ = self.collapsible(section, f"Register map table.")
|
|
||||||
tgroup = nodes.tgroup(cols=7)
|
|
||||||
for _ in range(7):
|
|
||||||
colspec = nodes.colspec(colwidth=1)
|
|
||||||
tgroup.append(colspec)
|
|
||||||
table = nodes.table(classes=['regmap'])
|
|
||||||
table += tgroup
|
|
||||||
|
|
||||||
self.table_header(tgroup, ["DWORD", "BYTE", "BITS", "Name", "Type", "Default Value", "Description"])
|
|
||||||
|
|
||||||
rows = []
|
|
||||||
for reg in obj['regmap']:
|
|
||||||
self.column_entries(rows, [
|
|
||||||
[reg['address'][0], 'literal'],
|
|
||||||
[reg['address'][1], 'literal'],
|
|
||||||
['', 'literal'],
|
|
||||||
[reg['name'], 'literal'],
|
|
||||||
['', 'literal'],
|
|
||||||
['', 'literal'],
|
|
||||||
[reg['description'], 'reST', ['description']],
|
|
||||||
])
|
|
||||||
|
|
||||||
for field in reg['fields']:
|
|
||||||
self.column_entries(rows, [
|
|
||||||
['', 'literal'],
|
|
||||||
['', 'literal'],
|
|
||||||
[f"[{field['bits']}]", 'literal'],
|
|
||||||
[field['name'], 'literal'],
|
|
||||||
[field['rw'], 'literal'],
|
|
||||||
[field['default'], 'default_value', ['default']],
|
|
||||||
[field['description'], 'reST', ['description']],
|
|
||||||
])
|
|
||||||
|
|
||||||
tbody = nodes.tbody()
|
|
||||||
tbody.extend(rows)
|
|
||||||
tgroup += tbody
|
|
||||||
content += table
|
|
||||||
|
|
||||||
subnode += section
|
|
||||||
|
|
||||||
if 'no-type-info' in self.options:
|
|
||||||
return subnode
|
|
||||||
|
|
||||||
tgroup = nodes.tgroup(cols=3)
|
|
||||||
for _ in range(3):
|
|
||||||
colspec = nodes.colspec(colwidth=1)
|
|
||||||
tgroup.append(colspec)
|
|
||||||
table = nodes.table()
|
|
||||||
table += tgroup
|
|
||||||
|
|
||||||
self.table_header(tgroup, ["Access Type", "Name", "Description"])
|
|
||||||
|
|
||||||
rows = []
|
|
||||||
for at in obj['access_type']:
|
|
||||||
self.column_entries(rows, [
|
|
||||||
[at, 'paragraph'],
|
|
||||||
[hdl_strings.access_type[at]['name'], 'paragraph'],
|
|
||||||
[hdl_strings.access_type[at]['description'], 'paragraph']
|
|
||||||
])
|
|
||||||
|
|
||||||
tbody = nodes.tbody()
|
|
||||||
tbody.extend(rows)
|
|
||||||
tgroup += tbody
|
|
||||||
section += table
|
|
||||||
|
|
||||||
return subnode
|
|
||||||
|
|
||||||
def run(self):
|
|
||||||
env = self.state.document.settings.env
|
|
||||||
self.current_doc = env.doc2path(env.docname)
|
|
||||||
if os.getcwd() not in self.current_doc:
|
|
||||||
raise Exception(f"Inconsistent paths, {os.getcwd()} not in {self.current_doc}")
|
|
||||||
owner = self.current_doc[len(os.getcwd())+1:-4]
|
|
||||||
|
|
||||||
node = node_div()
|
|
||||||
|
|
||||||
if 'name' in self.options:
|
|
||||||
lib_name = self.options['name']
|
|
||||||
else:
|
|
||||||
logger.warning("hdl-regmap directive without name option, skipped!")
|
|
||||||
return [ node ]
|
|
||||||
|
|
||||||
subnode = nodes.section(ids=["hdl-regmap"])
|
|
||||||
|
|
||||||
# Have to search all because it is allowed to have more than one regmap per file...
|
|
||||||
file = None
|
|
||||||
for f in env.regmaps:
|
|
||||||
if lib_name in env.regmaps[f]['subregmap']:
|
|
||||||
file = f
|
|
||||||
break
|
|
||||||
|
|
||||||
if file is None:
|
|
||||||
logger.warning(f"Title tool {lib_name} not-found in any regmap file, skipped!")
|
|
||||||
return [ node ]
|
|
||||||
|
|
||||||
if owner not in env.regmaps[f]['owners']:
|
|
||||||
env.regmaps[f]['owners'].append(owner)
|
|
||||||
self.tables(subnode, env.regmaps[f]['subregmap'][lib_name])
|
|
||||||
|
|
||||||
node += subnode
|
|
||||||
return [ node ]
|
|
||||||
|
|
||||||
class directive_parameters(directive_base):
|
|
||||||
option_spec = {'path': directives.unchanged}
|
|
||||||
required_arguments = 0
|
|
||||||
optional_arguments = 0
|
|
||||||
|
|
||||||
def tables(self, content, parameter):
|
|
||||||
description = self.get_descriptions(content)
|
|
||||||
|
|
||||||
if parameter is None:
|
|
||||||
return self.generic_table(description)
|
|
||||||
|
|
||||||
tgroup = nodes.tgroup(cols=5)
|
|
||||||
for _ in range(5):
|
|
||||||
colspec = nodes.colspec(colwidth=1)
|
|
||||||
tgroup.append(colspec)
|
|
||||||
table = nodes.table()
|
|
||||||
table += tgroup
|
|
||||||
|
|
||||||
self.table_header(tgroup, ["Name", "Description", "Data Type", "Default Value", "Choices/Range"])
|
|
||||||
|
|
||||||
rows = []
|
|
||||||
for key in parameter:
|
|
||||||
row = nodes.row()
|
|
||||||
self.column_entry(row, "{:s}".format(key), 'literal')
|
|
||||||
if key in description:
|
|
||||||
self.column_entry(row, description[key], 'reST', classes=['description'])
|
|
||||||
else:
|
|
||||||
self.column_entry(row, dot_fix(parameter[key]['description']), 'paragraph', classes=['description'])
|
|
||||||
for tag, ty in zip(['type', 'default'], ['paragraph', 'literal']):
|
|
||||||
if parameter[key][tag] is not None:
|
|
||||||
self.column_entry(row, parameter[key][tag], ty, classes=[tag])
|
|
||||||
else:
|
|
||||||
logger.warning(f"Got empty {tag} at parameter {key}!")
|
|
||||||
self.column_entry(row, "", 'paragraph')
|
|
||||||
crange = []
|
|
||||||
for tag in ['choices', 'range']:
|
|
||||||
if parameter[key][tag] is not None:
|
|
||||||
crange.append(parameter[key][tag])
|
|
||||||
crange = '. '.join(crange)
|
|
||||||
self.column_entry(row, crange, 'paragraph')
|
|
||||||
|
|
||||||
rows.append(row)
|
|
||||||
|
|
||||||
tbody = nodes.tbody()
|
|
||||||
tbody.extend(rows)
|
|
||||||
tgroup += tbody
|
|
||||||
|
|
||||||
for tag in description:
|
|
||||||
if tag not in parameter:
|
|
||||||
logger.warning(f"{tag} defined in the directive does not exist in the IP-XACT (component.xml)!")
|
|
||||||
|
|
||||||
return table
|
|
||||||
|
|
||||||
def run(self):
|
|
||||||
env = self.state.document.settings.env
|
|
||||||
self.current_doc = env.doc2path(env.docname)
|
|
||||||
|
|
||||||
node = node_div()
|
|
||||||
|
|
||||||
if 'path' not in self.options:
|
|
||||||
self.options['path'] = env.docname.replace('/index', '')
|
|
||||||
lib_name = self.options['path']
|
|
||||||
|
|
||||||
subnode = nodes.section(ids=["hdl-parameters"])
|
|
||||||
if lib_name in env.component:
|
|
||||||
subnode += self.tables(self.content, env.component[lib_name]['parameters'])
|
|
||||||
else:
|
|
||||||
subnode += self.tables(self.content, None)
|
|
||||||
|
|
||||||
node += subnode
|
|
||||||
|
|
||||||
return [ node ]
|
|
||||||
|
|
||||||
class directive_component_diagram(directive_base):
|
|
||||||
option_spec = {'path': directives.unchanged}
|
|
||||||
required_arguments = 0
|
|
||||||
optional_arguments = 0
|
|
||||||
|
|
||||||
def missing_diagram(self):
|
|
||||||
svg_raw = hdl_component.render_placeholder(self.options['path'])
|
|
||||||
|
|
||||||
svg = nodes.raw('', svg_raw, format='html')
|
|
||||||
return [ svg ]
|
|
||||||
|
|
||||||
def diagram(self):
|
|
||||||
name = hdl_component.get_name(self.options['path'])
|
|
||||||
path = '_build/managed'
|
|
||||||
f = open(os.path.join(path, name))
|
|
||||||
svg_raw = f.read()
|
|
||||||
|
|
||||||
svg = nodes.raw('', svg_raw, format='html')
|
|
||||||
return [ svg ]
|
|
||||||
|
|
||||||
def run(self):
|
|
||||||
env = self.state.document.settings.env
|
|
||||||
self.current_doc = env.doc2path(env.docname)
|
|
||||||
|
|
||||||
node = node_div()
|
|
||||||
|
|
||||||
if 'path' not in self.options:
|
|
||||||
self.options['path'] = env.docname.replace('/index', '')
|
|
||||||
lib_name = self.options['path']
|
|
||||||
|
|
||||||
subnode = nodes.section(ids=["hdl-component-diagram"])
|
|
||||||
if lib_name in env.component:
|
|
||||||
subnode += self.diagram()
|
|
||||||
else:
|
|
||||||
subnode += self.missing_diagram()
|
|
||||||
|
|
||||||
node += subnode
|
|
||||||
|
|
||||||
return [ node ]
|
|
||||||
|
|
||||||
|
|
||||||
def parse_hdl_component(path, ctime):
|
|
||||||
component = {
|
|
||||||
'bus_interface':{},
|
|
||||||
'bus_domain':{},
|
|
||||||
'ports': {},
|
|
||||||
'parameters': {},
|
|
||||||
'ctime': ctime
|
|
||||||
}
|
|
||||||
|
|
||||||
def get_namespaces(item):
|
|
||||||
nsmap = item.nsmap
|
|
||||||
for i in ['spirit', 'xilinx', 'xsi']:
|
|
||||||
if i not in nsmap:
|
|
||||||
raise Exception(f"Required namespace {i} not in file!")
|
|
||||||
|
|
||||||
return (nsmap['spirit'], nsmap['xilinx'], nsmap['xsi'])
|
|
||||||
|
|
||||||
def get(item, local_name):
|
|
||||||
items = get_all(item, local_name)
|
|
||||||
if len(items) == 0:
|
|
||||||
return None
|
|
||||||
else:
|
|
||||||
return items[0]
|
|
||||||
|
|
||||||
def get_all(item, local_name):
|
|
||||||
template = "/*[local-name()='%s']"
|
|
||||||
if not isinstance(local_name, str):
|
|
||||||
raise Exception("Got wrong type, only Strings are allowed")
|
|
||||||
local_name = local_name.split('/')
|
|
||||||
return item.xpath('.' + ''.join([template % ln for ln in local_name]))
|
|
||||||
|
|
||||||
def sattrib(item, attr):
|
|
||||||
nonlocal spirit
|
|
||||||
return item.get(f"{{{spirit}}}{attr}")
|
|
||||||
|
|
||||||
def xattrib(item, attr):
|
|
||||||
nonlocal xilinx
|
|
||||||
return item.get(f"{{{xilinx}}}{attr}")
|
|
||||||
|
|
||||||
def stag(item):
|
|
||||||
nonlocal spirit
|
|
||||||
return item.tag.replace(f"{{{spirit}}}",'')
|
|
||||||
|
|
||||||
def xtag(item):
|
|
||||||
nonlocal xilinx
|
|
||||||
return item.tag.replace(f"{{{xilinx}}}",'')
|
|
||||||
|
|
||||||
def clean_dependency(string):
|
|
||||||
return string[string.find("'"): string.rfind(')')].replace(')','')
|
|
||||||
|
|
||||||
def get_dependency(item, type_=None):
|
|
||||||
if type_ is None:
|
|
||||||
type_ = stag(item)
|
|
||||||
|
|
||||||
dependency = get(item, f"vendorExtensions/{type_}Info/enablement/isEnabled")
|
|
||||||
if dependency is None:
|
|
||||||
return None
|
|
||||||
else:
|
|
||||||
return clean_dependency(xattrib(dependency, 'dependency'))
|
|
||||||
|
|
||||||
def get_range(item):
|
|
||||||
min_ = sattrib(item, 'minimum')
|
|
||||||
max_ = sattrib(item, 'maximum')
|
|
||||||
if max_ == None or min_ == None:
|
|
||||||
return None
|
|
||||||
else:
|
|
||||||
return f"From {min_} to {max_}."
|
|
||||||
|
|
||||||
def get_choice_type(name):
|
|
||||||
return name[name.find('_')+1:name.rfind('_')]
|
|
||||||
|
|
||||||
def format_default_value(value, fmt):
|
|
||||||
if fmt == "bitString" and value[0:2].lower() == "0x":
|
|
||||||
return f"'h{value[2:].upper()}"
|
|
||||||
if fmt == "bitString" and value[0] == '"' and value[-1] == '"':
|
|
||||||
return f"'b{value[1:-1]}"
|
|
||||||
if fmt == "bool":
|
|
||||||
return value.title()
|
|
||||||
return value
|
|
||||||
|
|
||||||
root = etree.parse(path).getroot()
|
|
||||||
spirit, xilinx, _ = get_namespaces(root)
|
|
||||||
vendor = get(root, 'vendor').text
|
|
||||||
name = get(root, 'name').text
|
|
||||||
|
|
||||||
bs = component['bus_interface']
|
|
||||||
dm = component['bus_domain']
|
|
||||||
for bus_interface in get_all(root, 'busInterfaces/busInterface'):
|
|
||||||
bus_name = get(bus_interface, 'name').text
|
|
||||||
if '_signal_clock' in bus_name:
|
|
||||||
signal_name = get(get(bus_interface, 'portMaps/portMap'), 'physicalPort/name').text
|
|
||||||
if signal_name not in dm:
|
|
||||||
dm[signal_name] = []
|
|
||||||
dm[signal_name].append(bus_name[0:bus_name.find('_signal_clock')])
|
|
||||||
continue
|
|
||||||
if '_signal_reset' in bus_name:
|
|
||||||
signal_name = get(get(bus_interface, 'portMaps/portMap'), 'physicalPort/name').text
|
|
||||||
if signal_name not in dm:
|
|
||||||
dm[signal_name] = []
|
|
||||||
dm[signal_name].append(bus_name[0:bus_name.find('_signal_reset')])
|
|
||||||
continue
|
|
||||||
|
|
||||||
if get(bus_interface, 'slave') is not None:
|
|
||||||
bus_role = 'slave'
|
|
||||||
elif get(bus_interface, 'master') is not None:
|
|
||||||
bus_role = 'master'
|
|
||||||
else:
|
|
||||||
bus_role = None
|
|
||||||
|
|
||||||
bs[bus_name] = {
|
|
||||||
'name': sattrib(get(bus_interface, 'busType'), 'name'),
|
|
||||||
'role': bus_role,
|
|
||||||
'dependency': get_dependency(bus_interface, 'busInterface'),
|
|
||||||
'port_map': {}
|
|
||||||
}
|
|
||||||
|
|
||||||
pm = bs[bus_name]['port_map']
|
|
||||||
for port_map in get_all(bus_interface, 'portMaps/portMap'):
|
|
||||||
pm[get(port_map, 'physicalPort/name').text] = {
|
|
||||||
'logical_port': get(port_map, 'logicalPort/name').text,
|
|
||||||
'direction': ''
|
|
||||||
}
|
|
||||||
|
|
||||||
lport = component['ports']
|
|
||||||
for port in get_all(root, 'model/ports/port'):
|
|
||||||
port_name = get(port, 'name').text
|
|
||||||
port_direction = get(port, 'wire/direction').text
|
|
||||||
|
|
||||||
found = False
|
|
||||||
for bus in bs:
|
|
||||||
if port_name in bs[bus]['port_map']:
|
|
||||||
found = True
|
|
||||||
bs[bus]['port_map'][port_name]['direction'] = port_direction
|
|
||||||
break;
|
|
||||||
|
|
||||||
if found == False:
|
|
||||||
lport[port_name] = {
|
|
||||||
'direction': port_direction,
|
|
||||||
'dependency': get_dependency(port, 'port')
|
|
||||||
}
|
|
||||||
pr = component['parameters']
|
|
||||||
for parameter in get_all(root, 'parameters/parameter'):
|
|
||||||
param_description = get(parameter, 'displayName')
|
|
||||||
if param_description is not None:
|
|
||||||
param_name = get(parameter, 'name').text
|
|
||||||
param_value = get(parameter, 'value')
|
|
||||||
param_format = sattrib(param_value, 'format')
|
|
||||||
pr[param_name] = {
|
|
||||||
'description': param_description.text,
|
|
||||||
'default': format_default_value(param_value.text, param_format),
|
|
||||||
'type': param_format,
|
|
||||||
'_choice_ref': sattrib(param_value, 'choiceRef'),
|
|
||||||
'choices': None,
|
|
||||||
'range': get_range(param_value)
|
|
||||||
}
|
|
||||||
|
|
||||||
for parameter in get_all(root, 'model/modelParameters/modelParameter'):
|
|
||||||
param_name = get(parameter, 'name').text
|
|
||||||
param_type = sattrib(parameter, 'dataType')
|
|
||||||
if param_type == "std_logic_vector":
|
|
||||||
param_type = "logic vector"
|
|
||||||
if param_type is not None and param_name in pr:
|
|
||||||
if pr[param_name]['type'] is None:
|
|
||||||
pr[param_name]['type'] = param_type.capitalize()
|
|
||||||
else:
|
|
||||||
param_format = pr[param_name]['type']
|
|
||||||
pr[param_name]['type'] = param_format[0].upper()+param_format[1:]
|
|
||||||
|
|
||||||
for choice in get_all(root, 'choices/choice'):
|
|
||||||
name = get(choice, 'name').text
|
|
||||||
for key in pr:
|
|
||||||
if pr[key]['_choice_ref'] == name:
|
|
||||||
type_ = get_choice_type(name)
|
|
||||||
values = get_all(choice, 'enumeration')
|
|
||||||
string = []
|
|
||||||
if type_ == 'pairs':
|
|
||||||
for v in values:
|
|
||||||
string.append(f"{sattrib(v, 'text')} ({v.text})")
|
|
||||||
elif type_ == 'list':
|
|
||||||
for v in values:
|
|
||||||
string.append(v.text)
|
|
||||||
else:
|
|
||||||
break
|
|
||||||
pr[key]['choices'] = ', '.join(string)
|
|
||||||
break
|
|
||||||
|
|
||||||
return component
|
|
||||||
|
|
||||||
def manage_hdl_components(env, docnames, libraries):
|
|
||||||
if not hasattr(env, 'component'):
|
|
||||||
env.component = {}
|
|
||||||
cp = env.component
|
|
||||||
for lib in list(cp):
|
|
||||||
f = f"../{lib}/component.xml"
|
|
||||||
if not os.path.isfile(f):
|
|
||||||
del cp[lib]
|
|
||||||
|
|
||||||
for lib, doc in libraries:
|
|
||||||
f = f"../{lib}/component.xml"
|
|
||||||
if not os.path.isfile(f):
|
|
||||||
continue
|
|
||||||
ctime = os.path.getctime(f)
|
|
||||||
if lib in cp and cp[lib]['ctime'] >= ctime:
|
|
||||||
pass
|
|
||||||
else:
|
|
||||||
cp[lib] = parse_hdl_component(f, ctime)
|
|
||||||
hdl_component.render(env, lib, cp[lib])
|
|
||||||
docnames.append(doc)
|
|
||||||
|
|
||||||
# From https://github.com/tfcollins/vger/blob/main/vger/hdl_reg_map.py
|
|
||||||
def parse_hdl_regmap(reg, ctime):
|
|
||||||
regmap = {
|
|
||||||
'subregmap': {},
|
|
||||||
'owners':[],
|
|
||||||
'ctime': ctime
|
|
||||||
}
|
|
||||||
|
|
||||||
with open(f"regmap/adi_regmap_{reg}.txt", "r") as f:
|
|
||||||
data = f.readlines()
|
|
||||||
data = [d.replace("\n", "") for d in data]
|
|
||||||
|
|
||||||
while "TITLE" in data:
|
|
||||||
# Get title
|
|
||||||
tit = data.index("TITLE")
|
|
||||||
|
|
||||||
title = str(data[tit + 1].strip())
|
|
||||||
title_tool = str(data[tit + 2].strip())
|
|
||||||
data = data[tit + 2 :]
|
|
||||||
|
|
||||||
if 'ENDTITLE' in [title_tool, title]:
|
|
||||||
logger.warning(f"Malformed title fields at file regmap/adi_regmap_{reg}.txt, skipped!")
|
|
||||||
continue
|
|
||||||
|
|
||||||
regmap['subregmap'][title_tool] = {
|
|
||||||
'title': title,
|
|
||||||
'regmap': [],
|
|
||||||
'access_type': []
|
|
||||||
}
|
|
||||||
|
|
||||||
# Get registers
|
|
||||||
access_type = []
|
|
||||||
while "REG" in data:
|
|
||||||
regi = data.index("REG")
|
|
||||||
rfi = data.index("ENDREG")
|
|
||||||
|
|
||||||
if not regi:
|
|
||||||
break
|
|
||||||
|
|
||||||
reg_addr = data[regi + 1].strip()
|
|
||||||
reg_name = data[regi + 2].strip()
|
|
||||||
reg_desc = [data[fi].strip() for fi in range(regi + 3, rfi)]
|
|
||||||
reg_desc = " ".join(reg_desc)
|
|
||||||
|
|
||||||
with contextlib.suppress(ValueError):
|
|
||||||
if tet := data.index("TITLE"):
|
|
||||||
if regi > tet:
|
|
||||||
# into next regmap
|
|
||||||
break
|
|
||||||
data = data[regi + 1 :]
|
|
||||||
|
|
||||||
# Get fields
|
|
||||||
fields = []
|
|
||||||
while "FIELD" in data:
|
|
||||||
fi = data.index("FIELD")
|
|
||||||
efi = data.index("ENDFIELD")
|
|
||||||
|
|
||||||
if not fi:
|
|
||||||
break
|
|
||||||
|
|
||||||
with contextlib.suppress(ValueError):
|
|
||||||
if rege := data.index("REG"):
|
|
||||||
if fi > rege:
|
|
||||||
# into next register
|
|
||||||
break
|
|
||||||
|
|
||||||
field_loc = data[fi + 1].strip()
|
|
||||||
field_loc = field_loc.split(" ")
|
|
||||||
field_bits = field_loc[0].replace("[", "").replace("]", "")
|
|
||||||
field_default = ' '.join(field_loc[1:]) if len(field_loc) > 1 else "NA"
|
|
||||||
|
|
||||||
field_name = data[fi + 2].strip()
|
|
||||||
field_rw = data[fi + 3].strip()
|
|
||||||
|
|
||||||
if field_rw == 'R':
|
|
||||||
field_rw = 'RO'
|
|
||||||
elif field_rw == 'W':
|
|
||||||
field_rw = 'WO'
|
|
||||||
if '-V' in field_rw:
|
|
||||||
if 'V' not in access_type:
|
|
||||||
access_type.append('V')
|
|
||||||
field_rw_ = field_rw.replace('-V','')
|
|
||||||
if field_rw_ not in access_type:
|
|
||||||
if field_rw_ not in hdl_strings.access_type:
|
|
||||||
logger.warning(f"Malformed access type {field_rw} for register {field_name}, file regmap/adi_regmap_{reg}.txt.")
|
|
||||||
else:
|
|
||||||
access_type.append(field_rw)
|
|
||||||
|
|
||||||
field_desc = [data[fi].strip() for fi in range(fi + 4, efi)]
|
|
||||||
field_desc = " ".join(field_desc)
|
|
||||||
|
|
||||||
# TODO Remove dokuwiki scaping support
|
|
||||||
# Temporary dokuwiki scaping convert to not break current dokuwiki tables
|
|
||||||
field_default = field_default.replace("''", "``")
|
|
||||||
field_desc = field_desc.replace("''", "``")
|
|
||||||
|
|
||||||
fields.append(
|
|
||||||
{
|
|
||||||
"name": field_name,
|
|
||||||
"bits": field_bits,
|
|
||||||
"default": field_default,
|
|
||||||
"rw": field_rw,
|
|
||||||
"description": field_desc,
|
|
||||||
}
|
|
||||||
)
|
|
||||||
|
|
||||||
data = data[fi + 1 :]
|
|
||||||
|
|
||||||
try:
|
|
||||||
if '+' in reg_addr:
|
|
||||||
reg_addr_ = reg_addr.split('+')
|
|
||||||
reg_addr_[0] = int(reg_addr_[0], 16)
|
|
||||||
reg_addr_[1] = int(reg_addr_[1].replace('*n',''), 16)
|
|
||||||
reg_addr_dword = f"{hex(reg_addr_[0])} + {hex(reg_addr_[1])}*n"
|
|
||||||
reg_addr_byte = f"{hex(reg_addr_[0]<<2)} + {hex(reg_addr_[1]<<2)}*n"
|
|
||||||
else:
|
|
||||||
reg_addr_ = int(reg_addr, 16)
|
|
||||||
reg_addr_dword = f"{hex(reg_addr_)}"
|
|
||||||
reg_addr_byte = f"{hex(reg_addr_<<2)}"
|
|
||||||
except:
|
|
||||||
logger.warning(f"Got malformed register address {reg_addr} for register {reg_name}, file regmap/adi_regmap_{reg}.txt.")
|
|
||||||
reg_addr_dword = ""
|
|
||||||
reg_addr_byte = ""
|
|
||||||
|
|
||||||
regmap['subregmap'][title_tool]['regmap'].append(
|
|
||||||
{
|
|
||||||
'name': reg_name,
|
|
||||||
'address': [reg_addr_dword, reg_addr_byte],
|
|
||||||
'description': reg_desc,
|
|
||||||
'fields': fields
|
|
||||||
}
|
|
||||||
)
|
|
||||||
regmap['subregmap'][title_tool]['access_type'] = access_type
|
|
||||||
return regmap
|
|
||||||
|
|
||||||
def manage_hdl_regmaps(env, docnames):
|
|
||||||
if not hasattr(env, 'regmaps'):
|
|
||||||
env.regmaps = {}
|
|
||||||
|
|
||||||
rm = env.regmaps
|
|
||||||
for lib in list(rm):
|
|
||||||
f = f"regmap/adi_regmap_{lib}.txt"
|
|
||||||
if not os.path.isfile(f):
|
|
||||||
del rm[lib]
|
|
||||||
# Inconsistent naming convention, need to parse all in directory.
|
|
||||||
regmaps = []
|
|
||||||
for (dirpath, dirnames, filenames) in os.walk("regmap"):
|
|
||||||
for file in filenames:
|
|
||||||
m = re.search("adi_regmap_(\w+)\.txt", file)
|
|
||||||
if not bool(m):
|
|
||||||
continue
|
|
||||||
|
|
||||||
reg_name = m.group(1)
|
|
||||||
regmaps.extend(reg_name)
|
|
||||||
|
|
||||||
ctime = os.path.getctime(f"regmap/{file}")
|
|
||||||
if reg_name in rm and rm[reg_name]['ctime'] < ctime:
|
|
||||||
for o in rm[reg_name]['owners']:
|
|
||||||
if o not in docnames:
|
|
||||||
docnames.append(o)
|
|
||||||
if reg_name in rm and rm[reg_name]['ctime'] >= ctime:
|
|
||||||
pass
|
|
||||||
else:
|
|
||||||
rm[reg_name] = parse_hdl_regmap(reg_name, ctime)
|
|
||||||
|
|
||||||
def manage_hdl_artifacts(app, env, docnames):
|
|
||||||
libraries = [[k.replace('/index',''), k] for k in env.found_docs if k.find('library/') == 0]
|
|
||||||
|
|
||||||
manage_hdl_components(env, docnames, libraries)
|
|
||||||
manage_hdl_regmaps(env, docnames)
|
|
||||||
|
|
||||||
def setup(app):
|
|
||||||
app.add_directive('collapsible', directive_collapsible)
|
|
||||||
app.add_directive('hdl-parameters', directive_parameters)
|
|
||||||
app.add_directive('hdl-component-diagram', directive_component_diagram)
|
|
||||||
app.add_directive('hdl-interfaces', directive_interfaces)
|
|
||||||
app.add_directive('hdl-regmap', directive_regmap)
|
|
||||||
|
|
||||||
for node in [node_div, node_input, node_label, node_icon]:
|
|
||||||
app.add_node(node,
|
|
||||||
html =(node.visit, node.depart),
|
|
||||||
latex=(node.visit, node.depart),
|
|
||||||
text =(node.visit, node.depart))
|
|
||||||
|
|
||||||
app.connect('env-before-read-docs', manage_hdl_artifacts)
|
|
||||||
|
|
||||||
app.add_config_value('hide_collapsible_content', dft_hide_collapsible_content, 'env')
|
|
||||||
|
|
||||||
return {
|
|
||||||
'version': '0.1',
|
|
||||||
'parallel_read_safe': True,
|
|
||||||
'parallel_write_safe': True,
|
|
||||||
}
|
|
||||||
|
|
@ -1,230 +0,0 @@
|
||||||
import os.path
|
|
||||||
from lxml import etree
|
|
||||||
|
|
||||||
font_size = 16
|
|
||||||
margin = 18
|
|
||||||
line_length = 16
|
|
||||||
text_vertical_margin = 8
|
|
||||||
color_main = '#0067b9'
|
|
||||||
color_bg1 = '#c4e5ff'
|
|
||||||
color_bg2 = '#ebf6ff'
|
|
||||||
stroke_width = 3
|
|
||||||
|
|
||||||
class hdl_component():
|
|
||||||
|
|
||||||
@staticmethod
|
|
||||||
def get_name(lib_name):
|
|
||||||
return f"{lib_name.replace('/','-')}.svg"
|
|
||||||
|
|
||||||
@staticmethod
|
|
||||||
def render(env, lib_name, item):
|
|
||||||
#ports, bus_interface
|
|
||||||
dest_dir = os.path.join(env.srcdir, '_build/managed')
|
|
||||||
dest_file = os.path.join(dest_dir, hdl_component.get_name(lib_name))
|
|
||||||
|
|
||||||
def make_style(parent):
|
|
||||||
style = etree.SubElement(parent, 'style').text = """
|
|
||||||
a {
|
|
||||||
text-decoration: none;
|
|
||||||
}
|
|
||||||
"""
|
|
||||||
def make_gradient(parent):
|
|
||||||
defs = etree.SubElement(parent, 'defs')
|
|
||||||
gradient = etree.SubElement(defs, 'linearGradient', attrib={
|
|
||||||
'id':'ip_background',
|
|
||||||
'x1':'0', 'x2':'1', 'y1':'0', 'y2':'1'
|
|
||||||
})
|
|
||||||
etree.SubElement(gradient, 'stop', attrib={'offset':'0%', 'stop-color':color_bg1})
|
|
||||||
etree.SubElement(gradient, 'stop', attrib={'offset':'100%', 'stop-color':color_bg2})
|
|
||||||
|
|
||||||
def symbol_bus(parent):
|
|
||||||
rect_height = font_size
|
|
||||||
one_fifth_x = line_length/5
|
|
||||||
one_fifth_y = rect_height/5
|
|
||||||
x = 0; y = 0
|
|
||||||
pattern = [[0,1,0,1,0],[0,0,0,0,0],[0,1,0,1,0],[0,0,0,0,0],[0,1,0,1,0]]
|
|
||||||
etree.SubElement(parent, "rect", attrib={
|
|
||||||
'x':'0', 'y':'0',
|
|
||||||
'width':str(line_length), 'height':str(font_size),
|
|
||||||
'fill':color_bg1,
|
|
||||||
})
|
|
||||||
for i in pattern:
|
|
||||||
for j in i:
|
|
||||||
if j:
|
|
||||||
etree.SubElement(parent, "rect", attrib={
|
|
||||||
'x':str(x), 'y':str(y),
|
|
||||||
'width':str(one_fifth_x), 'height':str(one_fifth_y),
|
|
||||||
'fill':color_main,
|
|
||||||
})
|
|
||||||
x = x+one_fifth_x
|
|
||||||
x = 0
|
|
||||||
y = y+one_fifth_y
|
|
||||||
def symbol_port(parent):
|
|
||||||
etree.SubElement(parent, "line", attrib={
|
|
||||||
'stroke':'black',
|
|
||||||
'stroke-width':str(stroke_width),
|
|
||||||
'x1':'0', 'y1':str(font_size/2),
|
|
||||||
'x2':str(line_length), 'y2':str(font_size/2)
|
|
||||||
})
|
|
||||||
|
|
||||||
def create_text(items, side):
|
|
||||||
y_pos = margin*4
|
|
||||||
if side == 'out':
|
|
||||||
text_anchor = 'end'
|
|
||||||
x_pos = margin*4 + aux_width
|
|
||||||
line_x1 = x_pos+(margin)
|
|
||||||
line_x2 = x_pos+(margin+line_length)
|
|
||||||
x_pos_group = x_pos+margin
|
|
||||||
scale_group = 'scale(1,1)'
|
|
||||||
else:
|
|
||||||
text_anchor = 'start'
|
|
||||||
x_pos = margin*3
|
|
||||||
line_x1 = x_pos-(margin+line_length)
|
|
||||||
line_x2 = x_pos-(margin)
|
|
||||||
x_pos_group = x_pos-margin
|
|
||||||
scale_group = 'scale(-1,1)'
|
|
||||||
|
|
||||||
for elem in items:
|
|
||||||
if elem[1] == 'bus':
|
|
||||||
link_anchor = f"#bus-interface-{elem[0]}"
|
|
||||||
else:
|
|
||||||
link_anchor = "#ports"
|
|
||||||
link = etree.SubElement(root, "a", attrib={
|
|
||||||
'href':link_anchor,
|
|
||||||
})
|
|
||||||
etree.SubElement(link, "text", attrib={
|
|
||||||
'style':f"font: {font_size}px sans-serif",
|
|
||||||
'text-anchor':text_anchor,
|
|
||||||
'dominant-baseline':'middle',
|
|
||||||
'x':str(x_pos), 'y':str(y_pos)
|
|
||||||
}).text = elem[0]
|
|
||||||
group = etree.SubElement(root, "g", attrib={
|
|
||||||
'transform':f"translate({x_pos_group},{y_pos-font_size/2}) {scale_group}"}
|
|
||||||
)
|
|
||||||
if elem[1] == 'bus':
|
|
||||||
symbol_bus(group)
|
|
||||||
else:
|
|
||||||
symbol_port(group)
|
|
||||||
y_pos += font_size+text_vertical_margin
|
|
||||||
|
|
||||||
ins = []
|
|
||||||
outs = []
|
|
||||||
for key in item['bus_interface']:
|
|
||||||
if item['bus_interface'][key]['role'] == 'master':
|
|
||||||
outs.append((key, 'bus'))
|
|
||||||
else:
|
|
||||||
ins.append((key, 'bus'))
|
|
||||||
for key in item['ports']:
|
|
||||||
if item['ports'][key]['direction'] == 'out':
|
|
||||||
outs.append((key, 'port'))
|
|
||||||
else:
|
|
||||||
ins.append((key, 'port'))
|
|
||||||
|
|
||||||
max_len_in = 0
|
|
||||||
for elem in ins:
|
|
||||||
max_len_in = len(elem[0]) if len(elem[0]) > max_len_in else max_len_in
|
|
||||||
|
|
||||||
max_len_out = 0
|
|
||||||
for elem in outs:
|
|
||||||
max_len_out = len(elem[0]) if len(elem[0]) > max_len_out else max_len_out
|
|
||||||
|
|
||||||
aux_width = (max_len_in+max_len_out)*font_size*.6
|
|
||||||
|
|
||||||
num_outs = len(outs)
|
|
||||||
num_ins = len(ins)
|
|
||||||
max_num = max(num_outs, num_ins)
|
|
||||||
|
|
||||||
root = etree.Element('svg', xmlns="http://www.w3.org/2000/svg")
|
|
||||||
|
|
||||||
make_style(root)
|
|
||||||
make_gradient(root)
|
|
||||||
|
|
||||||
ip_width = aux_width + margin*3
|
|
||||||
ip_height = max_num*(font_size+text_vertical_margin) + margin*2
|
|
||||||
etree.SubElement(root, "rect", attrib={
|
|
||||||
'x':str(margin*2), 'y':str(margin*2),
|
|
||||||
'width':str(ip_width), 'height':str(ip_height),
|
|
||||||
'rx':str(margin),
|
|
||||||
'fill':'url(#ip_background)'
|
|
||||||
})
|
|
||||||
|
|
||||||
create_text(ins,'in')
|
|
||||||
create_text(outs,'out')
|
|
||||||
|
|
||||||
viewbox_x = margin*7 + aux_width
|
|
||||||
viewbox_y = margin*7 + max_num*(font_size+text_vertical_margin)
|
|
||||||
root.set('viewBox', f"0 0 {viewbox_x} {viewbox_y}")
|
|
||||||
root.set('width', str(viewbox_x))
|
|
||||||
root.set('height', str(viewbox_y))
|
|
||||||
|
|
||||||
etree.SubElement(root, "rect", attrib={
|
|
||||||
'x':str(margin*2), 'y':str(margin*2),
|
|
||||||
'width':str(ip_width), 'height':str(ip_height),
|
|
||||||
'rx':str(margin),
|
|
||||||
'fill':'none',
|
|
||||||
'stroke':color_main,
|
|
||||||
'stroke-width':str(stroke_width)
|
|
||||||
})
|
|
||||||
|
|
||||||
ipname_y = viewbox_y-font_size-margin
|
|
||||||
ipname_x = viewbox_x/2
|
|
||||||
etree.SubElement(root, "text", attrib={
|
|
||||||
'style':f"font: {font_size}px sans-serif",
|
|
||||||
'fill': color_main,
|
|
||||||
'text-anchor':'middle',
|
|
||||||
'dominant-baseline':'middle',
|
|
||||||
'x':str(ipname_x), 'y':str(ipname_y)
|
|
||||||
}).text = lib_name[lib_name.rfind('/')+1:]
|
|
||||||
|
|
||||||
tree = etree.ElementTree(root)
|
|
||||||
|
|
||||||
if not os.path.exists(dest_dir):
|
|
||||||
os.makedirs(dest_dir)
|
|
||||||
tree.write(dest_file)
|
|
||||||
|
|
||||||
@staticmethod
|
|
||||||
def render_placeholder(lib_name):
|
|
||||||
root = etree.Element('svg', xmlns="http://www.w3.org/2000/svg")
|
|
||||||
|
|
||||||
def text_element(text, fs, x, y, font='sans-serif'):
|
|
||||||
etree.SubElement(root, "text", attrib={
|
|
||||||
'style':f"font: {font_size*fs}px {font}",
|
|
||||||
'fill': '#666',
|
|
||||||
'text-anchor':'middle',
|
|
||||||
'dominant-baseline':'middle',
|
|
||||||
'x':str(x), 'y':str(y)
|
|
||||||
}).text = text
|
|
||||||
|
|
||||||
ip_width = font_size*30
|
|
||||||
ip_height = font_size*15
|
|
||||||
etree.SubElement(root, "rect", attrib={
|
|
||||||
'x':str(margin*2), 'y':str(margin*2),
|
|
||||||
'width':str(ip_width), 'height':str(ip_height),
|
|
||||||
'rx':str(margin),
|
|
||||||
'stroke':'#666',
|
|
||||||
'fill':'none',
|
|
||||||
'stroke-width':str(stroke_width),
|
|
||||||
'stroke-dasharray':'8 16',
|
|
||||||
'stroke-linecap':'round'
|
|
||||||
})
|
|
||||||
|
|
||||||
viewbox_x = ip_width + 4*margin
|
|
||||||
viewbox_y = ip_height + 4*margin
|
|
||||||
root.set('viewBox', f"0 0 {viewbox_x} {viewbox_y}")
|
|
||||||
root.set('width', str(viewbox_x))
|
|
||||||
root.set('height', str(viewbox_y))
|
|
||||||
|
|
||||||
text_y = viewbox_y/2.5
|
|
||||||
text_x = viewbox_x/2
|
|
||||||
text_element("🧐", 4, text_x, text_y-text_vertical_margin*2)
|
|
||||||
text_element(f"{lib_name[lib_name.rfind('/')+1:]} IP-XACT not found.",
|
|
||||||
1, text_x, text_y+font_size*2+text_vertical_margin)
|
|
||||||
text_element("Generate it and the documentation:",
|
|
||||||
.75, text_x, text_y+font_size*3+text_vertical_margin*2.5)
|
|
||||||
text_element(f"(cd {lib_name}; make)",
|
|
||||||
.75, text_x, text_y+font_size*4+text_vertical_margin*3, 'monospace')
|
|
||||||
text_element("(cd docs; make html)",
|
|
||||||
.75, text_x, text_y+font_size*5+text_vertical_margin*3.5, 'monospace')
|
|
||||||
|
|
||||||
tree = etree.ElementTree(root)
|
|
||||||
return etree.tostring(tree, encoding="utf-8", method="xml").decode("utf-8")
|
|
||||||
|
|
@ -1,40 +0,0 @@
|
||||||
###############################################################################
|
|
||||||
## Copyright (C) 2022-2023 Analog Devices, Inc. All rights reserved.
|
|
||||||
### SPDX short identifier: ADIBSD
|
|
||||||
###############################################################################
|
|
||||||
|
|
||||||
class hdl_strings ():
|
|
||||||
access_type = {
|
|
||||||
'RO':{
|
|
||||||
'name': 'Read-only',
|
|
||||||
'description': 'Reads will return the current register value. Writes have no effect.'
|
|
||||||
},
|
|
||||||
'WO':{
|
|
||||||
'name': 'Write-only',
|
|
||||||
'description': 'Writes will change the current register value. Reads have no effect.'
|
|
||||||
},
|
|
||||||
'RW':{
|
|
||||||
'name': 'Read-write',
|
|
||||||
'description': 'Reads will return the current register value. Writes will change the current register value.'
|
|
||||||
},
|
|
||||||
'RW1C':{
|
|
||||||
'name': 'Read,write-1-to-clear',
|
|
||||||
'description': 'Reads will return the current register value. Writing the register will clear those bits of the register which were set to 1 in the value written. Bits are set by hardware.'
|
|
||||||
},
|
|
||||||
'RW1S':{
|
|
||||||
'name': 'Read,write-1-to-set',
|
|
||||||
'description': 'Reads will return the current register value. Writing the register will set those bits of the register which were set to 1 in the value written. Bits are cleared by hardware.'
|
|
||||||
},
|
|
||||||
'W1S':{
|
|
||||||
'name': 'Write-1-to-set',
|
|
||||||
'description': 'Writing the register will set those bits of the register which were set to 1 in the value written. Bits are cleared by hardware. Reads have no effect.'
|
|
||||||
},
|
|
||||||
'V':{
|
|
||||||
'name': 'Volatile',
|
|
||||||
'description': 'The V suffix indicates that the register is volatile and its content might change without software interaction. The value of registers without the volatile designation will not change without an explicit write done by software.'
|
|
||||||
},
|
|
||||||
'NA':{
|
|
||||||
'name': 'No access',
|
|
||||||
'description': 'Do not read or write the register.'
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
@ -1,255 +0,0 @@
|
||||||
###############################################################################
|
|
||||||
## Copyright (C) 2023 Analog Devices, Inc. All rights reserved.
|
|
||||||
### SPDX short identifier: ADIBSD
|
|
||||||
###############################################################################
|
|
||||||
|
|
||||||
import subprocess
|
|
||||||
from docutils import nodes
|
|
||||||
from sphinx.util import logging
|
|
||||||
|
|
||||||
logger = logging.getLogger(__name__)
|
|
||||||
validate_links_user_agent = 'Status resolver (Python/Sphinx)'
|
|
||||||
|
|
||||||
# Default values
|
|
||||||
dft_url_datasheet = 'https://www.analog.com/media/en/technical-documentation/data-sheets/'
|
|
||||||
dft_url_dokuwiki = 'https://wiki.analog.com'
|
|
||||||
dft_url_ez = 'https://ez.analog.com'
|
|
||||||
dft_url_mw = 'https://www.mathworks.com'
|
|
||||||
dft_url_git = 'https://github.com/analogdevicesinc'
|
|
||||||
dft_url_adi = 'https://www.analog.com'
|
|
||||||
dft_url_xilinx = 'https://www.xilinx.com'
|
|
||||||
dft_url_intel = 'https://www.intel.com'
|
|
||||||
|
|
||||||
dft_validate_links = False
|
|
||||||
|
|
||||||
git_repos = [
|
|
||||||
# url_path name
|
|
||||||
['hdl', "HDL"],
|
|
||||||
['testbenches', "Testbenches"],
|
|
||||||
['linux', "Linux"],
|
|
||||||
['no-os', "no-OS"],
|
|
||||||
['libiio', "libiio"],
|
|
||||||
['scopy', "Scopy"],
|
|
||||||
['iio-oscilloscope', "IIO Oscilloscope"],
|
|
||||||
['pyadi-iio', "PyADI-IIO"]
|
|
||||||
]
|
|
||||||
vendors = ['xilinx', 'intel', 'mw']
|
|
||||||
|
|
||||||
def get_url_config(name, inliner):
|
|
||||||
app = inliner.document.settings.env.app
|
|
||||||
return getattr(app.config, "url_"+name)
|
|
||||||
|
|
||||||
def get_outer_inner(text):
|
|
||||||
"""
|
|
||||||
Extract 'outer <inner>' fields.
|
|
||||||
"""
|
|
||||||
pos = text.find('<')
|
|
||||||
if pos != -1 and text[len(text)-1] == '>':
|
|
||||||
return (text[0:pos].strip(), text[pos+1:-1])
|
|
||||||
else:
|
|
||||||
return (None, text)
|
|
||||||
|
|
||||||
def datasheet():
|
|
||||||
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
|
||||||
if text.find(':') in [0, -1]:
|
|
||||||
url = get_url_config('datasheet', inliner) + '/' + part_id + '.pdf'
|
|
||||||
else:
|
|
||||||
anchor = text[text.find(':')+1:]
|
|
||||||
part_id = text[0:text.find(':')]
|
|
||||||
url = get_url_config('datasheet', inliner) + '/' + part_id + '.pdf#' + anchor
|
|
||||||
node = nodes.reference(rawtext, part_id + " datasheet", refuri=url, **options)
|
|
||||||
add_link(inliner, lineno, url)
|
|
||||||
return [node], []
|
|
||||||
|
|
||||||
return role
|
|
||||||
|
|
||||||
def dokuwiki():
|
|
||||||
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
|
||||||
text, path = get_outer_inner(text)
|
|
||||||
if text is None:
|
|
||||||
text = path[path.rfind('/')+1:]
|
|
||||||
url = get_url_config('dokuwiki', inliner) + '/' + path
|
|
||||||
node = nodes.reference(rawtext, text, refuri=url, **options)
|
|
||||||
add_link(inliner, lineno, url)
|
|
||||||
return [node], []
|
|
||||||
|
|
||||||
return role
|
|
||||||
|
|
||||||
def ez():
|
|
||||||
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
|
||||||
text, path = get_outer_inner(text)
|
|
||||||
if path == '/':
|
|
||||||
path = ''
|
|
||||||
url = get_url_config('ez', inliner) + '/' + path
|
|
||||||
if text is None:
|
|
||||||
text = "EngineerZone"
|
|
||||||
node = nodes.reference(rawtext, text, refuri=url, **options)
|
|
||||||
add_link(inliner, lineno, url)
|
|
||||||
return [node], []
|
|
||||||
|
|
||||||
return role
|
|
||||||
|
|
||||||
def get_active_branch_name():
|
|
||||||
branch = subprocess.run(['git', 'branch', '--show-current'], capture_output=True)
|
|
||||||
return branch.stdout.decode('utf-8').replace('\n','')
|
|
||||||
|
|
||||||
def git(repo, alt_name):
|
|
||||||
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
|
||||||
url = get_url_config('git', inliner) + '/' + repo
|
|
||||||
if text == '/':
|
|
||||||
name = "ADI " + alt_name + " repository"
|
|
||||||
node = nodes.reference(rawtext, name, refuri=url, **options)
|
|
||||||
else:
|
|
||||||
text, path = get_outer_inner(text)
|
|
||||||
pos = path.find(':')
|
|
||||||
branch = get_active_branch_name() if pos in [0, -1] else path[0:pos]
|
|
||||||
path = path[pos+1:]
|
|
||||||
if text is None:
|
|
||||||
text = path
|
|
||||||
url = url + '/blob/' + branch + '/' + path
|
|
||||||
node = nodes.reference(rawtext, text, refuri=url, **options)
|
|
||||||
add_link(inliner, lineno, url)
|
|
||||||
return [node], []
|
|
||||||
|
|
||||||
return role
|
|
||||||
|
|
||||||
def adi():
|
|
||||||
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
|
||||||
name, adi_id = get_outer_inner(text)
|
|
||||||
if name is None:
|
|
||||||
name = adi_id
|
|
||||||
url = get_url_config('adi', inliner) + '/' + adi_id
|
|
||||||
node = nodes.reference(rawtext, name, refuri=url, **options)
|
|
||||||
add_link(inliner, lineno, url)
|
|
||||||
return [node], []
|
|
||||||
|
|
||||||
return role
|
|
||||||
|
|
||||||
def vendor(vendor_name):
|
|
||||||
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
|
||||||
text, path = get_outer_inner(text)
|
|
||||||
if text is None:
|
|
||||||
text = path[path.rfind('/')+1:]
|
|
||||||
url = get_url_config(vendor_name, inliner) + '/' + path
|
|
||||||
node = nodes.reference(rawtext, text, refuri=url, **options)
|
|
||||||
add_link(inliner, lineno, url)
|
|
||||||
return [node], []
|
|
||||||
|
|
||||||
return role
|
|
||||||
|
|
||||||
def prepare_validade_links(app, env, docnames):
|
|
||||||
# Not managing links, so checking only changed files per build.
|
|
||||||
# A user can run a build with validate_links False, touch the
|
|
||||||
# desired files then run with validate_links True to check the links
|
|
||||||
# from only these files.
|
|
||||||
env.links = {}
|
|
||||||
|
|
||||||
def validate_links(app, env):
|
|
||||||
if not env.config.validate_links:
|
|
||||||
logger.info(f"Skipping {len(env.links)} URLs checks-ups. Set validate_links to True to enable this.")
|
|
||||||
return
|
|
||||||
|
|
||||||
global asyncio, aiohttp
|
|
||||||
import asyncio
|
|
||||||
import aiohttp
|
|
||||||
|
|
||||||
asyncio.run(
|
|
||||||
async_validate_links(app, env)
|
|
||||||
)
|
|
||||||
|
|
||||||
async def validate_link(link, headers):
|
|
||||||
session_timeout = aiohttp.ClientTimeout(total=None, sock_connect=10, sock_read=10)
|
|
||||||
try:
|
|
||||||
async with aiohttp.ClientSession(timeout=session_timeout) as session:
|
|
||||||
async with session.get(link, headers=headers, timeout=10) as response:
|
|
||||||
return link, response.status
|
|
||||||
except aiohttp.ClientError as e:
|
|
||||||
return link, e
|
|
||||||
except asyncio.TimeoutError as e:
|
|
||||||
return link, e
|
|
||||||
|
|
||||||
async def async_validate_links(app, env):
|
|
||||||
headers = {'User-Agent': validate_links_user_agent}
|
|
||||||
|
|
||||||
fail_count = 0
|
|
||||||
total = len(env.links)
|
|
||||||
completed = 0
|
|
||||||
tasks = []
|
|
||||||
results = []
|
|
||||||
step = 25
|
|
||||||
|
|
||||||
links = list(env.links)
|
|
||||||
leng = int(total/step)+1 if total%step != 0 else int(total/step)
|
|
||||||
for i in range(0, leng):
|
|
||||||
cur = i*step
|
|
||||||
end = total if (i+1)*step > total else (i+1)*step
|
|
||||||
_links = links[cur:end]
|
|
||||||
for link in _links:
|
|
||||||
task = asyncio.create_task(validate_link(link, headers))
|
|
||||||
tasks.append(task)
|
|
||||||
|
|
||||||
for task in asyncio.as_completed(tasks):
|
|
||||||
results.append(await task)
|
|
||||||
completed += 1
|
|
||||||
print(f'Validated URL {completed} out of {total}, bundle {i+1} of {leng}...', end='\r')
|
|
||||||
del tasks
|
|
||||||
tasks = []
|
|
||||||
|
|
||||||
for link, error in results:
|
|
||||||
if isinstance(error, asyncio.TimeoutError):
|
|
||||||
error = 'Timeout Error'
|
|
||||||
if error != 200:
|
|
||||||
fail_count += 1
|
|
||||||
if len(env.links[link]) > 1:
|
|
||||||
extended_error = f"Resolved {len(env.links[link])} times, path shown is the first instance."
|
|
||||||
else:
|
|
||||||
extended_error = ""
|
|
||||||
logger.warning(f"URL {link} returned {error}! {extended_error}", location=env.links[link][0])
|
|
||||||
|
|
||||||
if fail_count:
|
|
||||||
logger.warning(f"{fail_count} out of {len(env.links)} URLs resolved with an error ({fail_count/(len(env.links))*100:0.2f}%)!")
|
|
||||||
else:
|
|
||||||
if total == 0:
|
|
||||||
extended_info = "\nAt every build, only the links at files that changed are checked, consider touching them to re-check."
|
|
||||||
else:
|
|
||||||
extended_info = ""
|
|
||||||
logger.info(f"All {total} URLs resolved successfully.{extended_info}")
|
|
||||||
|
|
||||||
|
|
||||||
def add_link(inliner, lineno, link):
|
|
||||||
links = inliner.document.settings.env.links
|
|
||||||
docname = (inliner.document.current_source[:-4],lineno)
|
|
||||||
if link not in links:
|
|
||||||
links[link] = [docname]
|
|
||||||
else:
|
|
||||||
links[link].append(docname)
|
|
||||||
|
|
||||||
def setup(app):
|
|
||||||
app.add_role("datasheet", datasheet())
|
|
||||||
app.add_role("dokuwiki", dokuwiki())
|
|
||||||
app.add_role("ez", ez())
|
|
||||||
app.add_role("adi", adi())
|
|
||||||
for name in vendors:
|
|
||||||
app.add_role(name, vendor(name))
|
|
||||||
for path, name in git_repos:
|
|
||||||
app.add_role("git-"+path, git(path, name))
|
|
||||||
|
|
||||||
app.connect('env-before-read-docs', prepare_validade_links)
|
|
||||||
app.connect('env-updated', validate_links)
|
|
||||||
|
|
||||||
app.add_config_value('url_datasheet', dft_url_datasheet, 'env')
|
|
||||||
app.add_config_value('url_dokuwiki', dft_url_dokuwiki, 'env')
|
|
||||||
app.add_config_value('url_ez', dft_url_ez, 'env')
|
|
||||||
app.add_config_value('url_mw', dft_url_mw, 'env')
|
|
||||||
app.add_config_value('url_git', dft_url_git, 'env')
|
|
||||||
app.add_config_value('url_adi', dft_url_adi, 'env')
|
|
||||||
app.add_config_value('url_xilinx', dft_url_xilinx, 'env')
|
|
||||||
app.add_config_value('url_intel', dft_url_intel, 'env')
|
|
||||||
|
|
||||||
app.add_config_value('validate_links',dft_validate_links,'env')
|
|
||||||
|
|
||||||
return {
|
|
||||||
'version': '0.1',
|
|
||||||
'parallel_read_safe': True,
|
|
||||||
'parallel_write_safe': True,
|
|
||||||
}
|
|
||||||
|
|
@ -1,50 +1,11 @@
|
||||||
:hide-toc:
|
|
||||||
|
|
||||||
HDL Reference Designs
|
HDL Reference Designs
|
||||||
===============================================================================
|
===============================================================================
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:caption: User guide
|
|
||||||
:hidden:
|
|
||||||
|
|
||||||
user_guide/index
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:caption: Libraries
|
|
||||||
:hidden:
|
|
||||||
|
|
||||||
library/axi_dmac/index
|
|
||||||
library/spi_engine/index
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:caption: Projects
|
|
||||||
:hidden:
|
|
||||||
|
|
||||||
AD4134-FMC <projects/ad4134_fmc/index>
|
|
||||||
AD4630-FMC <projects/ad4630_fmc/index>
|
|
||||||
AD469X-FMC <projects/ad469x_fmc/index>
|
|
||||||
AD5766-SDZ <projects/ad5766_sdz/index>
|
|
||||||
AD7134-FMC <projects/ad7134_fmc/index>
|
|
||||||
AD719X-ASDZ <projects/ad719x_asdz/index>
|
|
||||||
AD738X-FMC <projects/ad738x_fmc/index>
|
|
||||||
AD7616-SDZ <projects/ad7616_sdz/index>
|
|
||||||
AD9081-FMCA-EBZ/AD9082-FMCA-EBZ <projects/ad9081_fmca_ebz/index>
|
|
||||||
AD9434-FMC <projects/ad9434_fmc/index>
|
|
||||||
AD9783-EBZ <projects/ad9783_ebz/index>
|
|
||||||
ADAQ7980-SDZ <projects/adaq7980_sdz/index>
|
|
||||||
CN0363 <projects/cn0363/index>
|
|
||||||
CN0540 <projects/cn0540/index>
|
|
||||||
CN0561 <projects/cn0561/index>
|
|
||||||
PULSAR-ADC <projects/pulsar_adc/index>
|
|
||||||
|
|
||||||
.. role:: red
|
|
||||||
.. role:: green
|
|
||||||
|
|
||||||
.. attention::
|
.. attention::
|
||||||
|
|
||||||
Work-in-progress, not all content available at the
|
Work-in-progress, not all content available at the
|
||||||
`wiki <https://wiki.analog.com/resources/fpga/docs/build>`_
|
`wiki <https://wiki.analog.com/resources/fpga/docs/build>`_
|
||||||
have been imported yet.
|
has been imported yet.
|
||||||
|
|
||||||
.. image:: sources/HDL_logo.svg
|
.. image:: sources/HDL_logo.svg
|
||||||
:align: center
|
:align: center
|
||||||
|
|
@ -55,3 +16,15 @@ HDL libraries and projects for various reference design and prototyping systems.
|
||||||
This repository contains HDL code (Verilog or VHDL) and the required Tcl scripts
|
This repository contains HDL code (Verilog or VHDL) and the required Tcl scripts
|
||||||
to create and build a specific FPGA example design using Xilinx and/or Intel tool
|
to create and build a specific FPGA example design using Xilinx and/or Intel tool
|
||||||
chain.
|
chain.
|
||||||
|
|
||||||
|
.. hdl-build-status::
|
||||||
|
|
||||||
|
Contents
|
||||||
|
===============================================================================
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
user_guide/index
|
||||||
|
library/index
|
||||||
|
projects/index
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,18 @@
|
||||||
|
Libraries
|
||||||
|
===============================================================================
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This page lists only the IPs that have been ported to the new documentation
|
||||||
|
format.
|
||||||
|
|
||||||
|
See :ref:`ip_cores` for a complete list of IP cores.
|
||||||
|
|
||||||
|
Contents
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
axi_dmac/index
|
||||||
|
spi_engine/index
|
||||||
|
|
@ -36,9 +36,10 @@ Block design
|
||||||
-------------------------------------------------------------------------------
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
The reference design uses the standard :ref:`SPI Engine Framework <spi_engine>`
|
The reference design uses the standard :ref:`SPI Engine Framework <spi_engine>`
|
||||||
to interface the :adi:`AD4696` ADC in single SDO Mode. The :ref:`SPI Engine
|
to interface the :adi:`AD4696` ADC in single SDO Mode.
|
||||||
Offload module <spi_engine offload>`, which can be used to capture continuous
|
The :ref:`SPI Engine Offload module <spi_engine offload>`, which can be used to
|
||||||
data stream at maximum data rate, is triggered by the BUSY signal of the device.
|
capture continuous data stream at maximum data rate, is triggered by the BUSY
|
||||||
|
signal of the device.
|
||||||
|
|
||||||
Block diagram
|
Block diagram
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,36 @@
|
||||||
|
Projects
|
||||||
|
===============================================================================
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This page lists only reference designs that have been ported to the new
|
||||||
|
documentation format.
|
||||||
|
|
||||||
|
See
|
||||||
|
:dokuwiki:`AMD Xilinx Reference Designs <resources/alliances/xilinx>`
|
||||||
|
and
|
||||||
|
:dokuwiki:`Intel Reference Designs <resources/alliances/altera>`
|
||||||
|
for a complete list of reference designs.
|
||||||
|
|
||||||
|
Contents
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
AD4134-FMC <ad4134_fmc/index>
|
||||||
|
AD4630-FMC <ad4630_fmc/index>
|
||||||
|
AD469X-FMC <ad469x_fmc/index>
|
||||||
|
AD5766-SDZ <ad5766_sdz/index>
|
||||||
|
AD7134-FMC <ad7134_fmc/index>
|
||||||
|
AD719X-ASDZ <ad719x_asdz/index>
|
||||||
|
AD738X-FMC <ad738x_fmc/index>
|
||||||
|
AD7616-SDZ <ad7616_sdz/index>
|
||||||
|
AD9081-FMCA-EBZ/AD9082-FMCA-EBZ <ad9081_fmca_ebz/index>
|
||||||
|
AD9434-FMC <ad9434_fmc/index>
|
||||||
|
AD9783-EBZ <ad9783_ebz/index>
|
||||||
|
ADAQ7980-SDZ <adaq7980_sdz/index>
|
||||||
|
CN0363 <cn0363/index>
|
||||||
|
CN0540 <cn0540/index>
|
||||||
|
CN0561 <cn0561/index>
|
||||||
|
PULSAR-ADC <pulsar_adc/index>
|
||||||
|
|
@ -1,9 +1,3 @@
|
||||||
sphinx
|
sphinx
|
||||||
regex
|
https://github.com/analogdevicesinc/doctools/releases/download/latest/adi-doctools.tar.gz
|
||||||
lxml
|
sphinxcontrib.wavedrom
|
||||||
furo
|
|
||||||
wavedrom
|
|
||||||
aiohttp
|
|
||||||
aiodns
|
|
||||||
sphinxcontrib-wavedrom
|
|
||||||
sphinxcontrib-svg2pdfconverter
|
|
||||||
|
|
|
||||||
|
|
@ -1,155 +0,0 @@
|
||||||
.sidebar-brand {
|
|
||||||
background-color: #f8f9fb;
|
|
||||||
border-radius: .25em;
|
|
||||||
margin: var(--sidebar-item-spacing-vertical)
|
|
||||||
calc(var(--sidebar-item-spacing-horizontal)/2)
|
|
||||||
0
|
|
||||||
calc(var(--sidebar-item-spacing-horizontal)/2);
|
|
||||||
padding: 0;
|
|
||||||
width: 11em;
|
|
||||||
margin-left: 2.25em;
|
|
||||||
}
|
|
||||||
.sidebar-brand::before {
|
|
||||||
content: "";
|
|
||||||
display: block;
|
|
||||||
height: 4.5em;
|
|
||||||
background-size: auto 5.625em;
|
|
||||||
background-image: url(HDL_logo.svg);
|
|
||||||
background-position: -10em -.5em;
|
|
||||||
background-repeat: no-repeat;
|
|
||||||
}
|
|
||||||
.sidebar-brand-text {
|
|
||||||
display: none;
|
|
||||||
}
|
|
||||||
body[data-theme="dark"] .sidebar-brand {
|
|
||||||
color: #fff;
|
|
||||||
}
|
|
||||||
@media (min-width: 56em){
|
|
||||||
.content {
|
|
||||||
width: 52em;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
figure > object {
|
|
||||||
max-width: 100%;
|
|
||||||
}
|
|
||||||
img {
|
|
||||||
background: #fff;
|
|
||||||
border-radius: .25em;
|
|
||||||
padding: .5em 0;
|
|
||||||
}
|
|
||||||
iframe {
|
|
||||||
width: calc(50.625rem - 1rem);
|
|
||||||
height: calc(28.47rem - 0.5625rem);
|
|
||||||
margin-left: -1rem;
|
|
||||||
}
|
|
||||||
@media (max-width:50.625rem) {
|
|
||||||
iframe {
|
|
||||||
width: calc(100vw - 1rem);
|
|
||||||
height: calc(56.25vw - 1rem);
|
|
||||||
margin-left: -1rem;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
.WaveDrom {
|
|
||||||
background: #fff;
|
|
||||||
border-radius: .25em;
|
|
||||||
padding: .5em 0;
|
|
||||||
}
|
|
||||||
table.regmap {
|
|
||||||
font-size: .9em;
|
|
||||||
}
|
|
||||||
table.regmap .caption-text{
|
|
||||||
font-size: 1rem;
|
|
||||||
}
|
|
||||||
th, td.type {
|
|
||||||
white-space: nowrap;
|
|
||||||
}
|
|
||||||
td.description {
|
|
||||||
width: 45%;
|
|
||||||
font-size:.8em;
|
|
||||||
}
|
|
||||||
.red {
|
|
||||||
color: red;
|
|
||||||
}
|
|
||||||
.green {
|
|
||||||
color: green;
|
|
||||||
}
|
|
||||||
#signal-and-interface-pins h3 {
|
|
||||||
font-weight: normal;
|
|
||||||
}
|
|
||||||
.table-wrapper {
|
|
||||||
overflow: visible;
|
|
||||||
}
|
|
||||||
.collapsible {
|
|
||||||
border: 1px solid var(--color-table-border);
|
|
||||||
border-radius: .25em;
|
|
||||||
margin-bottom: -1px;
|
|
||||||
}
|
|
||||||
.collapsible_input {
|
|
||||||
display: none;
|
|
||||||
}
|
|
||||||
.collapsible_content {
|
|
||||||
border-top: 1px solid var(--color-table-border);
|
|
||||||
overflow: hidden;
|
|
||||||
height: 0;
|
|
||||||
padding: 0 .75em !important;
|
|
||||||
transition: ease opacity .25s;
|
|
||||||
opacity: 0;
|
|
||||||
}
|
|
||||||
.collapsible label {
|
|
||||||
width: 100%;
|
|
||||||
padding: 0.75em 1em 0.75em .75em;
|
|
||||||
user-select: none;
|
|
||||||
box-sizing: border-box;
|
|
||||||
cursor: pointer;
|
|
||||||
display: flex;
|
|
||||||
align-items: center;
|
|
||||||
justify-content: space-between;
|
|
||||||
font-weight: bold;
|
|
||||||
color: var(--color-toc-item-text);
|
|
||||||
}
|
|
||||||
.collapsible label .icon {
|
|
||||||
border: solid var(--color-toc-item-text);
|
|
||||||
border-width: 0 2px 2px 0;
|
|
||||||
display: block;
|
|
||||||
transition: transform ease .125s, margin-top ease .125s;
|
|
||||||
width: .6em;
|
|
||||||
height: .6em;
|
|
||||||
transform: rotate(-45deg);
|
|
||||||
}
|
|
||||||
.collapsible label p {
|
|
||||||
display: inline-block;
|
|
||||||
margin: 0;
|
|
||||||
}
|
|
||||||
.collapsible label, .collapsible div {
|
|
||||||
transition: box-shadow ease .25s;
|
|
||||||
}
|
|
||||||
.collapsible label:hover ~ div, .collapsible label:hover {
|
|
||||||
box-shadow: 0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1);
|
|
||||||
}
|
|
||||||
.collapsible_input:checked ~ label .icon {
|
|
||||||
transform: rotate(45deg);
|
|
||||||
margin-top: -.5em;
|
|
||||||
}
|
|
||||||
.collapsible_content {
|
|
||||||
overflow: auto;
|
|
||||||
}
|
|
||||||
.collapsible_input:checked ~ .collapsible_content {
|
|
||||||
height: 100%;
|
|
||||||
opacity: 1;
|
|
||||||
}
|
|
||||||
.default {
|
|
||||||
min-width: 5em;
|
|
||||||
max-width: 11em;
|
|
||||||
line-break: anywhere;
|
|
||||||
}
|
|
||||||
.default .pre {
|
|
||||||
white-space: pre;
|
|
||||||
}
|
|
||||||
|
|
||||||
#hdl-component-diagram {
|
|
||||||
text-align: center;
|
|
||||||
}
|
|
||||||
|
|
||||||
#hdl-component-diagram svg {
|
|
||||||
max-width: 100%;
|
|
||||||
}
|
|
||||||
|
|
@ -3,12 +3,13 @@
|
||||||
Documentation guidelines
|
Documentation guidelines
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
A brief set-of-rules for the documentation.
|
This documentation is built with `Sphinx <https://www.sphinx-doc.org>`_ and
|
||||||
|
all source code is available at the path :git-hdl:`docs`.
|
||||||
|
|
||||||
.. note::
|
To contribute to it, open a pull request with the changes to
|
||||||
The old wiki uses `dokuwiki <https://www.dokuwiki.org/dokuwiki>`_. When
|
:git-hdl:`this repository </>`, just make sure to read the general
|
||||||
importing text from there, consider the automated options that are provided
|
:ref:`doctools:docs_guidelines` first **and** the additional guidelines
|
||||||
in this page to convert it to reST.
|
below specific to the HDL repository.
|
||||||
|
|
||||||
Templates
|
Templates
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
|
|
@ -20,546 +21,17 @@ Templates are available:
|
||||||
* :git-hdl:`docs/projects/template` (:ref:`rendered <template_project>`).
|
* :git-hdl:`docs/projects/template` (:ref:`rendered <template_project>`).
|
||||||
|
|
||||||
Remove the ``:orphan:`` in the first line, it is to hide the templates from the
|
Remove the ``:orphan:`` in the first line, it is to hide the templates from the
|
||||||
`TOC tree <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`_.
|
`TOC tree <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`_,
|
||||||
|
and make sure to remove any placeholder text and instructive comment.
|
||||||
Indentation
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Directives are indented with 3 space, which is Sphinx's default.
|
|
||||||
At code directives, the code keeps its original indentation (e.g. 2 spaces for
|
|
||||||
Verilog code), but is offset by 3 spaces at the beginning of every line, to
|
|
||||||
instruct Sphinx the beginning and end of the code directive.
|
|
||||||
|
|
||||||
Table of contents
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
The relation between pages are created with the ``toctree`` directive,
|
|
||||||
which allows to generate the table of contents and navigation bars.
|
|
||||||
The ``toctree`` directive has the following format:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:caption: Caption
|
|
||||||
:hidden:
|
|
||||||
|
|
||||||
Custom title <path/to/page>
|
|
||||||
|
|
||||||
For pages with shorter titles, such as libraries, the label is inherited from
|
|
||||||
the page itself, for example:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:caption: Libraries
|
|
||||||
:hidden:
|
|
||||||
|
|
||||||
library/axi_dmac/index
|
|
||||||
library/spi_engine/index
|
|
||||||
|
|
||||||
And for pages with long titles, such as projects, overwrite the full title with
|
|
||||||
a custom title, e.g:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:caption: Projects
|
|
||||||
:hidden:
|
|
||||||
|
|
||||||
AD7616-SDZ <projects/ad7616_sdz/index>
|
|
||||||
|
|
||||||
This way, only "AD7616-SDZ" will be displayed in the page navigation bar instead
|
|
||||||
of "AD7616-SDZ HDL project".
|
|
||||||
|
|
||||||
References
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
References have the format ``library/project context``, e.g.
|
|
||||||
:code:`:ref:\`spi_engine execution\`` renders as :ref:`spi_engine execution`.
|
|
||||||
Notice how neither *library* nor *project* are present in the label, since there is no
|
|
||||||
naming collision between libraries or projects (no project will ever be named
|
|
||||||
*axi_dmac*).
|
|
||||||
|
|
||||||
Also, for project, libraries and IPs, the names should be exactly the
|
|
||||||
name of its folders, e.g. ``axi_pwm_gen`` and not ``axi-pwm-gen`` or ``AXI_PWM_GEN``,
|
|
||||||
this helps avoid broken references.
|
|
||||||
|
|
||||||
For resources without a particular source code file/folder, prefer hyphen ``-``
|
|
||||||
separation, for example, ``spi_engine control-interface`` instead of
|
|
||||||
``spi_engine control_interface``.
|
|
||||||
|
|
||||||
Text width
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Each line must be less than 80 columns wide.
|
|
||||||
You can use the :code:`fold` command to break the lines of the imported text
|
|
||||||
while respecting word-breaks:
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
cat imported.txt | fold -sw 80 > imported.rst
|
|
||||||
|
|
||||||
Or use :code:`pandoc`:
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
pandoc imported.txt -f dokuwiki -t rst --columns=80 -s -o imported.rst
|
|
||||||
|
|
||||||
|
|
||||||
Tables
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Prefer
|
|
||||||
`list-tables <https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table>`_
|
|
||||||
and imported
|
|
||||||
`csv-tables <https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table-1>`_
|
|
||||||
(using the file option), because they are faster to create, easier to maintain
|
|
||||||
and the 80 column-width rule can be respected with list-tables.
|
|
||||||
|
|
||||||
You can use the following command:
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
pandoc imported.txt -f dokuwiki -t rst --columns=80 -s -o imported.rst --list-tables
|
|
||||||
|
|
||||||
The :code:`list-tables` parameter requires *pandoc-types* >= 1.23, if it is not
|
|
||||||
an option, you shall remove it and export in the *grid* table format.
|
|
||||||
|
|
||||||
Now you only have to adjust the widths and give the final touches, like using
|
|
||||||
the correct directives and roles.
|
|
||||||
|
|
||||||
Lists
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Unordered lists use ``*`` or ``-`` and ordered lists ``#.``.
|
|
||||||
|
|
||||||
Child items must be aligned with the first letter of the parent item, that means,
|
|
||||||
2 spaces for unordered list and 3 spaces for ordered lists, for example:
|
|
||||||
|
|
||||||
.. code-block:: rst
|
|
||||||
|
|
||||||
#. Parent ordered item.
|
|
||||||
|
|
||||||
* Child unordeded item.
|
|
||||||
|
|
||||||
#. Child ordered item.
|
|
||||||
#. Child ordered item.
|
|
||||||
|
|
||||||
Renders as:
|
|
||||||
|
|
||||||
#. Parent numbered item.
|
|
||||||
|
|
||||||
* Child unordered item.
|
|
||||||
|
|
||||||
#. Child ordered item.
|
|
||||||
#. Child ordered item.
|
|
||||||
|
|
||||||
Code
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Prefer
|
|
||||||
`code-blocks <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`_
|
|
||||||
to
|
|
||||||
`code <https://docutils.sourceforge.io/docs/ref/rst/directives.html#code>`_
|
|
||||||
directives, because code-blocks have more options, such as showing line numbers
|
|
||||||
and emphasizing lines.
|
|
||||||
|
|
||||||
For example,
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
:linenos:
|
|
||||||
:emphasize-lines: 2
|
|
||||||
|
|
||||||
def hello_world():
|
|
||||||
string = "Hello world"
|
|
||||||
print(string)
|
|
||||||
|
|
||||||
Renders as
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
:linenos:
|
|
||||||
:emphasize-lines: 2
|
|
||||||
|
|
||||||
def hello_world():
|
|
||||||
string = "Hello world"
|
|
||||||
print(string)
|
|
||||||
|
|
||||||
Images
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Prefer the SVG format for images, and save it as *Optimized SVG* in
|
|
||||||
`inkscape <https://inkscape.org/>`_ to use less space.
|
|
||||||
|
|
||||||
Store them in a hierarchically, do not use ``images`` subdirectories.
|
|
||||||
The idea is to have simpler relative paths, for example, e.g.:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. image: ad2234_sdz_schematic.svg
|
|
||||||
|
|
||||||
|
|
||||||
Instead of overly complicated paths like:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. image: ../../project/images/ad2234_sdz/ad2234_sdz_schematic.svg
|
|
||||||
|
|
||||||
In general, this avoids dangling artifacts and keeps the documentation simple.
|
|
||||||
|
|
||||||
Vivado block-diagrams
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Vivado block-diagrams can be exported as PDF and then converted to SVG with
|
|
||||||
Inkscape. See :ref:`spi_engine tutorial` for a "final result" example.
|
|
||||||
|
|
||||||
Vivado waveform data
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
There is no way to export Vivado waveform data as vectors.
|
|
||||||
Therefore, the recommended method is to take a PNG screenshot and use
|
|
||||||
`GIMP <gimp.org>`_ to export as **8bpc RGB** with all metadata options
|
|
||||||
disabled.
|
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Always use the *Export As..* ``Ctrl+Shift+E`` option.
|
The old wiki uses `dokuwiki <https://www.dokuwiki.org/dokuwiki>`_. When
|
||||||
|
importing text from there, consider ``pandoc`` and the tips accross the
|
||||||
To reduce even further the size, you can use *Color > Dither..* to reduce the
|
:ref:`doctools:docs_guidelines` to convert it to reST.
|
||||||
number of colors in the PNG.
|
|
||||||
Saving as greyscale also reduces the PNG size, but might reduce readability and
|
|
||||||
it is not recommended.
|
|
||||||
|
|
||||||
Third-party directives and roles
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Third-party tools are used to expand Sphinx functionality, if you haven't already,
|
|
||||||
do:
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
pip install -r requirements.txt
|
|
||||||
|
|
||||||
Custom directives and roles
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
To expand Sphinx functionality beyond existing tools, custom directives and roles
|
|
||||||
have been written, which are located in the *docs/extensions* folder.
|
|
||||||
Extensions are straight forward to create, if some functionality is missing,
|
|
||||||
consider requesting or creating one.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
Link-like roles use the :code:`:role:\`text <link>\`` synthax, like external
|
|
||||||
links, but without the undescore in the end.
|
|
||||||
|
|
||||||
Color role
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
To print text in red or green, use :code:`:red:\`text\`` and :code:`:green:\`text\``.
|
|
||||||
|
|
||||||
Link roles
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The link roles are a group of roles defined by ``adi_links.py``.
|
|
||||||
|
|
||||||
The ``validate_links`` global option is used to validate each link during build.
|
|
||||||
These links are not managed, that means, only links from changed files are checked.
|
|
||||||
You can run a build with it set to False, then touch the desired files to check
|
|
||||||
the links of only these files.
|
|
||||||
|
|
||||||
Git role
|
|
||||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
||||||
|
|
||||||
The Git role allows to create links to the Git repository with a shorter syntax.
|
|
||||||
The role syntax is :code:`:git-repo:\`text <branch:path>\``, for example:
|
|
||||||
|
|
||||||
* :code:`:git-hdl:\`main:docs/user_guide/docs_guidelines.rst\``
|
|
||||||
renders as :git-hdl:`main:docs/user_guide/docs_guidelines.rst`.
|
|
||||||
* :code:`:git-hdl:\`Guidelines <docs/user_guide/docs_guidelines.rst>\``
|
|
||||||
renders as :git-hdl:`Guidelines <docs/user_guide/docs_guidelines.rst>`.
|
|
||||||
|
|
||||||
When the branch field is not present, it will be filled with the current branch.
|
|
||||||
It is recommended to not provide this field when it is a link to its own repository,
|
|
||||||
because it is useful to auto-fill it for documentation releases
|
|
||||||
(e.g. ``hdl_2023_r2``).
|
|
||||||
A scenario where it is recommended to provide the branch is when linking others
|
|
||||||
repositories.
|
|
||||||
|
|
||||||
The text field is optional and will be filled with the full path.
|
|
||||||
|
|
||||||
Finally, you can do :code:`:git-repo:\`/\`` for a link to the root of the
|
|
||||||
repository with pretty naming, for example, :code:`:git-hdl:\`/\`` is rendered
|
|
||||||
as :git-hdl:`/`.
|
|
||||||
|
|
||||||
ADI role
|
|
||||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
||||||
|
|
||||||
The adi role creates links for a webpage to the Analog Devices Inc. website.
|
|
||||||
|
|
||||||
The role syntax is :code:`:adi:\`text <webpage>\``, for example,
|
|
||||||
:code:`:adi:\`AD7175-2 <ad7175-2>\``.
|
|
||||||
Since links are case insensitive, you can also reduce it to
|
|
||||||
:code:`:adi:\`AD7175-2\``, when *webpage* is the same as *text* and will render
|
|
||||||
as :adi:`AD7175-2`.
|
|
||||||
|
|
||||||
Datasheet role
|
|
||||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
||||||
|
|
||||||
The datasheet role creates links for a datasheet in the Analog Devices Inc. website.
|
|
||||||
|
|
||||||
The role syntax is :code:`:datasheet:\`part_id:anchor\``, for example,
|
|
||||||
:code:`:datasheet:\`AD7984:[{"num"%3A51%2C"gen"%3A0}%2C{"name"%3A"XYZ"}%2C52%2C713%2C0]\``
|
|
||||||
is rendered as
|
|
||||||
:datasheet:`AD7984:[{"num"%3A51%2C"gen"%3A0}%2C{"name"%3A"XYZ"}%2C52%2C713%2C0]`.
|
|
||||||
The anchor is optional and is a link to a section of the PDF, and can be obtained
|
|
||||||
by just copying the link in the table of contents.
|
|
||||||
|
|
||||||
.. caution::
|
|
||||||
|
|
||||||
Since not all PDF readers support anchors, always provide the page and/or
|
|
||||||
figure number!
|
|
||||||
|
|
||||||
Dokuwiki role
|
|
||||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
||||||
|
|
||||||
The dokuwiki role creates links to the Analog Devices Inc. wiki website.
|
|
||||||
The role syntax is :code:`:dokuwiki:\`text <path>\``, for example,
|
|
||||||
:code:`:dokuwiki:\`pulsar-adc-pmods <resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods>\``
|
|
||||||
gets rendered as
|
|
||||||
:dokuwiki:`pulsar-adc-pmods <resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods>`.
|
|
||||||
|
|
||||||
EngineerZone role
|
|
||||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
||||||
|
|
||||||
The ez role creates links to the Analog Devices Inc. EngineerZone support website.
|
|
||||||
The role syntax is :code:`:ez:\`community\``, for example, :code:`:ez:\`fpga\``
|
|
||||||
gets rendered as :ez:`fpga`.
|
|
||||||
|
|
||||||
For Linux Software Drivers, it is :code:`:ez:\`linux-software-drivers\``.
|
|
||||||
|
|
||||||
For Microcontroller no-OS Drivers it is :code:`:ez:\`microcontroller-no-os-drivers\``.
|
|
||||||
|
|
||||||
Vendor role
|
|
||||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
||||||
|
|
||||||
The vendor role creates links to the vendor's website.
|
|
||||||
The role syntax is :code:`:vendor:\`text <path>\``, for example,
|
|
||||||
:code:`:xilinx:\`Zynq-7000 SoC Overview <support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf>\``
|
|
||||||
gets rendered
|
|
||||||
:xilinx:`Zynq-7000 SoC Overview <support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf>`.
|
|
||||||
|
|
||||||
The text parameter is optional, if absent, the file name will be used as the text,
|
|
||||||
for example,
|
|
||||||
:code:`:intel:\`content/www/us/en/docs/programmable/683780/22-4/general-purpose-i-o-overview.html\``
|
|
||||||
gets rendered
|
|
||||||
:intel:`content/www/us/en/docs/programmable/683780/22-4/general-purpose-i-o-overview.html`
|
|
||||||
(not very readable).
|
|
||||||
|
|
||||||
Supported vendors are: ``xilinx`` (AMD Xilinx), ``intel`` (Intel Altera) and
|
|
||||||
``mw`` (MathWorks).
|
|
||||||
|
|
||||||
HDL parameters directive
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The HDL parameters directive gets information parsed from IP-XACT (*component.xml*)
|
|
||||||
library and generates a table with the IP parameters.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
The IP-XACT files are generated by Vivado during the library build and not by
|
|
||||||
the documentation tooling.
|
|
||||||
|
|
||||||
The directive syntax is:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. hdl-parameters::
|
|
||||||
:path: <ip_path>
|
|
||||||
|
|
||||||
* - <parameter>
|
|
||||||
- <description>
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. hdl-parameters::
|
|
||||||
:path: library/spi_engine/spi_engine_interconnect
|
|
||||||
|
|
||||||
* - DATA_WIDTH
|
|
||||||
- Data width of the parallel SDI/SDO data interfaces.
|
|
||||||
* - NUM_OF_SDI
|
|
||||||
- Number of SDI lines on the physical SPI interface.
|
|
||||||
|
|
||||||
Renders as:
|
|
||||||
|
|
||||||
.. hdl-parameters::
|
|
||||||
:path: library/spi_engine/spi_engine_interconnect
|
|
||||||
|
|
||||||
* - DATA_WIDTH
|
|
||||||
- Data width of the parallel SDI/SDO data interfaces.
|
|
||||||
* - NUM_OF_SDI
|
|
||||||
- Number of SDI lines on the physical SPI interface.
|
|
||||||
|
|
||||||
Descriptions in the directive have higher precedence than in the *component.xml*
|
|
||||||
file.
|
|
||||||
|
|
||||||
The ``:path:`` option is optional, and should **not** be included if the
|
|
||||||
documentation file path matches the *component.xml* hierarchically.
|
|
||||||
|
|
||||||
HDL interface directive
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The HDL interfaces directive gets information parsed from *component.xml* library
|
|
||||||
and generates tables with the IP interfaces, both buses and ports.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
The *component.xml* files are generated by Vivado during the library build
|
|
||||||
and not by the documentation tooling.
|
|
||||||
|
|
||||||
The directive syntax is:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. hdl-interfaces::
|
|
||||||
:path: <ip_path>
|
|
||||||
|
|
||||||
* - <parameter>
|
|
||||||
- <description>
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. hdl-interfaces::
|
|
||||||
:path: library/spi_engine/spi_engine_interconnect
|
|
||||||
|
|
||||||
Descriptions in the directive have higher precedence than in the *component.xml*
|
|
||||||
file.
|
|
||||||
You can provide description to a port or a bus, but not for a bus port.
|
|
||||||
|
|
||||||
The ``:path:`` option is optional, and should **not** be included if the
|
|
||||||
documentation file path matches the *component.xml* hierarchically.
|
|
||||||
|
|
||||||
HDL component diagram directive
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The HDL component diagram directive gets information parsed from *component.xml*
|
|
||||||
library and generates a component diagram for the IP with buses and ports
|
|
||||||
information.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
The *component.xml* files are generated by Vivado during the library build
|
|
||||||
and not by the documentation tooling.
|
|
||||||
|
|
||||||
The directive syntax is:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. hdl-component-diagram::
|
|
||||||
:path: <ip_path>
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. hdl-component-diagram::
|
|
||||||
:path: library/spi_engine/spi_engine_interconnect
|
|
||||||
|
|
||||||
The ``:path:`` option is optional, and should **not** be included if the
|
|
||||||
documentation file path matches the *component.xml* hierarchically.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
This directive replaces the deprecated ``symbolator`` directive.
|
|
||||||
|
|
||||||
HDL regmap directive
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The HDL regmap directive gets information from *docs/regmap/adi_regmap_\*.txt* files
|
|
||||||
and generates tables with the register maps.
|
|
||||||
|
|
||||||
The directive syntax is:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. hdl-regmap::
|
|
||||||
:name: <regmap_name>
|
|
||||||
:no-type-info:
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. hdl-regmap::
|
|
||||||
:name: DMAC
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
The register map name is the title-tool, the value above ``ENDTITLE`` in the
|
|
||||||
source file.
|
|
||||||
|
|
||||||
This directive does not support content for descriptions, since the source file
|
|
||||||
already have proper descriptions.
|
|
||||||
|
|
||||||
The ``:name:`` option is **required**, because the title tool does not match
|
|
||||||
the IP name and one single *docs/regmap/adi_regmap_\*.txt* file can have more than
|
|
||||||
one register map.
|
|
||||||
The ``:no-type-info:`` option is optional, and should **not** be included if it is
|
|
||||||
in the main IP documentation page. It appends an auxiliary table explaining the
|
|
||||||
register access types.
|
|
||||||
|
|
||||||
Collapsible directive
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The collapsible directive creates a collapsible/dropdown/"HTML details".
|
|
||||||
|
|
||||||
The directive syntax is:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. collapsible:: <label>
|
|
||||||
|
|
||||||
<content>
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
.. code:: rst
|
|
||||||
|
|
||||||
.. collapsible:: Python code example.
|
|
||||||
|
|
||||||
.. code:: python
|
|
||||||
|
|
||||||
print("Hello World!")
|
|
||||||
|
|
||||||
Renders as:
|
|
||||||
|
|
||||||
.. collapsible:: Python code example.
|
|
||||||
|
|
||||||
.. code:: python
|
|
||||||
|
|
||||||
print("Hello World!")
|
|
||||||
|
|
||||||
Notice how you can use any Sphinx syntax, even nest other directives.
|
|
||||||
|
|
||||||
.. _installing_pandoc:
|
|
||||||
|
|
||||||
Global options for HDL directives
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Set ``hide_collapsible_content`` to True to hide the collapsibles by default.
|
|
||||||
|
|
||||||
Set ``validate_links`` to True to validate each link during build.
|
|
||||||
These links are not managed, that means, only links from changed files are checked.
|
|
||||||
You can run a build with it set to False, then touch the desired files to check
|
|
||||||
the links of only these files.
|
|
||||||
|
|
||||||
Common sections
|
Common sections
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
The **More information** and **Support** sections that are present in
|
The **More information** and **Support** sections that are present in
|
||||||
the HDL project documentation, are actually separate pages inserted as links.
|
the HDL project documentation, are actually separate pages inserted as links.
|
||||||
|
|
@ -576,4 +48,4 @@ They are inserted like this:
|
||||||
|
|
||||||
.. include:: ../common/support.rst
|
.. include:: ../common/support.rst
|
||||||
|
|
||||||
and will be rendered as sections of the page.
|
And they will be rendered as sections of the page.
|
||||||
|
|
|
||||||
|
|
@ -154,8 +154,7 @@ Vivado and \*_hw.tcl for Quartus) .
|
||||||
design.
|
design.
|
||||||
|
|
||||||
To find more information about how to build the libraries, please visit
|
To find more information about how to build the libraries, please visit
|
||||||
the :ref:`Building & Generating programming files
|
the :ref:`Building & Generating programming files <build_hdl>` section.
|
||||||
<build_hdl>` section.
|
|
||||||
|
|
||||||
|
|
||||||
Repository releases and branches
|
Repository releases and branches
|
||||||
|
|
|
||||||
|
|
@ -36,7 +36,7 @@ Contents
|
||||||
#. :ref:`porting_project`: How to port a project to a non-supported carrier
|
#. :ref:`porting_project`: How to port a project to a non-supported carrier
|
||||||
#. :ref:`customize_hdl`: Using and modifying the HDL design
|
#. :ref:`customize_hdl`: Using and modifying the HDL design
|
||||||
#. :ref:`hdl_coding_guideline`: The Verilog/VHDL coding guidelines that the
|
#. :ref:`hdl_coding_guideline`: The Verilog/VHDL coding guidelines that the
|
||||||
HDL team is following
|
HDL team follows
|
||||||
#. :ref:`docs_guidelines`: Documentation guidelines
|
#. :ref:`docs_guidelines`: Documentation guidelines
|
||||||
#. :ref:`third_party`: Third party forks with derived work
|
#. :ref:`third_party`: Third party forks with derived work
|
||||||
#. :dokuwiki:`Reference designs using AMD Xilinx hardware <resources/alliances/xilinx>`
|
#. :dokuwiki:`Reference designs using AMD Xilinx hardware <resources/alliances/xilinx>`
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue