Skip to content

Commit 7b6dad9

Browse files
AlexandraTrifanAlexandraTrifan
committed
docs: add docs for new plugins: AD9084 and JESD Status.
Signed-off-by: AlexandraTrifan <alexandra.trifan@analog.com>
1 parent cb55f3b commit 7b6dad9

File tree

4 files changed

+307
-0
lines changed

4 files changed

+307
-0
lines changed

‎docs/plugins/ad9084/ad9084.rst

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
.. _ad9084:
2+
3+
AD9084
4+
========================================
5+
6+
Overview
7+
---------
8+
9+
The **AD9084** instrument for Scopy enables integration and control of the
10+
Apollo MxFE platform within the Scopy software environment. This plugin
11+
allows users to configure and interact with the AD9084 ADC/DAC.
12+
13+
Instrument Layout
14+
-----------------
15+
16+
.. image:: https://raw.githubusercontent.com/analogdevicesinc/scopy/refs/heads/doc_resources/resources/ad9084/ad9084_overview.png
17+
:align: center
18+
19+
Device name indicator
20+
^^^^^^^^^^^^^^^^^^^^^^^^
21+
22+
This is the device that will be used to control the AD9084/AD9088 device.
23+
The device name is also used to identify the device in the IIO device tree.
24+
Default value is **axi-ad9084-rx-hpc**.
25+
26+
RX/TX enable buttons
27+
^^^^^^^^^^^^^^^^^^^^^^^^
28+
29+
These buttons allow enabling or disabling the RX and TX chain view in the Scopy instrument.
30+
The actual RX/TX chain operation is not disabled/enabled, as the buttons only control the
31+
visibility of the RX and TX chain settings within the instrument interface.
32+
33+
Refresh button
34+
^^^^^^^^^^^^^^^^^^^^^^^^
35+
36+
This button will refresh the current configuration values of the AD9084/AD9088 device.
37+
It will update all the displayed values in the instrument, ensuring that the user sees
38+
the latest configuration.
39+
40+
Settings menu button
41+
^^^^^^^^^^^^^^^^^^^^^^^^
42+
43+
This button will open the settings menu, allowing users to configure various parameters
44+
of the AD9084/AD9088 device. The settings menu includes options for:
45+
46+
- **PFIR config**
47+
48+
Allows users to load a PFIR filter configuration file. Make sure the
49+
file has the correct format and compatible with the device.
50+
The plugin provides a default PFIR configuration file that can be used as a starting point.
51+
A file dialog will open in the default FIR filter files location.
52+
53+
- **CFIR config**
54+
55+
Allows users to load a CFIR filter configuration file. Make sure the
56+
file has the correct format and compatible with the device.
57+
The plugin provides a default CFIR configuration file that can be used as a starting point.
58+
A file dialog will open in the default FIR filter files location.
59+
60+
RX Chain settings
61+
^^^^^^^^^^^^^^^^^^^^^^^^
62+
63+
The RX Chain section is a scrollable area containing configuration options for all the
64+
RX channels of the device.
65+
66+
All the UI controls are interactive, displaying the state of the
67+
current operation, specifically a progress bar while the operation is in progress, becoming
68+
green or red based on the success or failure of the operation, respectively.
69+
At startup all UI elements are initialized with the current values from the device.
70+
71+
Each RX channel section includes the following information:
72+
73+
- **Channel indicator**: Displays the channel number (e.g., Channel 1, Channel 2, etc.).
74+
- **Channel label**: Indicates the FDDC/CDDC arrangement for the channel.
75+
- **Channel enable**: A checkbox to enable or disable the channel. When successfully disabled,
76+
the channel name size will be reduced to indicate that the channel is inactive.
77+
- **CFIR enable**: A checkbox to enable or disable the CFIR filter for the channel.
78+
- **CFIR profile**: A dropdown menu to select the CFIR profile for the channel.
79+
- **ADC Frequency**: Control the ADC frequency.
80+
The value is displayed in MHz and it is a shared value for all RX channels. Whenever
81+
the value is changed for one channel, a read operation is performed to update all the
82+
RX channels with the new value.
83+
- **NCO Frequency**
84+
- **NCO Phase**
85+
- **Main NCO Frequency**
86+
- **Main NCO Phase**
87+
- **Test Mode**
88+
- **Nyquist Zone**: A dropdown menu to select the Nyquist zone for the channel.
89+
- **Loopback Mode**
90+
91+
92+
TX Chain settings
93+
^^^^^^^^^^^^^^^^^^^^^^^^
94+
95+
The TX Chain section is a scrollable area containing configuration options for all the
96+
TX channels of the device.
97+
98+
All the UI controls are interactive, displaying the state of the
99+
current operation, specifically a progress bar while the operation is in progress, becoming
100+
green or red based on the success or failure of the operation, respectively.
101+
At startup all UI elements are initialized with the current values from the device.
102+
103+
Each TX channel section includes the following information:
104+
105+
- **Channel indicator**: Displays the channel number (e.g., Channel 1, Channel 2, etc.).
106+
- **Channel label**: Indicates the FDUC/CDUC arrangement for the channel.
107+
- **Channel enable**: A checkbox to enable or disable the channel. When successfully disabled,
108+
the channel name size will be reduced to indicate that the channel is inactive.
109+
- **CFIR enable**: A checkbox to enable or disable the CFIR filter for the channel.
110+
- **CFIR profile**: A dropdown menu to select the CFIR profile for the channel.
111+
- **DAC Frequency**: Control the DAC frequency.
112+
The value is displayed in MHz and it is a shared value for all TX channels. Whenever
113+
the value is changed for one channel, a read operation is performed to update all the
114+
TX channels with the new value.
115+
- **NCO Frequency**
116+
- **NCO Phase**
117+
- **Gain Scale**
118+
- **Test Tone Scale**
119+
- **Test Tone Enable**
120+
- **Main NCO Frequency**
121+
- **Main NCO Phase**
122+
- **Main Test Tone Scale**
123+
- **Main Test Tone Enable**

‎docs/plugins/ad9084/index.rst

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
.. _ad9084_index:
2+
3+
APOLLO
4+
========================================
5+
6+
Overview
7+
--------
8+
9+
The **AD9084** plugin for Scopy enables integration and control of the
10+
Apollo MxFE platform within the Scopy software environment. This plugin
11+
allows users to configure and interact with the AD9084 ADC/DAC.
12+
13+
Features
14+
--------
15+
- **Device Discovery:** Automatic detection of connected AD9084/AD9088 devices.
16+
- **Signal Acquisition:** Real-time streaming of I/Q data from the device.
17+
- **Device Configuration:** Set all the required configuration parameters.
18+
19+
Supported Devices
20+
-------------------
21+
22+
- **AD9084** (Apollo MxFE Quad, 16-Bit, 28GSPS RF DAC and Quad, 12-Bit, 20 GSPS RF ADC)
23+
- **AD9088** (Apollo MxFE Octal, 16-Bit, 16 GSPS RF DAC and Octal, 12-Bit, 8 GSPS RF ADC )
24+
- **Apollo MxFE** (with AD9084/AD9088)
25+
26+
Getting Started
27+
---------------
28+
29+
**Prerequisites**
30+
31+
- A supported Apollo MxFE device (AD9084/AD9088)
32+
- Scopy version 2.1.0 or later
33+
34+
**Using the Plugin**
35+
36+
.. note::
37+
The plugin can be tested using the embedded Apollo Emulated device.
38+
This emulated device allows users to explore the plugin features
39+
without needing a physical device.
40+
Choose **apollo** from the Emulator dropdown in Scopy.
41+
Check the IIO Emulator section for more details!
42+
43+
44+
.. note::
45+
Make sure the AD9084 Plugin is selected in the Scopy **Add device** dialog
46+
after selecting the device URI.
47+
48+
This plugin contains a single type of instrument, which will be instantiated
49+
for each compatible device found in the current IIO context:
50+
51+
.. toctree::
52+
:maxdepth: 3
53+
54+
ad9084
55+
56+
57+
Additional Resources
58+
---------------------
59+
60+
- `AD9084 Product Page <https://www.analog.com/en/products/ad9084.html>`_
61+
- `Apollo MxFE Product Page <https://www.analog.com/en/lp/001/apollo-mxfe.html>`_

‎docs/plugins/index.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ General IIO plugins
2222

2323
* :ref:`Register Map <registermap>`
2424

25+
* :ref:`JESD204 Status <jesd_status>`
26+
2527

2628
Application Specific plugins
2729

@@ -55,6 +57,9 @@ Application Specific plugins
5557
* :ref:`AD936X <ad936x>`
5658
* :ref:`AD936X Advanced <ad936x_advanced>`
5759

60+
* AD9084
61+
* :ref:`AD9084 <ad9084>`
62+
5863
Contents
5964
---------------------------------------------------------------------
6065

@@ -71,4 +76,6 @@ Contents
7176
pqm/index
7277
swiot1l/index
7378
ad936x/index
79+
ad9084/index
80+
jesdstatus/index
7481

‎docs/plugins/jesdstatus/index.rst

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
.. _jesd_status:
2+
3+
JESD Status
4+
========================================
5+
6+
Overview
7+
----------------------------------------
8+
9+
The JESD Status utility plugin provides a graphical interface to monitor the status of
10+
JESD204 in Scopy.
11+
It allows users to visualize the link and lane status of connected JESD204 devices and
12+
provides insights into the lane alignment and other relevant parameters.
13+
14+
Instrument Layout
15+
----------------------------------------
16+
17+
.. image:: https://raw.githubusercontent.com/analogdevicesinc/scopy/refs/heads/doc_resources/resources/jesdstatus/jesdstatus_overview.png
18+
:align: center
19+
20+
21+
Comparison with JESD204B Status Utility
22+
----------------------------------------
23+
24+
.. note::
25+
The Scopy JESD Status plugin is not a replacement for the existing JESD204B Status utility.
26+
27+
28+
.. note::
29+
Device compatibility is given by the presence of JESD204B IIO device in the IIO context.
30+
Make sure your build exposes the JESD204B IIO device in the device tree
31+
(`TX <https://wiki.analog.com/resources/tools-software/linux-drivers/jesd204/axi_jesd204_tx>`_
32+
and `RX <https://wiki.analog.com/resources/tools-software/linux-drivers/jesd204/axi_jesd204_rx>`_).
33+
34+
35+
The Scopy JESD Status plugin does not replace the existing JESD204B Status utility.
36+
It is a new tool that provides integration and status monitoring from the same
37+
software environment used for device configuration and control.
38+
39+
Check the additional resources section for more information on the JESD204B Status
40+
utility.
41+
42+
The main difference between the two tools is in the way of data and status retrieval.
43+
The JESD Status plugin uses the IIO context to retrieve the status of the JESD204 link
44+
and lanes, while the JESD204B Status utility uses the SYSFS interface to read the
45+
status of the JESD204 link and lanes.
46+
47+
The Scopy JESD Status plugin allows users to view the status of JESD204 devices
48+
alongside other IIO devices in Scopy.
49+
50+
51+
Detailed Status Information
52+
----------------------------------------
53+
54+
.. list-table::
55+
:header-rows: 1
56+
:widths: 20 40
57+
58+
* - What
59+
- Description
60+
* - Link state (enabled/disabled)
61+
- In case link state is disabled, that either means the link was never enabled
62+
or that an error occurred and the FSM rolled back and disabled the link.
63+
In the jesd204-fsm case this can be prevented by using the jesd204-ignore-errors;
64+
devicetree property when placed in the jesd204-fsm jesd204-top-device node.
65+
66+
* - Link status
67+
- Depending on the encoding JESD204B/C 8B10B/64B66B there can be
68+
different values RESET, WAIT, CGS, ILAS, etc., DATA Please see link layer
69+
documentation for the state machine: JESD204B/C Link Receive Peripheral \ JESD204B/C
70+
Link Transmit Peripheral In general DATA is the desired state indicating proper operation.
71+
72+
* - SYNC is asserted/deasserted (8B10B only)
73+
- State of the external SYNC signal
74+
* - SYSREF captured (Yes/No)
75+
- Yes indicates that a SYSREF pulse was captured
76+
* - SYSREF alignment error (Yes/No)
77+
- Yes indicates that a SYSREF event has been observed which was unaligned,
78+
in regards to the LMFC/LEMC period, to a previously recorded SYSREF event.
79+
80+
* - Lane rate
81+
- The SERDES lane rate / bit clock
82+
* - LMFC/LEMC rate
83+
- Frequency of the internal local multiframe clocks (LMFC)/ local-multiblock-clock (LEMC)
84+
* - Lane rate / (40/66)
85+
- Is equal to the desired Link Clock frequency
86+
* - Reported Link Clock
87+
- Is the Link Clock frequency which is reported by the common clock framework.
88+
If this rate is different from the desired Link Clock frequency,
89+
there is likely a problem. For example the clock provider wasn’t able to set
90+
the desired value.
91+
92+
* - Measured Link Clock
93+
- Is the measured Link Clock, using a frequency counter inside the Link Layer Peripheral.
94+
For proper operation desired, reported and measured frequency must match.
95+
96+
* - Desired Device Clock
97+
- In case this value is different from the Desired Link Clock, this indicates
98+
Dual Clock Operation required by the Gearbox. Please see Gearbox/Dual Clock Operation
99+
in the Link Layer Peripheral documentation: JESD204B/C Link Receive Peripheral \ JESD204B/C
100+
Link Transmit Peripheral The Device Clock is typically generated by the clock provider
101+
which also provides SYSREF.
102+
103+
* - Reported Device Clock
104+
- Is the Device Clock frequency which is reported by the common clock framework.
105+
If this rate is different from the desired Device Clock frequency, there is likely
106+
a problem. For example the clock provider wasn’t able to set the desired value.
107+
108+
* - Measured Device Clock
109+
- Is the measured Device Clock, using a frequency counter inside the Link Layer Peripheral.
110+
For proper operation desired, reported and measured frequency must match.
111+
112+
Additional Resources
113+
---------------------
114+
115+
- `JESD204 Status Utility <https://wiki.analog.com/resources/tools-software/linux-software/jesd_status>`_
116+
- `JESD204 Eye Scan <https://wiki.analog.com/resources/tools-software/linux-software/jesd_eye_scan>`_

0 commit comments

Comments
 (0)