deploy: 092e4aa

jitter_docs/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: e656c0e2ef0a2c6be53b444d415db12e
+tags: 645f666f9bcd5a90fca523b33c5a78b7

jitter_docs/_sources/developer/explanations/decisions.rst.txt

@@ -0,0 +1,17 @@
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0. If a copy of the MPL was not distributed with this
+.. file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+Architectural Decision Records
+==============================
+
+We record major architectural decisions in Architecture Decision Records (ADRs),
+as `described by Michael Nygard
+<http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions>`_.
+Below is the list of our current ADRs.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    decisions/*

jitter_docs/_sources/developer/explanations/decisions/0001-record-architecture-decisions.rst.txt

@@ -0,0 +1,26 @@
+1. Record architecture decisions
+================================
+
+Date: 2022-02-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+We need to record the architectural decisions made on this project.
+
+Decision
+--------
+
+We will use Architecture Decision Records, as `described by Michael Nygard
+<http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions>`_.
+
+Consequences
+------------
+
+See Michael Nygard's article, linked above. To create new ADRs we will copy and
+paste from existing ones.

jitter_docs/_sources/developer/explanations/decisions/0002-switched-to-pip-skeleton.rst.txt

@@ -0,0 +1,35 @@
+2. Adopt python3-pip-skeleton for project structure
+===================================================
+
+Date: 2022-02-18
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+We should use the following `pip-skeleton <https://github.com/DiamondLightSource/python3-pip-skeleton>`_.
+The skeleton will ensure consistency in developer
+environments and package management.
+
+Decision
+--------
+
+We have switched to using the skeleton.
+
+Consequences
+------------
+
+This module will use a fixed set of tools as developed in python3-pip-skeleton
+and can pull from this skeleton to update the packaging to the latest techniques.
+
+As such, the developer environment may have changed, the following could be
+different:
+
+- linting
+- formatting
+- pip venv setup
+- CI/CD

jitter_docs/_sources/developer/how-to/contribute.rst.txt

@@ -0,0 +1 @@
+.. include:: ../../../.github/CONTRIBUTING.rst

jitter_docs/_sources/developer/how-to/make-release.rst.txt

@@ -0,0 +1,16 @@
+Make a release
+==============
+
+To make a new release, please follow this checklist:
+
+- Choose a new PEP440 compliant release number (see https://peps.python.org/pep-0440/)
+- Go to the GitHub release_ page
+- Choose ``Draft New Release``
+- Click ``Choose Tag`` and supply the new tag you chose (click create new tag)
+- Click ``Generate release notes``, review and edit these notes
+- Choose a title and click ``Publish Release``
+
+Note that tagging and pushing to the main branch has the same effect except that
+you will not get the option to edit the release notes.
+
+.. _release: https://github.com/PandABlocks/PandABlocks.github.io/releases

jitter_docs/_sources/developer/how-to/run-container.rst.txt

@@ -0,0 +1,38 @@
+Run in a container
+==================
+
+A PandA Development container is available from on `Github Container reistry <https://ghcr.io/pandablocks/pandablocks-dev-container>`_.
+
+
+
+Starting the container
+----------------------
+
+To pull the container from github container registry ::
+
+    $ docker pull https://ghcr.io/pandablocks/pandablocks-dev-container:latest
+
+To get a released version, use a numbered release instead of ``latest``.
+
+A directory containing all the PandA repos is required: ``REPO_DIR``.
+A Vivado installation is required: ``VIVADO_DIR``.
+A build directory is required: ``BUILD_DIR``
+
+The above directories will be mounted as volumes to the container as it is run with the following command:
+
+.. code-block:: bash
+
+    docker run --rm -it -v REPO_DIR:/repos:Z -v /scratch/tmp/build:/build:Z -v VIVADO_DIR:/scratch/Xilinx ghcr.io/pandablocks/pandablocks-dev-container /bin/bash
+
+In each repo you will need to:
+
+.. code-block:: bash
+
+    cp CONFIG.example CONFIG
+
+.. note::
+
+    For the Vivado installation the container path will need to match your local system. 
+    i.e. if it is located in /FPGA/Xilinx you will use VIVADO_DIR:/FPGA/Xilinx 
+    and you will then need to edit CONFIG as appropriate.
+

jitter_docs/_sources/developer/how-to/update-tools.rst.txt

@@ -0,0 +1,16 @@
+Update the tools
+================
+
+This module is merged with the python3-pip-skeleton_. This is a generic
+Python project structure which provides a means to keep tools and
+techniques in sync between multiple Python projects. To update to the
+latest version of the skeleton, run::
+
+    $ git pull --rebase=false https://github.com/DiamondLightSource/python3-pip-skeleton
+
+Any merge conflicts will indicate an area where something has changed that
+conflicts with the setup of the current module. Check the `closed pull requests
+<https://github.com/DiamondLightSource/python3-pip-skeleton/pulls?q=is%3Apr+is%3Aclosed>`_
+of the skeleton module for more details.
+
+.. _python3-pip-skeleton: https://DiamondLightSource.github.io/python3-pip-skeleton

jitter_docs/_sources/developer/index.rst.txt

@@ -0,0 +1,58 @@
+Developer Guide
+===============
+
+Documentation is split into four categories, also accessible from links in the
+side-bar.
+
+.. grid:: 2
+    :gutter: 4
+
+    .. grid-item-card:: :material-regular:`directions_run;3em`
+
+        .. toctree::
+            :caption: Tutorials
+            :maxdepth: 1
+
+        +++
+
+        Tutorials for getting up and running as a developer.
+
+    .. grid-item-card:: :material-regular:`task;3em`
+
+        .. toctree::
+            :caption: How-to Guides
+            :maxdepth: 1
+
+            how-to/contribute
+            how-to/update-tools
+            how-to/make-release
+            how-to/run-container
+
+        +++
+
+        Practical step-by-step guides for day-to-day dev tasks.
+
+    .. grid-item-card:: :material-regular:`apartment;3em`
+
+        .. toctree::
+            :caption: Explanations
+            :maxdepth: 1
+
+            explanations/decisions
+
+        +++
+
+        Explanations of how and why the architecture is why it is.
+
+    .. grid-item-card:: :material-regular:`description;3em`
+
+        .. toctree::
+            :caption: Reference
+            :maxdepth: 1
+
+            reference/latency_and_jitter
+            reference/standards
+
+        +++
+
+        Technical reference material on standards in use.

jitter_docs/_sources/developer/reference/latency_and_jitter.rst.txt

@@ -0,0 +1,112 @@
+Latency and Jitter
+==================
+
+Measuring Latency & Jitter
+--------------------------
+
+General Test Conditions:
+
+    - 0.144 μs clock period (~7MHz). This was the highest frequency that behaved consistently (see known issues section).
+    - Package versions on all PandAs:
+        - panda-fpga PandABox-no-fmc-sfp1_sync-3.0a2-162-gc398fbf
+        - panda-server zynq-3.0a3-31-g5f6f165
+        - panda-slowfpga b681574
+        - panda-webcontrol 2.1-8-g7aa28e8
+        - panda-webcontrol-no-subnet-validation 2.1-8-g7aa28e8
+    - Rohde & Schwarz RTO2044 oscilloscope set-up and measurement taking:
+        - Connect the two TTL outputs, that you wish to compare, to two different channel inputs on the front of the oscilloscope.
+        - Press the "Autoset" button on the oscilloscope to get most settings into the right ballpark.
+        - You should then see two square waves onscreen.
+        - For our tests, both channels were manually vertically scaled to 1V/div, and given an offset of 2.5V; but feel free to set them to something more comfortable for you, as long as you use the same for both channels.
+        - Select "Analysis" from the bottom toolbar.
+        - Select "Jitter Wizard" from the list that pops up.
+        - On the first screen, select "Skew" as the measurement type (for more info see https://www.rohde-schwarz.com/webhelp/RTO_HTML_UserManual_en/Content/2ff5499f0f6f4cd5.htm).
+        - On the second screen, make sure that the two channels that your square waves are on are selected. The original (clock block direct output) waveform should be selected as "Channel source 1", and the other waveform that you want to compare to it should be selected as "Channel source 2". "Edge polarity" shouldn't matter, but "Positive" was used for these tests. Finally, since you shouldn't be able to change it, "Relative Polarity" should already be set to "Matching".
+        - On the third screen, select "Retain current settings" in all three boxes.
+        - On the fourth screen, the slider buttons for "Source signal" and "Histogram of measurement" should be on (righthand side) and the other two ("Track of measurement" & "FFT spectrum of track") should be off (lefthand side).
+        - Click "Execute"!
+        - Check the trigger options to check that it's still triggering off the leading edge of your original (source of truth) waveform, it may well have switched to triggering off the other channel.
+        - Reduce the horizontal scale down to the smallest resolution where there is still at least one wavelength visible on the screen.
+        - Wait until the "Event count" exceeds 50,000, to ensure we have captured enough data for our sample to be representative.
+        - Take a screenshot through the web interface
+        - It should look something like this.
+
+.. image:: ../../images/Example1.jpg
+   :width: 600
+
+Baseline Measurements
+---------------------
+
+Specific Test Conditions:
+
+    - Connected like so: PandA-02, and for the roundtrip measurement: PandA-05.
+    - Giving a network arrangement of this, and for the roundtrip measurement this.
+
+.. image:: ../../images/Baseline2.png
+   :width: 600
+
+Results:
+
+Link Method                Internal Clock Latency Internal Clock Jitter External Clock Latency External Clock Jitter Recovered Clock Latency Recovered Clock Jitter
+-------------------------- ---------------------- --------------------- ---------------------- --------------------- ----------------------- ----------------------
+*                                                 Range      σ                                 Range      σ                                  Range      σ
+========================== ====================== ========== ========== ====================== ========== ========== ======================= ========== ===========
+Hard Metal Loopback        273 ns                 ±79.80 ps  18.190 ps  273 ns                 ±76.75 ps  18.078 ps  N/A                     N/A        N/A
+Short Fiber Optic Loopback 273 ns                 ±73.55 ps  18.091 ps  273 ns                 ±69.75 ps  17.914 ps  N/A                     N/A        N/A
+Long Fiber Optic Loopback  278 ns                 ±72.70 ps  18.146 ps  278 ns                 ±71.05 ps  18.079 ps  N/A                     N/A        N/A
+PandA to PandA Roundtrip   N/A                    N/A        N/A        555 ns                 ±69.50 ps  16.660 ps  555 ns                  ±68.70 ps  16.425 ps
+========================== ====================== ========== ========== ====================== ========== ========== ======================= ========== ===========
+
+Ring Configuration
+------------------
+
+Specific Test Conditions:
+
+    - Connected like so: PandA-02, PandA-05, and PandA-03.
+    - Giving a network arrangement of this.
+
+Results:
+
+Clock Type                    Delay After 1 Link Jitter After 1 Link  Delay After 2 Links Jitter After 2 Links   Delay After 3 Links Jitter After 3 Links
+---------------------------- ------------------- -------------------- ------------------- --------------------- -------------------- --------------------
+PandA-02  PandA-05  PandA-03                     Range      σ                             Range       σ                              Range      σ
+========= ========= ========= ================== ========== ========= =================== =========== ========= ==================== ========== =========
+Internal  Recovered Recovered 276 ns             ±657.95 ps	114.00 ps 545 ns              ±1209.55 ps 168.78 ps 847 ns               ±98.35 ps  24.869 ps
+External  External	External  269 ns             ±124.75 ps	29.646 ps 533.5 ns            ±134.50 ps  30.025 ps 822.5 ns             ±112.50 ps 25.224 ps
+External  Recovered	Recovered 276 ns             ±128.60 ps	31.322 ps 545 ns              ±134.10 ps  32.376 ps 839 ns               ±100.60 ps 25.137 ps
+Recovered Recovered	Recovered 276.5 ns           ±136.05 ps	32.778 ps 565 ns              ±136.35 ps  33.231 ps 847 ns               ±103.85 ps 24.901 ps
+========= ========= ========= ================== ========== ========= =================== =========== ========= ==================== ========== =========
+
+Star Configuration
+------------------
+
+Specific Test Conditions:
+
+    - Connected like so: PandA-02, PandA-05, and PandA-03.
+    - Giving a network arrangement of this.
+
+Infinitely Recycled Clock Drift
+-------------------------------
+
+Specific Test Conditions:
+
+    - 40ns clock period (25MHz).
+    - Used the previous PandABlocks-FPGA package version: panda-fpga PandABox-no-fmc-sfp1_sync-3.0a2-161-g57dda12
+    - Connected like so: PandA-02, PandA-05, and PandA-03.
+    - Giving a network arrangement of this.
+
+Results:
+
+After being left for 112.5 hours, the mean clock period was still measured to be within 0.01ns of the mean clock period initially measured at the start. So it is clear that there was no significant drift in the clock period/frequency over the duration of the test.
+
+The jitter in the clock period was measured to be:
+
+Time  Jitter
+----- ------------------
+*     Range    σ
+===== ======== =========
+Start ±71.0 ps 17.303 ps
+End   ±77.5 ps 17.569 ps
+===== ======== =========
+
+N.B. The oscilloscope was only switched on at the start and end of the test and was not left on during the unsupervised time, so it is possible that a significant deviation in clock period both occurred and was self-corrected during the unsupervised time.

jitter_docs/_sources/developer/reference/standards.rst.txt

@@ -0,0 +1,8 @@
+Standards
+=========
+
+This document defines the code and documentation standards used in this
+repository.
+
+Code Standards
+--------------

jitter_docs/_sources/genindex.rst.txt

@@ -0,0 +1,5 @@
+API Index
+=========
+
+..
+    https://stackoverflow.com/a/42310803

jitter_docs/_sources/index.rst.txt

@@ -0,0 +1,39 @@
+:html_theme.sidebar_secondary.remove:
+
+.. include:: ../README.rst
+    :end-before: when included in index.rst
+
+How the documentation is structured
+-----------------------------------
+
+The documentation is split into 2 sections:
+
+.. grid:: 2
+
+    .. grid-item-card:: :material-regular:`person;4em`
+        :link: user/index
+        :link-type: doc
+
+        The User Guide contains documentation on how to install and use PandABlocks.github.io.
+
+    .. grid-item-card:: :material-regular:`code;4em`
+        :link: developer/index
+        :link-type: doc
+
+        The Developer Guide contains documentation on how to develop and contribute changes back to PandABlocks.github.io.
+
+The Existing Documentation for the PandABlocks projects can be found:
+
+======================= =====================================================
+PandABlocks-FPGA        https://PandABlocks.github.io/PandABlocks-FPGA
+PandABlocks-rootfs      https://PandABlocks.github.io/PandABlocks-rootfs
+PandABlocks-server      https://PandABlocks.github.io/PandABlocks-server
+PandABlocks-webcontrol  https://PandABlocks.github.io/PandABlocks-webcontrol
+PandABlocks-client      https://PandABlocks.github.io/PandABlocks-client
+======================= =====================================================
+
+.. toctree::
+    :hidden:
+
+    user/index
+    developer/index