diff --git a/README.md b/README.md
index a578fc33d..9c078aa2b 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,32 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+---
# HDL Reference Designs
[Analog Devices Inc.](http://www.analog.com/en/index.html) HDL libraries and projects for various reference design and prototyping systems.
@@ -17,6 +45,18 @@ There is no free replacement for consulting services. If you have questions that
This repository supports reference designs for different [Analog Devices boards](../master/projects) based on [Intel and Xilinx FPGA development boards](../master/projects/common) or standalone.
+### Building documentation
+
+Install necessary tools
+```
+cd docs
+pip install -r requirements.txt
+```
+Then build the documentation with sphinx
+```
+make html
+```
+
### Prerequisites
* [Vivado Design Suite](https://www.xilinx.com/support/download.html)
@@ -35,8 +75,8 @@ Windows user please checkout [this page](https://wiki.analog.com/resources/fpga/
To build a project, checkout the [latest release](https://github.com/analogdevicesinc/hdl/releases), after that just **cd** to the
project that you want to build and run make:
```
- [~]cd projects/fmcomms2/zc706
- [~]make
+cd projects/fmcomms2/zc706
+make
```
A more comprehensive build guide can be found under the following link:
diff --git a/docs/extensions/adi_hdl_parser.py b/docs/extensions/adi_hdl_parser.py
index ba8e9e0fe..d18ed95af 100644
--- a/docs/extensions/adi_hdl_parser.py
+++ b/docs/extensions/adi_hdl_parser.py
@@ -1,3 +1,8 @@
+###############################################################################
+## Copyright (C) 2022-2023 Analog Devices, Inc. All rights reserved.
+### SPDX short identifier: ADIBSD
+###############################################################################
+
import os.path
from docutils import nodes
from docutils.statemachine import ViewList
@@ -96,7 +101,7 @@ class directive_base(Directive):
else:
items[key].append(line)
for key in items:
- items[key] = ' '.join(items[key]).strip().replace('- ', '', 1)
+ items[key] = ' '.join(items[key]).replace('-', '', 1).strip()
return items
def column_entry(self, row, text, node_type, classes=[]):
@@ -198,8 +203,8 @@ class directive_base(Directive):
is_div=True,
classes=['collapsible_content']
)
- label += icon
label += nodes.paragraph(text=text)
+ label += icon
container += input_
container += label
@@ -209,6 +214,23 @@ class directive_base(Directive):
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}
@@ -230,8 +252,9 @@ class directive_interfaces(directive_base):
section += title
if bs[tag]['dependency'] is not None:
- dependency = nodes.paragraph(text=f"Depends on {pretty_dep(bs[tag]['dependency'])}.")
- section += dependency
+ 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)
@@ -283,15 +306,28 @@ class directive_interfaces(directive_base):
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 key in description:
- self.column_entry(row, description[key], 'reST', classes=['description'])
+ if 'clk' in key or 'clock' in key:
+ domain = 'clock domain'
+ elif 'reset':
+ domain = 'reset signal'
else:
- self.column_entry(row, '', 'paragraph')
+ 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()
@@ -507,6 +543,7 @@ class directive_parameters(directive_base):
def parse_hdl_component(path, ctime):
component = {
'bus_interface':{},
+ 'bus_domain':{},
'ports': {},
'parameters': {},
'ctime': ctime
@@ -580,8 +617,22 @@ def parse_hdl_component(path, ctime):
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
+
bs[bus_name] = {
'name': sattrib(get(bus_interface, 'busType'), 'name'),
'dependency': get_dependency(bus_interface, 'busInterface'),
@@ -830,6 +881,7 @@ def manage_hdl_artifacts(app, env, docnames):
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-interfaces', directive_interfaces)
app.add_directive('hdl-regmap', directive_regmap)
diff --git a/docs/extensions/adi_hdl_static.py b/docs/extensions/adi_hdl_static.py
index 654963e66..8e80a45af 100644
--- a/docs/extensions/adi_hdl_static.py
+++ b/docs/extensions/adi_hdl_static.py
@@ -1,3 +1,8 @@
+###############################################################################
+## Copyright (C) 2022-2023 Analog Devices, Inc. All rights reserved.
+### SPDX short identifier: ADIBSD
+###############################################################################
+
class hdl_strings ():
access_type = {
'RO':{
diff --git a/docs/extensions/adi_links.py b/docs/extensions/adi_links.py
index 1f318b21c..40a11ae51 100644
--- a/docs/extensions/adi_links.py
+++ b/docs/extensions/adi_links.py
@@ -1,3 +1,8 @@
+###############################################################################
+## Copyright (C) 2022-2023 Analog Devices, Inc. All rights reserved.
+### SPDX short identifier: ADIBSD
+###############################################################################
+
from docutils import nodes
import subprocess
diff --git a/docs/library/spi_engine/axi_spi_engine.rst b/docs/library/spi_engine/axi_spi_engine.rst
index 583e25ec5..797e52484 100644
--- a/docs/library/spi_engine/axi_spi_engine.rst
+++ b/docs/library/spi_engine/axi_spi_engine.rst
@@ -63,8 +63,7 @@ Signal and Interface Pins
Interrupt output of the module. Is asserted when at least one of the
modules interrupt is pending and unmasked.
* - spi_clk
- - All ``spi_engine_ctrl`` signals and ``spi_resetn`` are
- synchronous to this clock.
+ - ``spi_resetn`` is synchronous to this clock.
* - spi_engine_ctrl
- :ref:`spi_engine control-interface` slave.
SPI Engine Control stream that contains commands and data for the
diff --git a/docs/sources/custom.css b/docs/sources/custom.css
index b3dda98f9..73db5d68f 100755
--- a/docs/sources/custom.css
+++ b/docs/sources/custom.css
@@ -6,15 +6,16 @@
0
calc(var(--sidebar-item-spacing-horizontal)/2);
padding: 0;
+ width: 11em;
+ margin-left: 2.25em;
}
.sidebar-brand::before {
content: "";
- display: inline-block;
- width: 100%;
- height: 4rem;
+ display: block;
+ height: 4.5em;
+ background-size: auto 5.625em;
background-image: url(HDL_logo.svg);
- background-size: auto 4rem;
- background-position: center;
+ background-position: -10em -.5em;
background-repeat: no-repeat;
}
.sidebar-brand-text {
@@ -63,6 +64,12 @@ td.description{
width: 45%;
font-size:.8em;
}
+#signal-and-interface-pins h3 {
+ font-weight: normal;
+}
+.table-wrapper {
+ overflow: visible;
+}
.collapsible {
border: 1px solid var(--color-table-border);
border-radius: .25em;
@@ -75,35 +82,44 @@ td.description{
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%;
- display: block;
- padding-left: .75em;
+ 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 {
- display: inline-block;
- padding-right: .25em;
+ 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: .75em 0;
+ margin: 0;
}
-.collapsible label .icon:before {
- content: '⮞';
- color: #666;
- transition: transform ease .125s, padding ease .125s;
- display: block;
- line-height: 1em;
- padding-right: .25em;
+.collapsible label, .collapsible div {
+ transition: box-shadow ease .25s;
}
-.collapsible_input:checked ~ label .icon:before {
- transform: rotate(90deg);
- padding-left: 4px;
+.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_input:checked ~ .collapsible_content {
height: 100%;
diff --git a/docs/user_guide/docs_guidelines.rst b/docs/user_guide/docs_guidelines.rst
index 9b4bdf656..a75997810 100644
--- a/docs/user_guide/docs_guidelines.rst
+++ b/docs/user_guide/docs_guidelines.rst
@@ -385,6 +385,39 @@ The ``:no-type-info:`` option is optional, and should **not** be included if it
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::