WIP: Feature/reference improv

_pinouts/segger-20/data.py

@@ -1,6 +1,12 @@
+# This information was referenced from the following sources:
+# https://www.segger.com/products/debug-probes/j-link/technology/interface-description
+# https://wiki.segger.com/Using_J-Link_VCOM_functionality
+# UM08001_JLinkARM User Manual
+
 legend = [
     ("SWD", "swd"),
     ("JTAG", "jtag"),
+    ("UART", "uart"),
     ("Reset", "rst"),
     ("Pin Number", "pin"),
     ("Power", "pwr"),
@@ -20,7 +26,7 @@
     ],
     [
         ("5", "pin"),
-        ("NC", "nc"),
+        ("UART TX", "uart"),
         ("TDI", "jtag"),
     ],
     [
@@ -50,6 +56,7 @@
     ],
     [
         ("17", "pin"),
+        ("UART RX", "uart"),
         ("NC", "nc"),
     ],
     [
@@ -85,27 +92,32 @@
     ],
     [
         ("14", "pin"),
-        ("GND", "gnd"),
+        ("GND*", "gnd"),
     ],
     [
         ("16", "pin"),
-        ("GND", "gnd"),
+        ("GND*", "gnd"),
     ],
     [
         ("18", "pin"),
-        ("GND", "gnd"),
+        ("GND*", "gnd"),
     ],
     [
         ("20", "pin"),
-        ("GND", "gnd"),
+        ("GND*", "gnd"),
     ],
 ]
 
 # Text
 
 title = """<tspan class='h1'>SEGGER 20pin JTAG/SWD Connector Pinout</tspan>"""
 
-description = """J-Link and J-Trace have a JTAG connector compatible with ARM's Multi-ICE connector.
+description = """J-Link and J-Trace have a JTAG connector compatible with ARM's Multi-ICE/JTAG connector.
 
 <tspan class='strong'>NOTE:</tspan> The header is FULL PITCH! This means it is 0.1 inch (2.54 mm) pitch pin header.
+<tspan class='strong'>NOTE:</tspan> The TX/RX directionality is from the perspective of the Debugger. On the
+Target (DUT) side these pins are swapped and pin 5 is RX and 17 is TX.
+<tspan class='strong'>NOTE:</tspan> The UART functionality is not available on all J-Link models nor all modes of operation.
+<tspan class='strong'>NOTE:</tspan> On later J-Link products pins 14, 16, 18, and 20 are reserved for firmware extensions,
+they can be left open or connected to GND in normal debug environments and are not essential for normal operation.
 """

_pinouts/segger-20/styles.css

@@ -50,6 +50,17 @@ text {
     fill: #2B59C3;
     stroke: rgb(0, 0, 0);
 }
+.uart .pinlabel__body{
+    fill: #4E148C;
+    stroke: rgb(0, 0, 0);
+}
+.uart .pinlabel__leader{
+    stroke: #4E148C;
+}
+.uart .swatch__body {
+    fill: #4E148C;
+    stroke: rgb(0, 0, 0);
+}
 .trace .pinlabel__body{
     fill: #9FCC2E;
     stroke: rgb(0, 0, 0);

conf.py

@@ -5,6 +5,17 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import os
+from urllib.parse import urlunparse, ParseResult
+
+# -- Helper functions --------------------------------------------------------
+
+
+# Build valid URL from parts
+def build_url(netloc='', path='', params='', query='', fragment='', scheme='https'):
+    if '__contains__' in dir(path) and not isinstance(path, str):
+        path = '/'.join(path)  # merge path parts into a single string
+    return urlunparse(ParseResult(scheme, netloc, path, params, query, fragment))
+
 
 # -- Path setup --------------------------------------------------------------
 
@@ -22,33 +33,65 @@
 project = 'Black Magic Debug'
 copyright = '2022-2023, Piotr Esden-Tempski <piotr@esden.net>; 2022-2023, Rachel Mant <git@dragonmux.network>'
 author = 'Piotr Esden-Tempski <piotr@esden.net>, Rachel Mant <git@dragonmux.network>'
-language  = 'en'
-html_baseurl = 'https://black-magic.org'
+language = 'en'
+
+# -- Project information not required by sphinx ------------------------------
+
+project_decription = 'The Plug&Play MCU Debugger'
+
+# URLs
+netloc_black_magic_org = 'black-magic.org'
+netloc_1b2 = '1bitsquared.com'
+netloc_1b2_eu = netloc_1b2.replace('.com', '.de')
+netloc_github = 'github.com'
+
+github_org_slug = 'blackmagic-debug'
+github_bmd_slug = 'blackmagic'
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'ablog',
     'myst_parser',
-    'sphinx.ext.todo',
+    'sphinx_favicon',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.extlinks',
     'sphinx.ext.githubpages',
     'sphinx.ext.graphviz',
     'sphinx.ext.napoleon',
-    'sphinxcontrib.platformpicker',
+    'sphinx.ext.todo',
     'sphinxcontrib.asciinema',
+    'sphinxcontrib.platformpicker',
     'sphinxcontrib.youtube',
-    'sphinx_favicon',
     'sphinxext.opengraph',
-    'ablog',
 ]
 
 source_suffix = {
-	'.rst': 'restructuredtext',
-	'.md': 'markdown',
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
 }
 
+extlinks = {
+    'black-magic-org-gh': (build_url(netloc_github, [github_org_slug, '%s']), None),
+    'bmd-gh': (build_url(netloc_github, [github_org_slug, github_bmd_slug, '%s']), None),
+    'bmd-issue': (build_url(netloc_github, [github_org_slug, github_bmd_slug, 'issues/%s']), 'BMD Issue #%s'),
+    '1b2': (build_url(netloc_1b2, '%s'), None),
+    '1b2-eu': (build_url(netloc_1b2_eu, '%s'), None),
+    '1b2-product': (build_url(netloc_1b2, 'products/%s'), '1BitSquared US store product %s'),
+    '1b2-product-eu': (build_url(netloc_1b2_eu, 'products/%s'), '1BitSquared EU store product %s'),
+    'github': (build_url(netloc_github, '%s'), None),
+    'github-user': (build_url(netloc_github, '%s'), '@%s'),
+}
+
+# Produce warnings for hard-coded external links that can be replaced with extlinks
+extlinks_detect_hardcoded_links = True
+
+# Make sure autosectionlabel targets are unique
+autosectionlabel_prefix_document = True
+
 todo_include_todos = True
 
 myst_heading_anchors = 3
@@ -66,6 +109,8 @@
 
 # -- Options for HTML output -------------------------------------------------
 
+html_baseurl = build_url(netloc_black_magic_org)
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
@@ -74,9 +119,9 @@
 
 html_theme_options = {
     'logo': 'blackmagic-logo.svg',
-    'github_user': 'blackmagic-debug',
-    'github_repo': 'blackmagic',
-    'description': 'The Plug&Play MCU Debugger',
+    'github_user': github_org_slug,
+    'github_repo': github_bmd_slug,
+    'description': project_decription,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -96,10 +141,10 @@
     ]
 }
 
-blog_baseurl = "https://black-magic.org"
+blog_baseurl = html_baseurl
 
 blog_authors = {
-    'esden': ('Piotr Esden-Tempski', 'https://github.com/esden'),
+    'esden': ('Piotr Esden-Tempski', build_url(netloc_github, 'esden')),
 }
 
 # Favicon settings
@@ -189,8 +234,8 @@
     },
 ]
 
-ogp_site_url = "https://black-magic.org"
-ogp_site_name = "Black Magic Debug"
+ogp_site_url = html_baseurl
+ogp_site_name = project
 ogp_image = "_static/blackmagic-logo.png"
 
 # Generate pinout diagrams

getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 ## Get a Black Magic Probe
-If you don't have one already, you'll need to [get a Black Magic Probe](index.md#getting-hardware).
+If you don't have one already, you'll need to {ref}`get a Black Magic Probe <index:getting hardware>`.
 
 ## Connecting to your computer
 Connect the Black Magic Probe to your computer's USB port.  When connected via USB, the Black Magic Probe will enumerate as a CDC-ACM device which the OS should present as a tty device or serial port.
@@ -25,9 +25,9 @@ On Windows, when you first connect, the Black Magic Probe should be detected as
 
 ![Device Manager](_assets/device_manager.png)
 
-__Note:__ For older Windows versions (Windows 7 and older), you will be prompted to install a driver.  You can download the driver [here](https://github.com/blackmagic-debug/blackmagic/tree/master/driver).
+__Note:__ For older Windows versions (Windows 7 and older), you will be prompted to install a driver.  You can download the driver {bmd-gh}`here <tree/master/driver>`.
 
-__Note:__ If you are on Windows 10 and want to upgrade the firmware to the probe itself, you can install the [libusbK](http://zadig.akeo.ie/) driver. This will give you access to the DFU interface of the Black Magic Probe and allow you to use dfu-util to upgrade the Black Magic Probe firmware. (You do not need to install this driver if you only plan to use the Black Magic Probe and do not need/want to upgrade the firmware.) Also, Windows 10 displays the BMP probe ports using the generic title, "USB Serial Device", as seen below:
+__Note:__ If you are on Windows 10 and want to upgrade the firmware to the probe itself, you can install the [libusbK](https://zadig.akeo.ie/) driver. This will give you access to the DFU interface of the Black Magic Probe and allow you to use dfu-util to upgrade the Black Magic Probe firmware. (You do not need to install this driver if you only plan to use the Black Magic Probe and do not need/want to upgrade the firmware.) Also, Windows 10 displays the BMP probe ports using the generic title, "USB Serial Device", as seen below:
 
 ![Device Manager Windows 10](_assets/device_manager_w10.png)
 
@@ -68,7 +68,7 @@ Attaching to Remote target
 The command `monitor swdp_scan` may be used to use the Serial-Wire Debug Protocol instead of JTAG to connect to the target.
 
 Once attached, all the standard GDB commands may be used to start and control
-the execution of the embedded application. [GDB Commands](usage/gdb-commands.md) provides a quick introduction.
+the execution of the embedded application. {ref}`usage/gdb-commands:gdb commands` provides a quick introduction.
 
 ```{note}
 On macOS use the `/dev/cu.usbmodem<somenumber>`. Don't use the tty version of this device as this one will freeze gdb when it tries to open it.
@@ -98,5 +98,5 @@ Esden created a video walk-through of using Black Magic Probe with the 1Bitsy mi
 If you have additional tutorial resources for the use of Black Magic Probe let us know so we can include them here.
 
 ## Getting started with open-source Cortex-M development
-- See [this presentation](https://github.com/gsmcmullin/embedded-demo/raw/master/slides.pdf), porting a basic Unix program to an embedded Cortex-M3 using [libopencm3](http://libopencm3.org/).
+- See {github}`this presentation<gsmcmullin/embedded-demo/raw/master/slides.pdf>`, porting a basic Unix program to an embedded Cortex-M3 using [libopencm3](http://libopencm3.org/).
 - The [gcc-arm-embedded readme](https://launchpadlibrarian.net/268329726/readme.txt) is also worth a read.

hacking/contrib.md

@@ -3,14 +3,14 @@
 ## General
 * Join the [Discord channel](https://discord.gg/P7FYThy)
 * Join the [mailing list](http://sourceforge.net/p/blackmagicdebug/mailman/)
-* Edit this [website on GitHub](https://github.com/blackmagic-debug/black-magic-org)
+* Edit this {black-magic-org-gh}`website on GitHub<black-magic-org>`
 * Use [Linux kernel coding style](https://www.kernel.org/doc/html/latest/process/coding-style.html)
 * Submit changes with [GitHub pull-requests](https://guides.github.com/introduction/flow/)
 
 ## Patch Policy (draft)
- - [@esden](https://github.com/esden) is the maintainer of the project.
- - [@dragonmux](https://github.com/dragonmux) is deputy maintainer answering to [@esden](https://github.com/esden)
- - If you have any questions regarding the contribution process either contact [@esden](https://github.com/esden) or [@dragonmux](https://github.com/dragonmux)
+ - {github-user}`esden` is the maintainer of the project.
+ - {github-user}`dragonmux` is deputy maintainer answering to {github-user}`esden`
+ - If you have any questions regarding the contribution process either contact {github-user}`esden` or {github-user}`dragonmux`
  - Every Pull Request has to build and pass all tests on top of the `main` branch before it can be merged.
  - Every Pull Request requires review from one of the maintainers.
  - Because we can't test all possible hardware platforms, we will need target specific maintainers to test and approve non-trivial changes to target support code.
@@ -25,4 +25,4 @@ without further testing assuming they conform to style and don't do anything stu
 
 ## Checks before providing a pull request
 
-Before providing a pull request, please read the [Contribution Guidelines](https://github.com/blackmagic-debug/blackmagic/blob/main/CONTRIBUTING.md).
+Before providing a pull request, please read the {bmd-gh}`Contribution Guidelines<blob/main/CONTRIBUTING.md>`.

hacking/hacking.md

@@ -2,11 +2,11 @@
 
 The Black Magic Debug firmware is under the GPLv3 open-source license, all contributions to the project should be either GPLv3 or compatible.
 
-Any contributed hardware designs found in the [hardware repository](https://github.com/blackmagic-debug/blackmagic-hardware/) is under the CC-BY-SA license.
+Any contributed hardware designs found in the {black-magic-org-gh}`hardware repository<blackmagic-hardware/>` is under the CC-BY-SA license.
 
 ## Getting the project source
 
-The project resides in a [GitHub git repository](https://github.com/blackmagic-debug/blackmagic)
+The project resides in a {black-magic-org-gh}`GitHub git repository<blackmagic>`
 
 Clone this repository (or fork and clone) using your desired method. Typically:
 
@@ -50,7 +50,7 @@ This will result in the following binary files:
 ## Alternative Hardware
 
 A number of users have contributed alternative hardware designs that are compatible with the native firmware.
-Some of these designs are in the [hardware repo](https://github.com/blackmagic-debug/blackmagic-hardware/tree/master/contrib). Check the `README.md` files for details. For instance, to compile a BMP for an ST-Link v2 to run as alternative to the ST firmware, compile:
+Some of these designs are in the {black-magic-org-gh}`hardware repo<blackmagic-hardware/tree/master/contrib>`. Check the `README.md` files for details. For instance, to compile a BMP for an ST-Link v2 to run as alternative to the ST firmware, compile:
 
 ```bash
 make PROBE_HOST=stlink ST_BOOTLOADER=1
@@ -94,4 +94,4 @@ Exit the screen session by type crt-a + ctl-\\.
 
 ## Updating firmware
 
-Follow instructions in [Firmware Upgrade Section](/upgrade.md).
+Follow instructions in {ref}`upgrade` Section.

hacking/target-clock-generation.md

@@ -39,7 +39,7 @@ TMS is used to help navigate the capture and find the correct routines to measur
 signal we want to measure. We use a 1% pre-trigger capture ratio, 24MHz sampling frequency and 100 million
 samples per capture to ensure we get sufficient data.
 
-To prepare the first (`_no_delay`) run, we co-opt the remote protocol by [editing remote.c](https://github.com/blackmagic-debug/blackmagic/blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/remote.c#L272).
+To prepare the first (`_no_delay`) run, we co-opt the remote protocol by {bmd-gh}`editing remote.c<blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/remote.c#L272>`.
 We do this by commenting out the referenced line and replacing it with `target_clk_divider = UINT32_MAX;`
 which, by virtue of how the bitbanging routines are written, forces the _no_delay variants.
 
@@ -54,14 +54,14 @@ Once complete, we can then turn our attention to PulseView where you should see
 The resulting capture has, as noted, two regions of interest. The reason for this is that they contain
 clock pulses from all 3 major routines used and are easily identified. This is why we capture TMS as well.
 
-At the start of a JTAG scan run, BMD [reinitialises its JTAG subsystem](https://github.com/blackmagic-debug/blackmagic/blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/target/jtag_scan.c#L89-L96).
+At the start of a JTAG scan run, BMD {bmd-gh}`reinitialises its JTAG subsystem<blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/target/jtag_scan.c#L89-L96>`.
 When it does this, it sets TMS high, sets the jtag_proc structure back up, and then [runs a >50 pulse JTAG
 reset and the ARM SWD-to-JTAG sequence](https://github.com/blackmagic-debug/blackmagic/blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/platforms/common/jtagtap.c#L53-L55).
 
 This then ensures the bus is in a good state while leaving TMS high after. We then perform an additional
 JTAG reset when starting the ID code readout, along with having to switch into the Shift-DR JTAG TAP state. These
 are the additional sets of pulses between the marked ones of interest. We finally do
-[several 32-bit transactions](https://github.com/blackmagic-debug/blackmagic/blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/target/jtag_scan.c#L171)
+{bmd-gh}`several 32-bit transactions<blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/target/jtag_scan.c#L171>`
 on the bus, with the goal of reading out ID codes. These are done with TMS low giving this distinctive signature
 between TMS and TCK that we see in the capture.
 
@@ -131,15 +131,15 @@ The final division factor is provided as an output in cell B9 of the sheet "Data
 
 Having done all of the above, there are a series of simple `#define` statements that must be added to the platform's header. We will make reference to the native (BMP) platform as an example for this section.
 
-The first thing that must be defined in the platform header, is [`BITBANG_CALIBRATED_FREQS`](https://github.com/blackmagic-debug/blackmagic/blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/platforms/native/platform.h#L296)
+The first thing that must be defined in the platform header, is {bmd-gh}``BITBANG_CALIBRATED_FREQS`<blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/platforms/native/platform.h#L296>`
 which serves to inform the `platform_max_frequency_{get,set}` implementations that a calibration has been done and
 not to use the old method this replaces.
 
 With this defined, we must then define the frequency achieved by the `_no_delay` routines, and the maximum frequency
-achieved by  the `_clk_delay` routines. This involves defining [`BITBANG_NO_DELAY_FREQ` and `BITBANG_0_DELAY_FREQ`](https://github.com/blackmagic-debug/blackmagic/blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/platforms/native/platform.h#L305-L313C9)
+achieved by  the `_clk_delay` routines. This involves defining {bmd-gh}`BITBANG_NO_DELAY_FREQ and BITBANG_0_DELAY_FREQ<blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/platforms/native/platform.h#L305-L313C9>`
 which are the measured frequency values expressed in Hz.
 
 Finally, the conversion constants for the delay routines must be defined. These are
-[`BITBANG_DIVIDER_OFFSET` and `BITBANG_DIVIDER_FACTOR`](https://github.com/blackmagic-debug/blackmagic/blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/platforms/native/platform.h#L327-L328).
+{bmd-gh}`BITBANG_DIVIDER_OFFSET and BITBANG_DIVIDER_FACTOR<blob/799a4088e6c98fcbd977d9c3f2036bef4ba1e9b6/src/platforms/native/platform.h#L327-L328>`.
 These are the values from the linear regression called out in the above section -
 workbook sheet "Data", cells B9 and B12.