diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index c1f5d4a08..39a287b1b 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -215,3 +215,6 @@ # Code owners for jesd204 IP /library/jesd204/ ionut.podgoreanu@analog.com adrian.costina@analog.com + +# Code owners for docs +/docs/ iulia.moldovan@analog.com jorge.marques@analog.com stanca.pop@analog.com laez.barbosa@analog.com diff --git a/docs/Containerfile b/docs/Containerfile deleted file mode 100644 index 082847e7e..000000000 --- a/docs/Containerfile +++ /dev/null @@ -1,36 +0,0 @@ -FROM registry.gitlab.com/islandoftex/images/texlive:TL2022-2022-12-25-full - -SHELL ["/bin/bash", "-c"] - -ENV HOME /root - -ARG DEBIAN_FRONTEND=noninteractive -ENV TZ=Europe/Bucharest - -ENV PROJ hdl-docs - -RUN apt-get update - -RUN apt-get -y --no-install-recommends install \ - python3 python3-venv python3-pip - -# To convert svg to pdf, used in sphinx->LaTeX->pdf pipeline -RUN apt-get -y --no-install-recommends install \ - librsvg2-bin - -RUN python3 -m venv /opt/venv - -COPY requirements.txt . - -RUN source /opt/venv/bin/activate ; \ - pip3 install -U pip - -RUN source /opt/venv/bin/activate ; \ - pip3 install wheel vext vext.gi - -RUN source /opt/venv/bin/activate ; \ - pip3 install -r requirements.txt ; \ - deactivate - -RUN mkdir -p /usr/local/bin ; \ - ln -s /opt/venv/bin/symbolator /usr/local/bin/symbolator diff --git a/docs/conf.py b/docs/conf.py index f3b05cdf8..c08410e5d 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,6 +32,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # -- Custom extensions configuration ------------------------------------------- hide_collapsible_content = True +validate_links = False # -- todo configuration ------------------------------------------------------- diff --git a/docs/extensions/adi_hdl_parser.py b/docs/extensions/adi_hdl_parser.py index f87cf4434..75c7954f3 100644 --- a/docs/extensions/adi_hdl_parser.py +++ b/docs/extensions/adi_hdl_parser.py @@ -75,16 +75,6 @@ def pretty_dep(string): return '' return string.replace("'MODELPARAM_VALUE.",'').replace("'",'') -def sanitized_bool(string): - string_ = string.strip().lower() - if string_ in ['1', 'true', 'yes', 'y']: - return True - elif string_ in ['0', 'false', 'no', 'n']: - return False - else: - logger.warning(f"Got malformed bool value {string}.") - return False - class directive_base(Directive): has_content = True add_index = True @@ -118,6 +108,16 @@ class directive_base(Directive): 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 @@ -380,7 +380,7 @@ class directive_regmap(directive_base): table = nodes.table(classes=['regmap']) table += tgroup - self.table_header(tgroup, ["DWORD", "BYTE", "BITS", "Name", "Type", "Default", "Description"]) + self.table_header(tgroup, ["DWORD", "BYTE", "BITS", "Name", "Type", "Default Value", "Description"]) rows = [] for reg in obj['regmap']: @@ -400,8 +400,8 @@ class directive_regmap(directive_base): ['', 'literal'], [f"[{field['bits']}]", 'literal'], [field['name'], 'literal'], - [field['rw'], 'paragraph'], - [field['default'], 'paragraph', ['default']], + [field['rw'], 'literal'], + [field['default'], 'default_value', ['default']], [field['description'], 'reST', ['description']], ]) @@ -817,7 +817,7 @@ def parse_hdl_regmap(reg, ctime): field_loc = data[fi + 1].strip() field_loc = field_loc.split(" ") field_bits = field_loc[0].replace("[", "").replace("]", "") - field_default = field_loc[1] if len(field_loc) > 1 else "NA" + 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() @@ -839,6 +839,11 @@ def parse_hdl_regmap(reg, ctime): 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, diff --git a/docs/extensions/adi_links.py b/docs/extensions/adi_links.py index 82e873da3..3257834c5 100644 --- a/docs/extensions/adi_links.py +++ b/docs/extensions/adi_links.py @@ -1,19 +1,28 @@ ############################################################################### -## Copyright (C) 2022-2023 Analog Devices, Inc. All rights reserved. +## Copyright (C) 2023 Analog Devices, Inc. All rights reserved. ### SPDX short identifier: ADIBSD ############################################################################### from docutils import nodes -import subprocess +from sphinx.util import logging +import subprocess +import asyncio +import aiohttp + +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_git = 'https://github.com/analogdevicesinc' -dft_url_part = 'https://www.analog.com' -dft_url_xilinx = 'https://www.xilinx.com' -dft_url_intel = 'https://www.intel.com' +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 @@ -23,9 +32,10 @@ git_repos = [ ['no-os', "no-OS"], ['libiio', "libiio"], ['scopy', "Scopy"], - ['iio-oscilloscope', "IIO Oscilloscope"] + ['iio-oscilloscope', "IIO Oscilloscope"], + ['pyadi-iio', "PyADI-IIO"] ] -vendors = ['xilinx', 'intel'] +vendors = ['xilinx', 'intel', 'mw'] def get_url_config(name, inliner): app = inliner.document.settings.env.app @@ -50,7 +60,9 @@ def datasheet(): 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(): @@ -60,16 +72,24 @@ def dokuwiki(): 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=[]): - url = get_url_config('ez', inliner) + '/' + text - node = nodes.reference(rawtext, "EngineerZone", refuri=url, **options) + 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 + return role def get_active_branch_name(): branch = subprocess.run(['git', 'branch', '--show-current'], capture_output=True) @@ -87,20 +107,24 @@ def git(repo, alt_name): branch = get_active_branch_name() if pos in [0, -1] else path[0:pos] path = path[pos+1:] if text is None: - text = path[path.rfind('/')+1:] + 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 part(): +def adi(): def role(name, rawtext, text, lineno, inliner, options={}, content=[]): - name, part_id = get_outer_inner(text) + name, adi_id = get_outer_inner(text) if name is None: - name = part_id - url = get_url_config('part', inliner) + '/' + part_id + '.html' + 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): @@ -110,27 +134,118 @@ def vendor(vendor_name): 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 + + 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 = total%step+2 if total%step != 0 else total%step+1 + 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("part", part()) + 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_part', dft_url_part, '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, diff --git a/docs/library/axi_dmac/index.rst b/docs/library/axi_dmac/index.rst index fb2df5b2e..0f8a261b0 100644 --- a/docs/library/axi_dmac/index.rst +++ b/docs/library/axi_dmac/index.rst @@ -56,7 +56,7 @@ Files * - Name - Description - * - :git-hdl:`master:library/axi_dmac/axi_dmac.v` + * - :git-hdl:`library/axi_dmac/axi_dmac.v` - Verilog source for the peripheral. Block Diagram diff --git a/docs/library/spi_engine/axi_spi_engine.rst b/docs/library/spi_engine/axi_spi_engine.rst index 797e52484..527c670bd 100644 --- a/docs/library/spi_engine/axi_spi_engine.rst +++ b/docs/library/spi_engine/axi_spi_engine.rst @@ -23,9 +23,9 @@ Files * - Name - Description - * - :git-hdl:`master:library/spi_engine/axi_spi_engine/axi_spi_engine.v` + * - :git-hdl:`library/spi_engine/axi_spi_engine/axi_spi_engine.v` - Verilog source for the peripheral. - * - :git-hdl:`master:library/spi_engine/axi_spi_engine/axi_spi_engine_ip.tcl` + * - :git-hdl:`library/spi_engine/axi_spi_engine/axi_spi_engine_ip.tcl` - TCL script to generate the Vivado IP-integrator project for the peripheral. Configuration Parameters diff --git a/docs/library/spi_engine/control-interface.rst b/docs/library/spi_engine/control-interface.rst index 925add1d1..30efbf0cc 100644 --- a/docs/library/spi_engine/control-interface.rst +++ b/docs/library/spi_engine/control-interface.rst @@ -30,7 +30,7 @@ Files * - Name - Description - * - :git-hdl:`master:library/spi_engine/interfaces/spi_engine_ctrl_rtl.xml` + * - :git-hdl:`library/spi_engine/interfaces/spi_engine_ctrl_rtl.xml` - Interface definition file Signal Pins diff --git a/docs/library/spi_engine/index.rst b/docs/library/spi_engine/index.rst index 6a63a2e95..88eba154c 100644 --- a/docs/library/spi_engine/index.rst +++ b/docs/library/spi_engine/index.rst @@ -75,14 +75,14 @@ Examples -------------------------------------------------------------------------------- * :dokuwiki:`CN0363 `: - Colorimeter application using the :part:`AD7175-2` Sigma-Delta ADC. + Colorimeter application using the :adi:`AD7175-2` Sigma-Delta ADC. * :dokuwiki:`resources/eval/user-guides/adaq7980-sdz`: A 16-bit ADC subsystem with four common signal processing and conditioning blocks. * :dokuwiki:`resources/tools-software/uc-drivers/ad5766`: 16-channel, 16-/12-bit, voltage output Digital-to-Analog Converters (DAC). * :dokuwiki:`CN0363 `: The AD7768-1 is a low power, high performance, Σ-Δ analog-to-digital converter (ADC). -* :git-hdl:`master:projects/ad40xx_fmc` +* :git-hdl:`projects/ad40xx_fmc` Evaluation Board for the AD4000 Series 16-/18-/20-Bit Precision SAR ADCs. * :dokuwiki:`AD469x `: 16-Bit, 16-Channel, 500 kSPS/1 MSPS, Easy Drive Multiplexed SAR ADC. diff --git a/docs/library/spi_engine/offload-control-interface.rst b/docs/library/spi_engine/offload-control-interface.rst index 7002d2813..7671d1b5a 100644 --- a/docs/library/spi_engine/offload-control-interface.rst +++ b/docs/library/spi_engine/offload-control-interface.rst @@ -16,7 +16,7 @@ Files * - Name - Description - * - :git-hdl:`master:library/spi_engine/interfaces/spi_engine_offload_ctrl_rtl.xml` + * - :git-hdl:`library/spi_engine/interfaces/spi_engine_offload_ctrl_rtl.xml` - Interface definition file Signal Pins diff --git a/docs/library/spi_engine/spi-bus-interface.rst b/docs/library/spi_engine/spi-bus-interface.rst index bb47a1ed5..1aad773c3 100644 --- a/docs/library/spi_engine/spi-bus-interface.rst +++ b/docs/library/spi_engine/spi-bus-interface.rst @@ -13,7 +13,7 @@ Files * - Name - Description - * - :git-hdl:`master:library/spi_engine/interfaces/spi_master_rtl.xml` + * - :git-hdl:`library/spi_engine/interfaces/spi_master_rtl.xml` - Interface definition file Signal Pins diff --git a/docs/library/spi_engine/spi_engine_execution.rst b/docs/library/spi_engine/spi_engine_execution.rst index 89877c9d9..6ef0fe884 100644 --- a/docs/library/spi_engine/spi_engine_execution.rst +++ b/docs/library/spi_engine/spi_engine_execution.rst @@ -19,9 +19,9 @@ Files * - Name - Description - * - :git-hdl:`master:library/spi_engine/spi_engine_execution/spi_engine_execution.v` + * - :git-hdl:`library/spi_engine/spi_engine_execution/spi_engine_execution.v` - Verilog source for the peripheral. - * - :git-hdl:`master:library/spi_engine/spi_engine_execution/spi_engine_execution_ip.tcl` + * - :git-hdl:`library/spi_engine/spi_engine_execution/spi_engine_execution_ip.tcl` - TCL script to generate the Vivado IP-integrator project for the peripheral. Configuration Parameters diff --git a/docs/library/spi_engine/spi_engine_interconnect.rst b/docs/library/spi_engine/spi_engine_interconnect.rst index e6924c162..bd31706ad 100644 --- a/docs/library/spi_engine/spi_engine_interconnect.rst +++ b/docs/library/spi_engine/spi_engine_interconnect.rst @@ -27,9 +27,9 @@ Files * - Name - Description - * - :git-hdl:`master:library/spi_engine/spi_engine_interconnect/spi_engine_interconnect.v` + * - :git-hdl:`library/spi_engine/spi_engine_interconnect/spi_engine_interconnect.v` - Verilog source for the peripheral. - * - :git-hdl:`master:library/spi_engine/spi_engine_interconnect/spi_engine_interconnect_ip.tcl` + * - :git-hdl:`library/spi_engine/spi_engine_interconnect/spi_engine_interconnect_ip.tcl` - TCL script to generate the Vivado IP-integrator project for the peripheral. diff --git a/docs/library/spi_engine/spi_engine_offload.rst b/docs/library/spi_engine/spi_engine_offload.rst index 0a9bb68bd..966fcea35 100644 --- a/docs/library/spi_engine/spi_engine_offload.rst +++ b/docs/library/spi_engine/spi_engine_offload.rst @@ -19,9 +19,9 @@ Files * - Name - Description - * - :git-hdl:`master:library/spi_engine/spi_engine_offload/spi_engine_offload.v` + * - :git-hdl:`library/spi_engine/spi_engine_offload/spi_engine_offload.v` - Verilog source for the peripheral. - * - :git-hdl:`master:library/spi_engine/spi_engine_offload/spi_engine_offload_ip.tcl` + * - :git-hdl:`library/spi_engine/spi_engine_offload/spi_engine_offload_ip.tcl` - TCL script to generate the Vivado IP-integrator project for the peripheral. diff --git a/docs/library/spi_engine/tutorial.rst b/docs/library/spi_engine/tutorial.rst index a12abc711..5b2056500 100644 --- a/docs/library/spi_engine/tutorial.rst +++ b/docs/library/spi_engine/tutorial.rst @@ -68,7 +68,7 @@ SPI Engine hierarchy instantiation The SPI Engine can be implemented in two ways, either by placing and connecting each IP individually or by using the function provided by the -:git-hdl:`master:library/spi_engine/scripts/spi_engine.tcl` script. +:git-hdl:`library/spi_engine/scripts/spi_engine.tcl` script. Using the script ensures that the correct connections are being made and that the IP cores will receive the correct parameter configuration since certain diff --git a/docs/library/template_framework/index.rst b/docs/library/template_framework/index.rst index e87ef98a1..1fa26300b 100644 --- a/docs/library/template_framework/index.rst +++ b/docs/library/template_framework/index.rst @@ -42,7 +42,7 @@ Examples -------------------------------------------------------------------------------- * :dokuwiki:`CN0363 `: - Colorimeter application using the :part:`AD7175-2` Sigma-Delta ADC. + Colorimeter application using the :adi:`AD7175-2` Sigma-Delta ADC. Additional Resources -------------------------------------------------------------------------------- diff --git a/docs/library/template_framework/interface.rst b/docs/library/template_framework/interface.rst index f65482d38..a9f2cab9b 100644 --- a/docs/library/template_framework/interface.rst +++ b/docs/library/template_framework/interface.rst @@ -19,7 +19,7 @@ Files * - Name - Description - * - :git-hdl:`master:library/spi_engine/interfaces/spi_engine_ctrl_rtl.xml` + * - :git-hdl:`library/spi_engine/interfaces/spi_engine_ctrl_rtl.xml` - Interface definition file Signal Pins diff --git a/docs/library/template_framework/template_module.rst b/docs/library/template_framework/template_module.rst index 1cf862fa6..56d5da509 100644 --- a/docs/library/template_framework/template_module.rst +++ b/docs/library/template_framework/template_module.rst @@ -17,9 +17,9 @@ Files * - Name - Description - * - :git-hdl:`master:library/spi_engine/spi_engine_execution/spi_engine_execution.v` + * - :git-hdl:`library/spi_engine/spi_engine_execution/spi_engine_execution.v` - Verilog source for the peripheral. - * - :git-hdl:`master:library/spi_engine/spi_engine_execution/spi_engine_execution_ip.tcl` + * - :git-hdl:`library/spi_engine/spi_engine_execution/spi_engine_execution_ip.tcl` - TCL script to generate the Vivado IP-integrator project for the peripheral. Configuration Parameters diff --git a/docs/library/template_ip/index.rst b/docs/library/template_ip/index.rst index 8bcdf11dc..95fb6ca4e 100644 --- a/docs/library/template_ip/index.rst +++ b/docs/library/template_ip/index.rst @@ -22,7 +22,7 @@ Files * - Name - Description - * - :git-hdl:`master:library/axi_dmac/axi_dmac.v` + * - :git-hdl:`library/axi_dmac/axi_dmac.v` - Verilog source for the peripheral. @@ -108,12 +108,12 @@ from the interface module. Software Guidelines -------------------------------------------------------------------------------- -Linux is supported also using :git-linux:`/`. +Linux is supported also using :git-linux:`master:/`. References -------------------------------------------------------------------------------- * :git-hdl:`/`, :git-hdl:`library/axi_ad777x` library. -* :git-linux:`/`. +* :git-linux:`master:/`. * :xilinx:`Zynq-7000 SoC Overview `. * :xilinx:`Zynq-7000 SoC Packaging and Pinout `. diff --git a/docs/projects/ad7616_sdz/index.rst b/docs/projects/ad7616_sdz/index.rst index a42997652..c5d2170f5 100644 --- a/docs/projects/ad7616_sdz/index.rst +++ b/docs/projects/ad7616_sdz/index.rst @@ -6,15 +6,15 @@ AD7616-SDZ HDL project Overview ------------------------------------------------------------------------------- -The :part:`AD7616` is a 16-bit, data acquisition system (DAS) that supports -dual simultaneous sampling of 16 channels. The :part:`AD7616` operates from a +The :adi:`AD7616` is a 16-bit, data acquisition system (DAS) that supports +dual simultaneous sampling of 16 channels. The :adi:`AD7616` operates from a single 5 V supply and can accommodate ±10 V, ±5 V, and ±2.5 V true bipolar input signals while sampling at throughput rates up to 1 MSPS per channel pair with 90 dB SNR. Higher SNR performance can be achieved with the on-chip oversampling mode; 92 dB for an oversampling ratio of 2. The input clamp protection circuitry can tolerate voltages up to ±20 V. -The :part:`AD7616` has 1 MΩ analog input impedance regardless of sampling +The :adi:`AD7616` has 1 MΩ analog input impedance regardless of sampling frequency. The single supply operation, on-chip filtering, and high input impedance eliminate the need for driver op-amps and external bipolar supplies. @@ -26,23 +26,23 @@ high-speed serial and parallel interfaces. Supported boards ------------------------------------------------------------------------------- -- :part:`EVAL-AD7616 ` +- :adi:`EVAL-AD7616 ` Supported devices ------------------------------------------------------------------------------- -- :part:`AD7616` +- :adi:`AD7616` Supported carriers ------------------------------------------------------------------------------- -- :xilinx:`ZedBoard` on FMC slot +- :xilinx:`ZedBoard ` on FMC slot - :xilinx:`ZC706` on FMC LPC slot Other required hardware ------------------------------------------------------------------------------- -- :part:`SDP-I-FMC ` +- :adi:`SDP-I-FMC ` Block design ------------------------------------------------------------------------------- @@ -117,31 +117,6 @@ LK40 A Onboard 5v0 power supply selected LK41 A Onboard 3v3 power supply selected ================== ========= ==================================== -IP list -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- :git-hdl:`AD_EDGE_DETECT ` -- :git-hdl:`AXI_AD7616 ` * -- :git-hdl:`AXI_CLKGEN ` -- :git-hdl:`AXI_DMAC ` -- :git-hdl:`AXI_HDMI_TX ` -- :git-hdl:`AXI_I2S_ADI ` -- :git-hdl:`AXI_PWM_GEN ` -- :git-hdl:`AXI_SPDIF_TX ` -- :git-hdl:`AXI_SPI_ENGINE ` ** -- :git-hdl:`AXI_SYSID ` -- :git-hdl:`SPI_ENGINE_EXECUTION ` ** -- :git-hdl:`SPI_ENGINE_INTERCONNECT ` ** -- :git-hdl:`SPI_ENGINE_OFFLOAD ` ** -- :git-hdl:`SYNC_BITS ` -- :git-hdl:`SYSID_ROM ` - -.. admonition:: Legend - :class: note - - - ``*`` instantiated only for SER_PAR_N=0 (parallel interface) - - ``**`` instantiated only for SER_PAR_N=1 (serial interface) - CPU/Memory interconnects addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -277,7 +252,7 @@ Building the HDL project The design is built upon ADI's generic HDL reference design framework. ADI does not distribute the bit/elf files of these projects so they -must be built from the sources available :git-hdl:`here `. To get +must be built from the sources available :git-hdl:`here `. To get the source you must `clone `__ the HDL repository, and then build the project as follows:. @@ -331,14 +306,14 @@ Systems related Hardware related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Product datasheet: :part:`AD7616` +- Product datasheet: :adi:`AD7616` - `UG-1012, Evaluation Board User Guide `__ HDL related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :git-hdl:`ad7616_sdz HDL project ` +- :git-hdl:`ad7616_sdz HDL project ` .. list-table:: :widths: 30 35 35 @@ -348,53 +323,53 @@ HDL related - Source code link - Documentation link * - AD_EDGE_DETECT - - :git-hdl:`library/common/ad_edge_detect.v ` + - :git-hdl:`library/common/ad_edge_detect.v` - * - AXI_AD7616 - - :git-hdl:`library/axi_ad7616 ` * + - :git-hdl:`library/axi_ad7616` * - :dokuwiki:`[Wiki] ` * - AXI_CLKGEN - - :git-hdl:`library/axi_dmac ` + - :git-hdl:`library/axi_clkgen` - :dokuwiki:`[Wiki] ` * - AXI_DMAC - - :git-hdl:`library/axi_dmac ` + - :git-hdl:`library/axi_dmac` - :ref:`here ` * - AXI_HDMI_TX - - :git-hdl:`library/axi_hdmi_tx ` + - :git-hdl:`library/axi_hdmi_tx` - :dokuwiki:`[Wiki] ` * - AXI_I2S_ADI - - :git-hdl:`library/axi_i2s_adi ` + - :git-hdl:`library/axi_i2s_adi` - * - AXI_PWM_GEN - - :git-hdl:`library/axi_pwm_gen ` + - :git-hdl:`library/axi_pwm_gen` - :dokuwiki:`[Wiki] ` * - AXI_SPDIF_TX - - :git-hdl:`library/axi_spdif_tx ` + - :git-hdl:`library/axi_spdif_tx` - * - AXI_SPI_ENGINE - - :git-hdl:`library/spi_engine/axi_spi_engine ` ** + - :git-hdl:`library/spi_engine/axi_spi_engine` ** - :ref:`here ` * - AXI_SYSID - - :git-hdl:`library/axi_sysid ` + - :git-hdl:`library/axi_sysid` - :dokuwiki:`[Wiki] ` * - AXI_SPI_ENGINE - - :git-hdl:`library/spi_engine/axi_spi_engine ` ** + - :git-hdl:`library/spi_engine/axi_spi_engine` ** - :ref:`here ` * - SPI_ENGINE_EXECUTION - - :git-hdl:`library/spi_engine/spi_engine_execution ` ** + - :git-hdl:`library/spi_engine/spi_engine_execution` ** - :ref:`here ` * - SPI_ENGINE_INTERCONNECT - - :git-hdl:`library/spi_engine/spi_engine_interconnect ` ** + - :git-hdl:`library/spi_engine/spi_engine_interconnect` ** - :ref:`here ` * - SPI_ENGINE_OFFLOAD - - :git-hdl:`library/spi_engine/spi_engine_offload ` ** + - :git-hdl:`library/spi_engine/spi_engine_offload` ** - :ref:`here ` * - SYNC_BITS - - :git-hdl:`library/util_cdc/sync_bits.v ` + - :git-hdl:`library/util_cdc/sync_bits.v` - * - SYSID_ROM - - :git-hdl:`library/sysid_rom ` - - + - :git-hdl:`library/sysid_rom` + - :dokuwiki:`[Wiki] ` .. admonition:: Legend :class: note diff --git a/docs/projects/ad9081_fmca_ebz/index.rst b/docs/projects/ad9081_fmca_ebz/index.rst index e10255aca..4e7d353d3 100644 --- a/docs/projects/ad9081_fmca_ebz/index.rst +++ b/docs/projects/ad9081_fmca_ebz/index.rst @@ -6,7 +6,7 @@ AD9081-FMCA-EBZ/AD9082-FMCA-EBZ HDL project Overview ------------------------------------------------------------------------------- -The :part:`AD9081-FMCA-EBZ ` / :part:`AD9082-FMCA-EBZ ` +The :adi:`AD9081-FMCA-EBZ ` / :adi:`AD9082-FMCA-EBZ ` reference design (also known as Single MxFE) is a processor based (e.g. Microblaze) embedded system. The design consists from a receive and a transmit chain. @@ -38,19 +38,19 @@ but must share the same reference clock. Supported boards ------------------------------------------------------------------------------- -- :part:`AD9081-FMCA-EBZ ` -- :part:`AD9082-FMCA-EBZ ` +- :adi:`AD9081-FMCA-EBZ ` +- :adi:`AD9082-FMCA-EBZ ` Supported devices ------------------------------------------------------------------------------- -- :part:`AD9081` -- :part:`AD9082` -- :part:`AD9177` -- :part:`AD9207` -- :part:`AD9209` -- :part:`AD9986` -- :part:`AD9988` +- :adi:`AD9081` +- :adi:`AD9082` +- :adi:`AD9177` +- :adi:`AD9207` +- :adi:`AD9209` +- :adi:`AD9986` +- :adi:`AD9988` Supported carriers ------------------------------------------------------------------------------- @@ -62,7 +62,7 @@ Supported carriers * - Evaluation board - Carrier - FMC slot - * - :part:`AD9081-FMCA-EBZ ` + * - :adi:`AD9081-FMCA-EBZ ` - `A10SoC`_ - FMCA * - @@ -88,7 +88,7 @@ Supported carriers * - Evaluation board - Carrier - FMC slot - * - :part:`AD9082-FMCA-EBZ ` + * - :adi:`AD9082-FMCA-EBZ ` - :xilinx:`VCK190` - FMC0 * - @@ -445,12 +445,12 @@ Building the HDL project The design is built upon ADI's generic HDL reference design framework. ADI does not distribute the bit/elf files of these projects so they -must be built from the sources available :git-hdl:`here `. To get +must be built from the sources available :git-hdl:`here `. To get the source you must `clone `__ the HDL repository. -Then go to the :git-hdl:`projects/ad9081_fmca_ebz ` +Then go to the :git-hdl:`projects/ad9081_fmca_ebz ` location and run the make command by typing in your command prompt: **Linux/Cygwin/WSL** @@ -692,18 +692,18 @@ Hardware related - Product datasheets: - - :part:`AD9081` - - :part:`AD9082` - - :part:`AD9988` - - :part:`AD9986` + - :adi:`AD9081` + - :adi:`AD9082` + - :adi:`AD9988` + - :adi:`AD9986` - `UG-1578, Device User Guide `__ - `UG-1829, Evaluation Board User Guide `__ HDL related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :git-hdl:`AD9081_FMCA_EBZ HDL project source code ` -- :git-hdl:`AD9082_FMCA_EBZ HDL project source code ` +- :git-hdl:`AD9081_FMCA_EBZ HDL project source code ` +- :git-hdl:`AD9082_FMCA_EBZ HDL project source code ` .. list-table:: :widths: 30 35 35 @@ -713,40 +713,40 @@ HDL related - Source code link - Documentation link * - AXI_DMAC - - :git-hdl:`library/axi_dmac ` + - :git-hdl:`library/axi_dmac` - :ref:`here ` * - AXI_SYSID - - :git-hdl:`library/axi_sysid ` + - :git-hdl:`library/axi_sysid` - :dokuwiki:`[Wiki] ` * - SYSID_ROM - - :git-hdl:`library/sysid_rom ` + - :git-hdl:`library/sysid_rom` - :dokuwiki:`[Wiki] ` * - UTIL_CPACK2 - - :git-hdl:`library/util_pack/util_cpack2 ` + - :git-hdl:`library/util_pack/util_cpack2` - :dokuwiki:`[Wiki] ` * - UTIL_UPACK2 - - :git-hdl:`library/util_pack/util_upack2 ` + - :git-hdl:`library/util_pack/util_upack2` - :dokuwiki:`[Wiki] ` * - UTIL_ADXCVR for AMD - - :git-hdl:`library/xilinx/util_adxcvr ` + - :git-hdl:`library/xilinx/util_adxcvr` - :dokuwiki:`[Wiki] ` * - AXI_ADXCVR for Intel - - :git-hdl:`library/intel/axi_adxcvr ` + - :git-hdl:`library/intel/axi_adxcvr` - :dokuwiki:`[Wiki] ` * - AXI_ADXCVR for AMD - - :git-hdl:`library/intel/axi_adxcvr ` + - :git-hdl:`library/xilinx/axi_adxcvr` - :dokuwiki:`[Wiki] ` * - AXI_JESD204_RX - - :git-hdl:`library/jesd204/axi_jesd204_rx ` + - :git-hdl:`library/jesd204/axi_jesd204_rx` - :dokuwiki:`[Wiki] ` * - AXI_JESD204_TX - - :git-hdl:`library/jesd204/axi_jesd204_tx ` + - :git-hdl:`library/jesd204/axi_jesd204_tx` - :dokuwiki:`[Wiki] ` * - JESD204_TPL_ADC - - :git-hdl:`library/jesd204/jesd204_tpl_adc ` + - :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_adc` - :dokuwiki:`[Wiki] ` * - JESD204_TPL_DAC - - :git-hdl:`library/jesd204/jesd204_tpl_dac ` + - :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_dac` - :dokuwiki:`[Wiki] ` - :dokuwiki:`[Wiki] Generic JESD204B block designs ` diff --git a/docs/projects/ad9783_ebz/index.rst b/docs/projects/ad9783_ebz/index.rst index 8d68c8086..dab92f367 100644 --- a/docs/projects/ad9783_ebz/index.rst +++ b/docs/projects/ad9783_ebz/index.rst @@ -6,7 +6,7 @@ AD9783-EBZ HDL project Overview ------------------------------------------------------------------------------- -The :part:`AD9783` includes pin-compatible, high dynamic range, dual +The :adi:`AD9783` includes pin-compatible, high dynamic range, dual digital-to-analog converters (DACs) with 16-bit resolution, and sample rates of up to 500 MSPS. @@ -14,20 +14,20 @@ The device includes specific features for direct conversion transmit applications, including gain and offset compensation, interfacing seamlessly with analog quadrature modulators. -The :part:`EVAL-AD9783` board is connected to the FPGA carrier through -:part:`AD-DAC-FMC`-ADP interposer board. +The :adi:`EVAL-AD9783` board is connected to the FPGA carrier through +:adi:`AD-DAC-FMC`-ADP interposer board. Supported boards ------------------------------------------------------------------------------- -- :part:`EVAL-AD9783` +- :adi:`EVAL-AD9783` Supported devices ------------------------------------------------------------------------------- -- :part:`AD9780` -- :part:`AD9781` -- :part:`AD9783` +- :adi:`AD9780` +- :adi:`AD9781` +- :adi:`AD9783` Supported carriers ------------------------------------------------------------------------------- @@ -53,7 +53,7 @@ Clock scheme - External clock source connected to J1 (CLOCK IN) - For maximum performance, give a 500 MHz clock -To make the connection between the :part:`EVAL-AD9783` evaluation board and +To make the connection between the :adi:`EVAL-AD9783` evaluation board and the carrier using SPI, some hardware changes must be done to the evaluation board. These are presented in detail in the **Connections and hardware changes** section. @@ -107,7 +107,7 @@ Building the HDL project The design is built upon ADI's generic HDL reference design framework. ADI does not distribute the bit/elf files of these projects so they -must be built from the sources available :git-hdl:`here `. To get +must be built from the sources available :git-hdl:`here `. To get the source you must `clone `__ the HDL repository, and then build the project as follows: @@ -159,16 +159,16 @@ Hardware related - Product datasheets: - - :part:`AD9780` - - :part:`AD9781` - - :part:`AD9783` - - :part:`EVAL-AD9783` - - :part:`AD-DAC-FMC`-ADP + - :adi:`AD9780` + - :adi:`AD9781` + - :adi:`AD9783` + - :adi:`EVAL-AD9783` + - :adi:`AD-DAC-FMC`-ADP HDL related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :git-hdl:`AD9783_EBZ HDL project source code ` +- :git-hdl:`AD9783_EBZ HDL project source code ` .. list-table:: :widths: 30 35 35 @@ -178,19 +178,19 @@ HDL related - Source code link - Documentation link * - AXI_AD9783 - - :git-hdl:`library/axi_ad9783 ` + - :git-hdl:`library/axi_ad9783` - :dokuwiki:`[Wiki] ` * - AXI_DMAC - - :git-hdl:`library/axi_dmac ` + - :git-hdl:`library/axi_dmac` - :ref:`here ` * - AXI_SYSID - - :git-hdl:`library/axi_sysid ` + - :git-hdl:`library/axi_sysid` - :dokuwiki:`[Wiki] ` * - SYSID_ROM - - :git-hdl:`library/sysid_rom ` + - :git-hdl:`library/sysid_rom` - :dokuwiki:`[Wiki] ` * - UTIL_UPACK2 - - :git-hdl:`library/util_pack/util_upack2 ` + - :git-hdl:`library/util_pack/util_upack2` - :dokuwiki:`[Wiki] ` Software related diff --git a/docs/projects/common/support.rst b/docs/projects/common/support.rst index 69131885a..67112424e 100644 --- a/docs/projects/common/support.rst +++ b/docs/projects/common/support.rst @@ -2,7 +2,7 @@ Support ------------------------------------------------------------------------------- `Analog Devices, Inc.`_ will provide **limited** online support for anyone using -the :git-hdl:`reference design ` with `ADI`_ components +the :git-hdl:`reference design <>` with `ADI`_ components via the :ez:`fpga` FPGA reference designs forum. For questions regarding the `ADI`_ Linux device drivers, device trees, etc. from @@ -10,7 +10,7 @@ our :git-linux:`Linux GitHub repository `, the team will offer support on the :ez:`linux-software-drivers` Linux software drivers forum. For questions concerning the `ADI`_ No-OS drivers, from our -:git-no-os:`No-OS GitHub repository `, the team will offer support +:git-no-os:`No-OS GitHub repository `, the team will offer support on the :ez:`microcontroller-no-os-drivers` microcontroller No-OS drivers forum. It should be noted, that the older the tools' versions and release diff --git a/docs/projects/template/index.rst b/docs/projects/template/index.rst index 052bf4b67..02002ca87 100644 --- a/docs/projects/template/index.rst +++ b/docs/projects/template/index.rst @@ -17,17 +17,17 @@ Supported boards **\*IF IT APPLIES**\ \* -- :part:`AD9081-FMCA-EBZ ` -- :part:`AD9082-FMCA-EBZ ` +- :adi:`AD9081-FMCA-EBZ ` +- :adi:`AD9082-FMCA-EBZ ` Supported devices ------------------------------------------------------------------------------- **\*EXAMPLES**\ \* -- :part:`AD9081` -- :part:`AD9177` -- :part:`AD9209` +- :adi:`AD9081` +- :adi:`AD9177` +- :adi:`AD9209` Supported carriers ------------------------------------------------------------------------------- @@ -42,7 +42,7 @@ another carrier. Take these tables as an example:**\ \* * - Evaluation board - Carrier - FMC slot - * - :part:`AD9081-FMCA-EBZ ` + * - :adi:`AD9081-FMCA-EBZ ` - `A10SoC`_ - FMCA * - @@ -68,7 +68,7 @@ another carrier. Take these tables as an example:**\ \* * - Evaluation board - Carrier - FMC slot - * - :part:`AD9082-FMCA-EBZ ` + * - :adi:`AD9082-FMCA-EBZ ` - :xilinx:`VCK190` - FMC0 * - @@ -445,7 +445,7 @@ Building the HDL project The design is built upon ADI's generic HDL reference design framework. ADI does not distribute the bit/elf files of these projects so they -must be built from the sources available :git-hdl:`here `. To get +must be built from the sources available :git-hdl:`here <>`. To get the source you must `clone `__ the HDL repository. @@ -635,10 +635,10 @@ Hardware related - Product datasheets: - - :part:`AD9081` - - :part:`AD9082` - - :part:`AD9988` - - :part:`AD9986` + - :adi:`AD9081` + - :adi:`AD9082` + - :adi:`AD9988` + - :adi:`AD9986` - `UG-1578, Device User Guide `__ - `UG-1829, Evaluation Board User Guide `__ @@ -655,8 +655,8 @@ HDL related **THIS IS JUST AN EXAMPLE** -- :git-hdl:`AD9081_FMCA_EBZ HDL project source code ` -- :git-hdl:`AD9082_FMCA_EBZ HDL project source code ` +- :git-hdl:`AD9081_FMCA_EBZ HDL project source code ` +- :git-hdl:`AD9082_FMCA_EBZ HDL project source code ` .. list-table:: :widths: 30 35 35 @@ -666,40 +666,40 @@ HDL related - Source code link - Documentation link * - AXI_DMAC - - :git-hdl:`library/axi_dmac ` + - :git-hdl:`library/axi_dmac` - :ref:`here ` * - AXI_SYSID - - :git-hdl:`library/axi_sysid ` + - :git-hdl:`library/axi_sysid` - :dokuwiki:`[Wiki] ` * - SYSID_ROM - - :git-hdl:`library/sysid_rom ` + - :git-hdl:`library/sysid_rom` - :dokuwiki:`[Wiki] ` * - UTIL_CPACK2 - - :git-hdl:`library/util_pack/util_cpack2 ` + - :git-hdl:`library/util_pack/util_cpack2` - :dokuwiki:`[Wiki] ` * - UTIL_UPACK2 - - :git-hdl:`library/util_pack/util_upack2 ` + - :git-hdl:`library/util_pack/util_upack2` - :dokuwiki:`[Wiki] ` * - UTIL_ADXCVR for AMD - - :git-hdl:`library/xilinx/util_adxcvr ` + - :git-hdl:`library/xilinx/util_adxcvr` - :dokuwiki:`[Wiki] ` * - AXI_ADXCVR for Intel - - :git-hdl:`library/intel/axi_adxcvr ` + - :git-hdl:`library/intel/axi_adxcvr` - :dokuwiki:`[Wiki] ` * - AXI_ADXCVR for AMD - - :git-hdl:`library/intel/axi_adxcvr ` + - :git-hdl:`library/xilinx/axi_adxcvr` - :dokuwiki:`[Wiki] ` * - AXI_JESD204_RX - - :git-hdl:`library/jesd204/axi_jesd204_rx ` + - :git-hdl:`library/jesd204/axi_jesd204_rx` - :dokuwiki:`[Wiki] ` * - AXI_JESD204_TX - - :git-hdl:`library/jesd204/axi_jesd204_tx ` + - :git-hdl:`library/jesd204/axi_jesd204_tx` - :dokuwiki:`[Wiki] ` * - JESD204_TPL_ADC - - :git-hdl:`library/jesd204/jesd204_tpl_adc ` + - :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_adc` - :dokuwiki:`[Wiki] ` * - JESD204_TPL_DAC - - :git-hdl:`library/jesd204/jesd204_tpl_dac ` + - :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_dac` - :dokuwiki:`[Wiki] ` - :dokuwiki:`[Wiki] Generic JESD204B block designs ` diff --git a/docs/regmap/adi_regmap_common.txt b/docs/regmap/adi_regmap_common.txt index 73455d72e..c79a6b8e0 100644 --- a/docs/regmap/adi_regmap_common.txt +++ b/docs/regmap/adi_regmap_common.txt @@ -169,8 +169,8 @@ REG 0x0007 REG_FPGA_INFO FPGA device information -:git-hdl:`master:library/scripts/adi_intel_device_info_enc.tcl` (Intel encoded values) -:git-hdl:`master:library/scripts/adi_xilinx_device_info_enc.tcl` (Xilinx encoded values) +:git-hdl:`library/scripts/adi_intel_device_info_enc.tcl` (Intel encoded values) +:git-hdl:`library/scripts/adi_xilinx_device_info_enc.tcl` (Xilinx encoded values) ENDREG FIELD diff --git a/docs/regmap/adi_regmap_dmac.txt b/docs/regmap/adi_regmap_dmac.txt index 5716a3477..b2263b955 100644 --- a/docs/regmap/adi_regmap_dmac.txt +++ b/docs/regmap/adi_regmap_dmac.txt @@ -330,7 +330,7 @@ X_LENGTH ENDREG FIELD -[23:0] {log2(max(\n''DMA_DATA_WIDTH_SRC'',\n''DMA_DATA_WIDTH_DEST''\n)/8){1'b1}} +[23:0] {log2(max(''DMA_DATA_WIDTH_SRC'', ''DMA_DATA_WIDTH_DEST'')/8){1'b1}} X_LENGTH RW Number of bytes to transfer - 1. diff --git a/docs/requirements.txt b/docs/requirements.txt index f55c82892..a00fccc2e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,6 +2,8 @@ sphinx lxml furo wavedrom +aiohttp +aiodns sphinxcontrib-wavedrom sphinxcontrib-svg2pdfconverter https://github.com/hdl/pyhdlparser/tarball/master diff --git a/docs/sources/custom.css b/docs/sources/custom.css index f71ab1124..e88b52fb8 100755 --- a/docs/sources/custom.css +++ b/docs/sources/custom.css @@ -60,7 +60,10 @@ table.regmap { table.regmap .caption-text{ font-size: 1rem; } -th, td.type, td.default { +td { + min-width: 4em; +} +th, td.type { white-space: nowrap; } td.description { @@ -130,11 +133,18 @@ td.description { transform: rotate(45deg); margin-top: -.5em; } +.collapsible_content { + overflow: auto; +} .collapsible_input:checked ~ .collapsible_content { height: 100%; opacity: 1; } .default { - min-width: 7em; + min-width: 5em; + max-width: 11em; line-break: anywhere; } +.default .pre { + white-space: pre; +} diff --git a/docs/user_guide/architecture.rst b/docs/user_guide/architecture.rst index c8f97bbd7..91f130577 100644 --- a/docs/user_guide/architecture.rst +++ b/docs/user_guide/architecture.rst @@ -15,7 +15,7 @@ subsystems: dependent** - it describes part of the ``system_wrapper`` module - located in - :git-hdl:`projects/common `; + :git-hdl:`projects/common `; one for each carrier - **Board design** --- description of what the **board** attached to @@ -147,7 +147,7 @@ CPU/Memory interconnects addresses The memory addresses that will be used by software are based on the HDL addresses of the IP register map, to which an offset is added, depending on the architecture of the used FPGA (see also :git-hdl:`ad_cpu_interconnect -procedure `; architecture is +procedure `; architecture is specified by ``sys_zynq`` variable, for AMD FPGAs). **Zynq-7000 and 7 Series** @@ -200,7 +200,7 @@ HDMI There is HDMI support for all the carriers which are using the ADV7511 as HDMI transmitter. The HDMI transmitter core can be found -`here `__. +:git-hdl:`here `. GPIOs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/user_guide/build_hdl.rst b/docs/user_guide/build_hdl.rst index 17d89a830..6a8ae611b 100644 --- a/docs/user_guide/build_hdl.rst +++ b/docs/user_guide/build_hdl.rst @@ -34,10 +34,10 @@ HDL project from the repository: #. The proper Vivado/Quartus version can be found in: - Starting with ``hdl_2021_r1`` release branch: - :git-hdl:`master:scripts/adi_env.tcl` + :git-hdl:`scripts/adi_env.tcl` - For ``hdl_2019_r2`` and older: - :git-hdl:`hdl/projects/scripts/adi_project_xilinx.tcl ` for Vivado, and - :git-hdl:`hdl/projects/scripts/adi_project_intel.tcl ` for Quartus. + :git-hdl:`hdl/projects/scripts/adi_project_xilinx.tcl ` for Vivado, and + :git-hdl:`hdl/projects/scripts/adi_project_intel.tcl ` for Quartus. #. Download the tools from the following links: @@ -100,7 +100,7 @@ Setup the HDL repository These designs are built upon ADI's generic HDL reference designs framework. ADI does not distribute the bit/elf files of these projects so they -must be built from the sources available :git-hdl:`here `. To get +must be built from the sources available :git-hdl:`here `. To get the source you must `clone `__ the HDL repository. @@ -126,8 +126,8 @@ to the :ref:`git_repository` section for more details. performance, you must clone your hdl repository in the WSL file system. For example: (:code:`\\\\wsl.localhost\\Ubuntu\\home\\username\\hdl`) -The above command clones the 'default' branch, which is the 'master' for -HDL. The 'master' branch always points to the latest stable release +The above command clones the 'default' branch, which is the 'main' for +HDL. The 'main' branch always points to the latest stable release branch, but it also has features **that are not fully tested**. If you want to switch to any other branch you need to checkout that branch: diff --git a/docs/user_guide/docs_guidelines.rst b/docs/user_guide/docs_guidelines.rst index 019c6b72d..07ffd7718 100644 --- a/docs/user_guide/docs_guidelines.rst +++ b/docs/user_guide/docs_guidelines.rst @@ -17,7 +17,7 @@ Templates are available: * :git-hdl:`docs/library/template_ip` (:ref:`rendered `). * :git-hdl:`docs/library/template_framework` (:ref:`rendered `). -* :git-hdl:`docs/projects/template_project` (:ref:`rendered `). +* :git-hdl:`docs/projects/template` (:ref:`rendered `). Remove the ``:orphan:`` in the first line, it is to hide the templates from the `TOC tree `_. @@ -151,13 +151,12 @@ it is not recommended. Third-party directives and roles -------------------------------------------------------------------------------- -Third-party tools are used to expand Sphinx functionality, for example, to -generate component diagrams. +Third-party tools are used to expand Sphinx functionality, if you haven't already, +do: -.. tip:: +.. code:: bash - Check :git-hdl:`docs/Containterfile` for a recipe to install these - tools, either in the host or in a container. + pip install -r requirements.txt Symbolator directive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -183,37 +182,53 @@ Color role To print text in red or green, use :code:`:red:\`text\`` and :code:`:green:\`text\``. -Git role +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 \``, for example: -* :code:`:git-hdl:\`master:docs/contributing/guidelines.rst\`` - renders as :git-hdl:`master:docs/contributing/guidelines.rst`. -* :code:`:git-hdl:\`Guidelines \`` - renders as :git-hdl:`Guidelines `. +* :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 \`` + renders as :git-hdl:`Guidelines `. -The branch field is optional and will be filled with the current branch. -The text field is optional and will be filled with the file or directory name. +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:`/`. -Part role -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ADI role +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -The part role creates links for a part to the Analog Devices Inc. website. +The adi role creates links for a webpage to the Analog Devices Inc. website. -The role syntax is :code:`:part:\`text \``, for example, -:code:`:part:\`AD7175-2 \``. +The role syntax is :code:`:adi:\`text \``, for example, +:code:`:adi:\`AD7175-2 \``. Since links are case insensitive, you can also reduce it to -:code:`:part:\`AD7175-2\``, when *part_id* is the same as *text* and will render -as :part:`AD7175-2`. +: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. @@ -230,7 +245,7 @@ by just copying the link in the table of contents. figure number! Dokuwiki role -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ The dokuwiki role creates links to the Analog Devices Inc. wiki website. The role syntax is :code:`:dokuwiki:\`text \``, for example, @@ -239,7 +254,7 @@ gets rendered as :dokuwiki:`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\`` @@ -250,7 +265,7 @@ 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 \``, for example, @@ -265,18 +280,19 @@ 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` and `intel`. +Supported vendors are: ``xilinx`` (AMD Xilinx), ``intel`` (Intel Altera) and +``mw`` (MathWorks). HDL parameters directive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The HDL parameters directive gets information parsed from *component.xml* library -and generates a table with the IP parameters. +The HDL parameters directive gets information parsed from IP-XACT (*component.xml*) +library and generates a table with the IP parameters. .. note:: - The *component.xml* files are generated by Vivado during the library build - and not by the documentation tooling. + The IP-XACT files are generated by Vivado during the library build and not by + the documentation tooling. The directive syntax is: @@ -425,8 +441,12 @@ Notice how you can use any Sphinx syntax, even nest other directives. Global options for HDL directives ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the `hide_collapsible_content` to set the default state of the collapsibles, -if you set to False, they be expanded by default. +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/user_guide/git_repository.rst b/docs/user_guide/git_repository.rst index 3d72646e8..32a117986 100644 --- a/docs/user_guide/git_repository.rst +++ b/docs/user_guide/git_repository.rst @@ -162,7 +162,7 @@ Repository releases and branches ------------------------------------------------------------------------------- The repository may contain multiple branches and tags. The -:git-hdl:`master ` branch +:git-hdl:`main ` branch is the development branch (latest sources, but not stable). If you check out this branch, some builds may fail. If you are not into any kind of experimentation, you should only check out one of the release branch. @@ -173,7 +173,7 @@ All our release branches have the following naming convention: ADI does two releases each year when all the projects get an update to support the latest tools and get additional new features. \*\* The -master branch is always synchronized with the latest release.*\* If you +main branch is always synchronized with the latest release.*\* If you are in doubt, ask us on :ez:`fpga`. .. note:: @@ -183,7 +183,7 @@ are in doubt, ask us on :ez:`fpga`. https://github.com/analogdevicesinc/hdl/releases - The latest version of tools used on master can be found at: - :git-hdl:`master:scripts/adi_env.tcl` (*required_vivado_version* and + The latest version of tools used on main can be found at: + :git-hdl:`scripts/adi_env.tcl` (*required_vivado_version* and *required_quartus_version* variables). For Intel Quartus Standard, the version is specified in each project that uses it, depending on the carrier. diff --git a/docs/user_guide/hdl_coding_guideline.rst b/docs/user_guide/hdl_coding_guideline.rst index 73c0983fd..eb6ad436c 100755 --- a/docs/user_guide/hdl_coding_guideline.rst +++ b/docs/user_guide/hdl_coding_guideline.rst @@ -316,7 +316,7 @@ to the last parenthesis of the last port. **A10.3** -Commented parts of code **must** not be added to the master +Commented parts of code **must** not be added to the main branch (i.e if, case, module instances, etc). **A11** diff --git a/docs/user_guide/introduction.rst b/docs/user_guide/introduction.rst index 5e4b3c016..622bdb9bf 100644 --- a/docs/user_guide/introduction.rst +++ b/docs/user_guide/introduction.rst @@ -7,10 +7,10 @@ The main purpose of this user guide is to help the user understand and use (modify or otherwise) the HDL resources provided by `Analog Devices, Inc.`_, and to provide advices and instructions for using these resources. These resources are found on the GitHub, the -:git-hdl:`HDL repository `. +:git-hdl:`/`. After reading this guide, the user should be able to build a specific project -from the :git-hdl:`HDL repository ` and be able to modify +from the :git-hdl:`/` and be able to modify (if so desire) the digital data path implemented in the FPGA. Furthermore, all ADI developed and supported IPs are presented in detail. diff --git a/docs/user_guide/porting_project.rst b/docs/user_guide/porting_project.rst index 137349b8c..1e007b2cb 100644 --- a/docs/user_guide/porting_project.rst +++ b/docs/user_guide/porting_project.rst @@ -83,7 +83,7 @@ components of it. The user should look at it as a suggestion only. .. tip:: - In :git-hdl:`projects/common `/ + In :git-hdl:`projects/common `/ you can find templates for the *system_top.v*, *Makefile*, etc. to help you when creating a new project. diff --git a/docs/user_guide/releases.rst b/docs/user_guide/releases.rst index d6b348693..5938ced57 100644 --- a/docs/user_guide/releases.rst +++ b/docs/user_guide/releases.rst @@ -66,7 +66,7 @@ Release branches - AMD Xilinx - Release notes - List of supported projects and IP cores - * - :git-hdl:`master` + * - :git-hdl:`main ` - Quartus Pro 23.2 - Vivado 2023.1 - @@ -145,13 +145,13 @@ When Intel or AMD have a new release, we usually follow them and update our tools in a timely manner. Changing the version of tool used on a branch is done by updating the -git-hdl:`adi_env.tcl ` script. +git-hdl:`adi_env.tcl ` script. If the tool version is not the one you want to use, keep in mind that when making a setup, you will have to build the software files with the same version, otherwise you might encounter problems in your setup. -For example, you want to use an older version of Vivado on the master branch +For example, you want to use an older version of Vivado on the main branch which uses a newer one. Then you will need to manually build the software -files from the master branch, with the same version of Vitis too. Or for +files from the main branch, with the same version of Vitis too. Or for Linux, to use the proper version of CROSS_COMPILE, etc.