diff --git a/.gitignore b/.gitignore index a7cd63a4c..7f6f1b56f 100644 --- a/.gitignore +++ b/.gitignore @@ -102,6 +102,8 @@ library/**/bd/bd.tcl qdb tmp-clearbox *.bin +__pycache__ +_build .qsys_edit .github/CODEOWNERS .github/PULL_REQUEST_TEMPLATE.md diff --git a/docs/contributing/guidelines.rst b/docs/contributing/guidelines.rst index d744372fd..e7c142bb5 100644 --- a/docs/contributing/guidelines.rst +++ b/docs/contributing/guidelines.rst @@ -172,36 +172,47 @@ 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 \`` synthax, like external + links, but without the undescore in the end. + + Git role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Git role allows to create links to the Git repository with a shorter syntax. -The role syntax is :code:`:git-:\`:\``, for example, -:code:`:git-hdl:\`master:contributing/guidelines.rst\`` -is rendered as :git-hdl:`master:contributing/guidelines.rst`. -You can leave the branch blank to autofill the link with the current branch. +The role syntax is :code:`:git-repo:\`text \``, for example: -You can also do :code:`:git-:\`/\`` for a link to the root of the +* :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 `. + +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. + +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The part role creates links for a part to the Analog Devices website. +The part role creates links for a part to the Analog Devices Inc. website. -The role syntax is :code:`:part:\`:\``, for example, -:code:`:part:\`ad7175-2:AD7175-2\``. +The role syntax is :code:`:part:\`text \``, for example, +:code:`:part:\`AD7175-2 \``. Since links are case insensitive, you can also reduce it to -:code:`:part:\`AD7175-2\``, when *part_id* is the same as *part_name*. -It is rendered as :part:`AD7175-2`. +:code:`:part:\`AD7175-2\``, when *part_id* is the same as *text* and will render +as :part:`AD7175-2`. Datasheet role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The datasheet role creates links for a datasheet in the Analog Devices website. +The datasheet role creates links for a datasheet in the Analog Devices Inc. website. -The role syntax is :code:`:datasheet:\`:\``, for example, +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]`. @@ -216,29 +227,36 @@ by just copying the link in the table of contents. Dokuwiki role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The dokuwiki role creates links to the Analog Devices wiki website. -The role syntax is :code:`:dokuwiki:\`:\``, for example, -:code:`:dokuwiki:\`pulsar-adc-pmods:resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods\`` +The dokuwiki role creates links to the Analog Devices Inc. wiki website. +The role syntax is :code:`:dokuwiki:\`text \``, for example, +:code:`:dokuwiki:\`pulsar-adc-pmods \`` gets rendered as -:dokuwiki:`pulsar-adc-pmods:resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods`. +:dokuwiki:`pulsar-adc-pmods `. EngineerZone role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ez role creates links to the Analog Devices EngineerZone support website. -The role syntax is :code:`:ez:\`\``, for example, :code:`:ez:\`fpga\`` +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`. -Xilinx role +Vendor role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The xilinx role creates links to the Xilinx website. -The role syntax is :code:`:xilinx:\`:\``, for example, -:code:`:xilinx:\`Zynq-7000 SoC Overview:support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf\`` +The vendor role creates links to the vendor's website. +The role syntax is :code:`:vendor:\`text \``, for example, +:code:`:xilinx:\`Zynq-7000 SoC Overview \`` gets rendered -:xilinx:`Zynq-7000 SoC Overview:support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf`. +:xilinx:`Zynq-7000 SoC Overview `. -The name parameter is optional, if absent, the file name will be used as the name. +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` and `intel`. HDL parameters directive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/extensions/adi_links.py b/docs/extensions/adi_links.py index 6485f70be..6615e7280 100644 --- a/docs/extensions/adi_links.py +++ b/docs/extensions/adi_links.py @@ -8,15 +8,21 @@ dft_url_ez = 'https://ez.analog.com' dft_url_git = 'https://github.com/analogdevicesinc' dft_url_part = 'https://www.analog.com/products' dft_url_xilinx = 'https://www.xilinx.com' +dft_url_intel = 'https://www.intel.com' def get_url_config(name, inliner): app = inliner.document.settings.env.app - try: - if not eval("app.config.url_"+name): - raise AttributeError - except AttributeError as err: - raise ValueError(str(err)) - return eval("app.config.url_"+name) + return getattr(app.config, "url_"+name) + +def get_outer_inner(text): + """ + Extract 'outer ' 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=[]): @@ -32,10 +38,11 @@ def datasheet(): def dokuwiki(): def role(name, rawtext, text, lineno, inliner, options={}, content=[]): - path = text[text.find(':')+1:] - name = path[path.rfind('/')+1:] if text.find(':') in [0, -1] else text[0:text.find(':')] + 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, name, refuri=url, **options) + node = nodes.reference(rawtext, text, refuri=url, **options) return [node], [] return role @@ -58,28 +65,34 @@ def git(repo, alt_name): name = "ADI " + alt_name + " repository" node = nodes.reference(rawtext, name, refuri=url, **options) else: - branch = get_active_branch_name() if text.find(':') in [0, -1] else text[0:text.find(':')] - path = text[text.find(':')+1:] + 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[path.rfind('/')+1:] url = url + '/blob/' + branch + '/' + path - node = nodes.reference(rawtext, path[path.rfind('/')+1:], refuri=url, **options) + node = nodes.reference(rawtext, text, refuri=url, **options) return [node], [] return role def part(): def role(name, rawtext, text, lineno, inliner, options={}, content=[]): - part_name = text[text.find(':')+1:] - part_id = part_name if text.find(':') in [0, -1] else text[0:text.find(':')] + name, part_id = get_outer_inner(text) + if name is None: + name = part_id url = get_url_config('part', inliner) + '/' + part_id + '.html' - node = nodes.reference(rawtext, part_name, refuri=url, **options) + node = nodes.reference(rawtext, name, refuri=url, **options) return [node], [] return role -def xilinx(): +def vendor(vendor_name): def role(name, rawtext, text, lineno, inliner, options={}, content=[]): - name = text[text.rfind('/')+1:] if text.find(':') in [0, -1] else text[0:text.find(':')] - path = text[text.find(':')+1:] - url = get_url_config('xilinx', inliner) + '/' + path - node = nodes.reference(rawtext, name, refuri=url, **options) + 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) return [node], [] return role @@ -91,7 +104,8 @@ def setup(app): app.add_role("git-testbenches", git('testbenches', "Testbenches")) app.add_role("git-linux", git('linux', "Linux")) app.add_role("part", part()) - app.add_role("xilinx", xilinx()) + app.add_role("xilinx", vendor('xilinx')) + app.add_role("intel", vendor('intel')) app.add_config_value('url_datasheet', dft_url_datasheet, 'env') app.add_config_value('url_dokuwiki', dft_url_dokuwiki, 'env') @@ -99,6 +113,7 @@ def setup(app): 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_xilinx', dft_url_xilinx, 'env') + app.add_config_value('url_intel', dft_url_intel, 'env') return { 'version': '0.1', diff --git a/docs/library/axi_dmac/index.rst b/docs/library/axi_dmac/index.rst index 63ea4811a..9ffa2faa5 100644 --- a/docs/library/axi_dmac/index.rst +++ b/docs/library/axi_dmac/index.rst @@ -620,8 +620,8 @@ Software Support Analog Devices recommends to use the provided software drivers. -- :dokuwiki:`Analog Device AXI-DMAC DMA Controller Linux Driver: - resources/tools-software/linux-drivers/axi-dmac` +- :dokuwiki:`Analog Device AXI-DMAC DMA Controller Linux Driver + ` Known Issues -------------------------------------------------------------------------------- diff --git a/docs/library/spi_engine/index.rst b/docs/library/spi_engine/index.rst index 2d9a89b39..6a63a2e95 100644 --- a/docs/library/spi_engine/index.rst +++ b/docs/library/spi_engine/index.rst @@ -56,7 +56,7 @@ Interfaces Software -------------------------------------------------------------------------------- -* :dokuwiki:`Linux Driver:resources/tools-software/linux-drivers/spi/spi_engine`: +* :dokuwiki:`Linux Driver `: Linux driver for the SPI Engine framework. * :ref:`spi_engine instruction-format`: Overview of the SPI Engine Instruction format. @@ -68,25 +68,25 @@ This list contains cores that are not part of the core SPI engine framework but make use of its interfaces and are intend to be used together with the SPI engine framework. -* :dokuwiki:`util-sigma-delta-spi:resources/fpga/peripherals/util_sigma_delta_spi`: +* :dokuwiki:`util-sigma-delta-spi `: Helper module for interfacing ADCs from the Analog Devices Sigma-Delta family. Examples -------------------------------------------------------------------------------- -* :dokuwiki:`CN0363:resources/eval/user-guides/eval-cn0363-pmdz`: +* :dokuwiki:`CN0363 `: Colorimeter application using the :part:`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:resources/eval/user-guides/eval-cn0363-pmdz`: +* :dokuwiki:`CN0363 `: The AD7768-1 is a low power, high performance, Σ-Δ analog-to-digital converter (ADC). * :git-hdl:`master:projects/ad40xx_fmc` Evaluation Board for the AD4000 Series 16-/18-/20-Bit Precision SAR ADCs. -* :dokuwiki:`AD469x:resources/eval/user-guides/ad469x`: +* :dokuwiki:`AD469x `: 16-Bit, 16-Channel, 500 kSPS/1 MSPS, Easy Drive Multiplexed SAR ADC. -* :dokuwiki:`AD4630-24 / AD4030-24 / AD4630-16:resources/eval/user-guides/ad463x/hdl`: +* :dokuwiki:`AD4630-24 / AD4030-24 / AD4630-16 `: 16/24-Bit, 2 MSPS Single or Dual Channel SAR ADC. Additional Resources diff --git a/docs/library/spi_engine/tutorial.rst b/docs/library/spi_engine/tutorial.rst index c66cc37d0..1771fc011 100644 --- a/docs/library/spi_engine/tutorial.rst +++ b/docs/library/spi_engine/tutorial.rst @@ -13,7 +13,7 @@ Evaluating the target device The aim of this project is to provide support for a family of ADCs which come in the form of -:dokuwiki:`pulsar-adc-pmods:resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods`. +:dokuwiki:`pulsar-adc-pmods `. They all share the same interface and the same PCB, the differences being found in their performance. The table below offers a comparison between the timing parameters of the SPI interface for these devices. Using this table we can see @@ -67,8 +67,8 @@ 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 spi_engine.tcl -script :git-hdl:`master:library/spi_engine/scripts/spi_engine.tcl` +each IP individually or by using the function provided by the +:git-hdl:`master: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 @@ -264,7 +264,7 @@ Testbench -------------------------------------------------------------------------------- To check the overall performance of the design and also to expose any major -bugs, the system can be tested using a testbench (:git-testbenches:`main:`). +bugs, the system can be tested using a testbench from :git-testbenches:`/`. The testbench framework is designed to use the same bd.tcl as the actual project :git-testbenches:`main:pulsar_adc_pmdz/system_bd.tcl#L50` diff --git a/docs/library/template_framework/index.rst b/docs/library/template_framework/index.rst index b6b7233c7..e87ef98a1 100644 --- a/docs/library/template_framework/index.rst +++ b/docs/library/template_framework/index.rst @@ -35,13 +35,13 @@ Related IP Cores This list contains cores that are not part of the core {ip name} but make use of its interfaces and are intend to be used together with the {ip name}. -* :dokuwiki:`util-sigma-delta-spi:resources/fpga/peripherals/util_sigma_delta_spi`: +* :dokuwiki:`util-sigma-delta-spi `: Helper module for interfacing ADCs from the Analog Devices Sigma-Delta family. Examples -------------------------------------------------------------------------------- -* :dokuwiki:`CN0363:resources/eval/user-guides/eval-cn0363-pmdz`: +* :dokuwiki:`CN0363 `: Colorimeter application using the :part:`AD7175-2` Sigma-Delta ADC. Additional Resources diff --git a/docs/library/template_ip/index.rst b/docs/library/template_ip/index.rst index 321597004..8bcdf11dc 100644 --- a/docs/library/template_ip/index.rst +++ b/docs/library/template_ip/index.rst @@ -115,5 +115,5 @@ References * :git-hdl:`/`, :git-hdl:`library/axi_ad777x` library. * :git-linux:`/`. -* :xilinx:`Zynq-7000 SoC Overview:support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf`. -* :xilinx:`Zynq-7000 SoC Packaging and Pinout:support/documentation/user_guides/ug865-Zynq-7000-Pkg-Pinout.pdf`. +* :xilinx:`Zynq-7000 SoC Overview `. +* :xilinx:`Zynq-7000 SoC Packaging and Pinout `.