docs: add docs/library/cn0363/* specific IPs #1550

caosjr · 2025-01-02T18:21:06Z

Adds documentation for the CN0363 specific IPs:

CN0363 DMA Sequencer;
CN0363 Phase Data Sync.

PR Description

Please replace this comment with summary, motivation and context of the changes.
List any dependencies required for this change.

You can check the checkboxes below by inserting a 'x' between square brackets
(without any other characters or spaces) or just check them after publishing the PR.

If there is a breaking change, specify dependent PRs in description and
try to push all related PRs at the same time.

PR Type

Bug fix (change that fixes an issue)
New feature (change that adds new functionality)
Breaking change (has dependencies in other repos or will cause CI to fail)

PR Checklist

I have followed the code style guidelines
I have performed a self-review of changes
I have compiled all hdl projects and libraries affected by this PR
I have tested in hardware affected projects, at least on relevant boards
I have commented my code, at least hard-to-understand parts
I have signed off all commits from this PR
I have updated the documentation (wiki pages, ReadMe files, Copyright etc)
I have not introduced new Warnings/Critical Warnings on compilation
I have added new hdl testbenches or updated existing ones

Adds documentation for the CN0363 specific IPs: - CN0363 DMA Sequencer; - CN0363 Phase Data Sync. Signed-off-by: Carlos Souza <[email protected]>

gastmaier

Quick review done using the GitHub GUI

docs/library/cn0363/cn0363_phase_data_sync/index.rst

docs/library/cn0363/index.rst

fixes some cosmetic changes Signed-off-by: Carlos Souza <[email protected]>

Signed-off-by: Jorge Marques <[email protected]>

Remove trailing whitespace. Use local project ref. Fix leading backslash. Rename ip labels. Signed-off-by: Jorge Marques <[email protected]>

Mostly better PDF output. Signed-off-by: Jorge Marques <[email protected]>

gastmaier

Additional review now using the proper tools...

Please do not commit trailing whitespace.
I sent patches privately to help applying the requested changes.

gastmaier · 2025-01-09T15:28:44Z

docs/library/cn0363/cn0363_phase_data_sync/index.rst

@@ -0,0 +1,97 @@
+.. _cn0363_phase_data_sync:


When you have plain pages, without additional resources, you can include in the parent simply as

index.rst cn0363_dma_sequencer.rst cn0363_phase_data_sync.rst

Remember, the documentation is highly hierarchical, so docs/library/cn0363/cn0363_phase_data_sync/index.rst ends up being redundant.

gastmaier · 2025-01-09T15:31:21Z

docs/library/cn0363/index.rst

+.. toctree::
+   :maxdepth: 2
+
+   CN0363 DMA Sequencer <cn0363_dma_sequencer/index>
+   CN0363 Phase Data Sync <cn0363_phase_data_sync/index>


With my suggestion, this could be simply:

.. toctree:: :maxdepth: 2 :glob: *

gastmaier · 2025-01-09T15:33:57Z

docs/library/cn0363/cn0363_phase_data_sync/index.rst

@@ -0,0 +1,97 @@
+.. _cn0363_phase_data_sync:
+
+CN0363 Phase Data Sync FPGA Peripheral


CN0363 Phase Data Sync or Phase Data Sync

On my side I want to add to the theme the level navigation on top, which completely removes the desire of providing a "full name" for the page, like in the developer.analog.com :

(change included in the review commit)

gastmaier · 2025-01-09T15:36:33Z

docs/library/cn0363/cn0363_dma_sequencer/index.rst

@@ -0,0 +1,104 @@
+.. _cn0363_dma_sequencer:
+
+CN0363 DMA Sequencer FPGA Peripheral


Just CN0363 DMA Sequencer

(change included in the review commit)

gastmaier · 2025-01-09T15:37:10Z

docs/library/cn0363/cn0363_dma_sequencer/index.rst

+.. hdl-component-diagram::
+
+The CN0363 Sequencer FPGA Peripheral is part of the 
+:dokuwiki:`CN0363 HDL project documentation <resources/eval/user-guides/eval-cn0363-pmdz/reference_hdl>` 


this page already exists in our repo. (change included in the review commit)

I see however that the wiki page seems to be more complete, could you work on improving the imported one?

gastmaier · 2025-01-09T15:44:41Z

docs/library/cn0363/cn0363_phase_data_sync/index.rst

+    * - :git-hdl:`/library/cn0363/cn0363_phase_data_sync/cn0363_phase_data_sync.v`
+      - Verilog source for the peripheral.
+    * - :git-hdl:`/library/cn0363/cn0363_phase_data_sync/cn0363_phase_data_sync_ip.tcl`


leading backslash on git-hdl
(change included in the review commit)

gastmaier · 2025-01-09T15:52:52Z

docs/library/cn0363/cn0363_dma_sequencer/index.rst

+More Information
+--------------------------------------------------------------------------------
+
+-  :dokuwiki:`[Wiki] CN0363 HDL project documentation <resources/eval/user-guides/eval-cn0363-pmdz/reference_hdl>`


Link local doc (change included in the review commit)

gastmaier · 2025-01-09T15:53:31Z

docs/library/cn0363/cn0363_phase_data_sync/index.rst

+More Information
+--------------------------------------------------------------------------------
+
+- :ref:`EVAL-CN0363-PMDZ HDL reference design <cn0363>`


Here you used the local ref

gastmaier · 2025-01-09T15:58:33Z

docs/library/cn0363/index.rst

+
+CN0363 library comprises two IPs: 
+
+- **CN0363 DMA Sequencer**;


; is not used in lists.

gastmaier · 2025-01-09T15:59:06Z

docs/library/cn0363/index.rst

+Contents
+--------
+


This is useless, better ref the Contents list above and leave the toctree hidden.

gastmaier · 2025-01-09T16:18:59Z

output.pdf
Example unified doc after patches

gastmaier

The page does not fully follow the template https://github.com/analogdevicesinc/hdl/blob/main/docs/library/template_ip/index.rst?plain=1 .
It is important to follow the template, one handy trick of the doc is to cycle the pages anchored on a particular section using Ctrl+Alt+Shift+Left/Right so we can "batch" check on particular section.

gastmaier · 2025-01-10T09:42:23Z

docs/library/cn0363/cn0363_phase_data_sync.rst

+      - TCL script to generate the Vivado IP-integrator project for the
+        peripheral.
+
+Signal and Interface Pins


Interface

gastmaier · 2025-01-10T09:42:40Z

docs/library/cn0363/cn0363_dma_sequencer.rst

+      - TCL script to generate the Vivado IP-integrator project for the
+        peripheral.
+
+Signal and Interface Pins


Interface

gastmaier · 2025-01-10T09:43:56Z

docs/library/cn0363/cn0363_dma_sequencer.rst

+      - Output
+      - Reset signal for the processing pipeline
+
+Theory of Operation


Detailed Description is more used.

gastmaier · 2025-01-10T09:44:04Z

docs/library/cn0363/cn0363_phase_data_sync.rst

+      - The overflow signal is asserted if a new sample arrives before the
+        previous one has been consumed.
+
+Theory of Operation


Detailed Description is more used.

gastmaier · 2025-01-10T09:44:25Z

docs/library/cn0363/cn0363_phase_data_sync.rst

+is inserted into the processing pipeline after the reset belongs to the first
+channel.
+
+More Information


References

gastmaier · 2025-01-10T09:44:30Z

docs/library/cn0363/cn0363_dma_sequencer.rst

+discarded. This allows an application to select which data channels it wants to
+capture.
+
+More Information


References

gastmaier · 2025-01-10T09:44:50Z

docs/library/cn0363/cn0363_dma_sequencer.rst

+bit is set the channel is sent to the ``dma_wr`` interface, otherwise it is
+discarded. This allows an application to select which data channels it wants to
+capture.
+


Software Support section?

gastmaier · 2025-01-10T09:44:56Z

docs/library/cn0363/cn0363_phase_data_sync.rst

+resets the channel swap detection logic and makes sure that the next sample that
+is inserted into the processing pipeline after the reset belongs to the first
+channel.
+


Software Support section?

docs: add docs/library/cn0363/* specific IPs

79c31de

Adds documentation for the CN0363 specific IPs: - CN0363 DMA Sequencer; - CN0363 Phase Data Sync. Signed-off-by: Carlos Souza <[email protected]>

caosjr requested review from IuliaCMoldovan, gastmaier, StancaPop and LBFFilho as code owners January 2, 2025 18:21

gastmaier requested changes Jan 7, 2025

View reviewed changes

docs/library/cn0363/cn0363_phase_data_sync/index.rst Outdated Show resolved Hide resolved

docs/library/cn0363/index.rst Outdated Show resolved Hide resolved

caosjr and others added 4 commits January 7, 2025 22:04

fix: inserted description for the CN0363 library

a72e6e6

fixes some cosmetic changes Signed-off-by: Carlos Souza <[email protected]>

fix: docs: cn0363: Wrong project in label

15c5afa

Signed-off-by: Jorge Marques <[email protected]>

review: docs: cn0363

d259a9a

Remove trailing whitespace. Use local project ref. Fix leading backslash. Rename ip labels. Signed-off-by: Jorge Marques <[email protected]>

review: docs: cn0363: Rework structure

22fa097

Mostly better PDF output. Signed-off-by: Jorge Marques <[email protected]>

gastmaier requested changes Jan 9, 2025

View reviewed changes

gastmaier requested changes Jan 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add docs/library/cn0363/* specific IPs #1550

docs: add docs/library/cn0363/* specific IPs #1550

caosjr commented Jan 2, 2025

gastmaier left a comment

gastmaier left a comment

gastmaier Jan 9, 2025

gastmaier Jan 9, 2025

gastmaier Jan 9, 2025

gastmaier Jan 9, 2025

gastmaier Jan 9, 2025

gastmaier Jan 9, 2025

gastmaier Jan 9, 2025

gastmaier Jan 9, 2025

gastmaier Jan 9, 2025

gastmaier Jan 9, 2025

gastmaier commented Jan 9, 2025

gastmaier left a comment

gastmaier Jan 10, 2025

gastmaier Jan 10, 2025

gastmaier Jan 10, 2025

gastmaier Jan 10, 2025

gastmaier Jan 10, 2025

gastmaier Jan 10, 2025

gastmaier Jan 10, 2025

gastmaier Jan 10, 2025

		@@ -0,0 +1,97 @@
		.. _cn0363_phase_data_sync:

		CN0363 Phase Data Sync FPGA Peripheral

		@@ -0,0 +1,104 @@
		.. _cn0363_dma_sequencer:

		CN0363 DMA Sequencer FPGA Peripheral


		CN0363 library comprises two IPs:

		- CN0363 DMA Sequencer;

		Contents
		--------

docs: add docs/library/cn0363/* specific IPs #1550

Are you sure you want to change the base?

docs: add docs/library/cn0363/* specific IPs #1550

Conversation

caosjr commented Jan 2, 2025

PR Description

PR Type

PR Checklist

gastmaier left a comment

Choose a reason for hiding this comment

gastmaier left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gastmaier commented Jan 9, 2025

gastmaier left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment