From 48d60a9949b742a1112d8497a5bbb28ef9f6fd4d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 12:16:29 +0100 Subject: [PATCH 01/16] pinouts/segger-20: add uart labels --- _pinouts/segger-20/data.py | 9 +++++++-- _pinouts/segger-20/styles.css | 11 +++++++++++ 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/_pinouts/segger-20/data.py b/_pinouts/segger-20/data.py index 9bcb38d..bb7ffc8 100644 --- a/_pinouts/segger-20/data.py +++ b/_pinouts/segger-20/data.py @@ -1,6 +1,7 @@ legend = [ ("SWD", "swd"), ("JTAG", "jtag"), + ("UART", "uart"), ("Reset", "rst"), ("Pin Number", "pin"), ("Power", "pwr"), @@ -20,7 +21,7 @@ ], [ ("5", "pin"), - ("NC", "nc"), + ("UART TX", "uart"), ("TDI", "jtag"), ], [ @@ -50,6 +51,7 @@ ], [ ("17", "pin"), + ("UART RX", "uart"), ("NC", "nc"), ], [ @@ -105,7 +107,10 @@ title = """SEGGER 20pin JTAG/SWD Connector Pinout""" -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. NOTE: The header is FULL PITCH! This means it is 0.1 inch (2.54 mm) pitch pin header. +NOTE: 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. +NOTE: The UART functionality is not available on all J-Link models nor all modes of operation. """ diff --git a/_pinouts/segger-20/styles.css b/_pinouts/segger-20/styles.css index f154013..7d35771 100644 --- a/_pinouts/segger-20/styles.css +++ b/_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); From e4799352fb67380fdda94773882a91b8dea2dd1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 12:24:51 +0100 Subject: [PATCH 02/16] pinouts/segger-20: add reserved gnds --- _pinouts/segger-20/data.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/_pinouts/segger-20/data.py b/_pinouts/segger-20/data.py index bb7ffc8..6018286 100644 --- a/_pinouts/segger-20/data.py +++ b/_pinouts/segger-20/data.py @@ -87,19 +87,19 @@ ], [ ("14", "pin"), - ("GND", "gnd"), + ("GND*", "gnd"), ], [ ("16", "pin"), - ("GND", "gnd"), + ("GND*", "gnd"), ], [ ("18", "pin"), - ("GND", "gnd"), + ("GND*", "gnd"), ], [ ("20", "pin"), - ("GND", "gnd"), + ("GND*", "gnd"), ], ] @@ -113,4 +113,6 @@ NOTE: 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. NOTE: The UART functionality is not available on all J-Link models nor all modes of operation. +NOTE: 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. """ From 48e2e17a04b057df64aed9195a4f6e16fb130243 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 12:25:22 +0100 Subject: [PATCH 03/16] pinouts/segger-20: add reference sources --- _pinouts/segger-20/data.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/_pinouts/segger-20/data.py b/_pinouts/segger-20/data.py index 6018286..c91e9bc 100644 --- a/_pinouts/segger-20/data.py +++ b/_pinouts/segger-20/data.py @@ -1,3 +1,8 @@ +# 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"), From 4cc3aea4cd4f20c08ccffeddf26ac145650fc220 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 13:17:56 +0100 Subject: [PATCH 04/16] conf: add autosectionlabel extension Allows us to refer to sections by its title with the reference role (ref) --- conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/conf.py b/conf.py index 7e0e288..9394a86 100644 --- a/conf.py +++ b/conf.py @@ -32,6 +32,7 @@ # ones. extensions = [ 'myst_parser', + 'sphinx.ext.autosectionlabel', 'sphinx.ext.todo', 'sphinx.ext.githubpages', 'sphinx.ext.graphviz', @@ -49,6 +50,9 @@ '.md': 'markdown', } +# Make sure autosectionlabel targets are unique +autosectionlabel_prefix_document = True + todo_include_todos = True myst_heading_anchors = 3 From 5659ae8a1d1a8acffc0a7090cfe582f9c8212943 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 13:18:50 +0100 Subject: [PATCH 05/16] pinouts/segger-20: add usage notes --- knowledge/pinouts.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/knowledge/pinouts.md b/knowledge/pinouts.md index b39cd5c..bbe2cc4 100644 --- a/knowledge/pinouts.md +++ b/knowledge/pinouts.md @@ -46,9 +46,14 @@ This connector is the old and trusty ARM JTAG connector. It is a bigger pitch (0 This is a custom connector that STMicroelectronics invented. It is backwards compatible with the [ARM Cortex 10Pin Debug Connector](#arm-cortex-10pin-debug-connector), so one can plug a 14pin ribbon cable into a 10pin debug connector if the connector is not fully shrouded. The ribbon cable will then overhang the connector by two pins on each side. If your target has this 14pin connector you can connect the Black Magic Probe by connecting a 14pin ribbon cable to the Black Magic Probe ([1BitSquared](https://1bitsquared.com/products/stdc14-idc-cable) is offering these cables in their store). - ## SEGGER 20pin Debug Connector ![](../_pinouts/segger-20-legend.svg) -This is a custom connector used on SEGGER J-Link and J-Trace debug probes, designed to be loosely compatible with the [ARM JTAG Connector](#arm-jtag-connector). +This is a custom connector used on SEGGER J-Link and J-Trace debug probes, designed to be loosely compatible with the {ref}`knowledge/pinouts:arm jtag connector`. + +Targets using this connector can be directly interfaced with {ref}`hardware:native hardware` probes using a 20Pin JTAG adapter board found on the [1BitSquared](https://1bitsquared.com/collections/accessories/products/20pin-jtag-adapter) store. + +SEGGER J-Link probes using this connector can interface directly with targets using the {ref}`knowledge/pinouts:black magic debug unified connector (bmdu)` using the same 20Pin JTAG adapter board. + +Note that in both cases the adapter board does not allow for UART or J-Link Kickstart power (pin 19) to be used. From 1133f5efe88bdcc74e5064a30ef077292d2a3cf2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 18:16:49 +0100 Subject: [PATCH 06/16] conf: sort extensions --- conf.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/conf.py b/conf.py index 9394a86..ea82e2c 100644 --- a/conf.py +++ b/conf.py @@ -31,23 +31,23 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'ablog', 'myst_parser', + 'sphinx_favicon', 'sphinx.ext.autosectionlabel', - 'sphinx.ext.todo', '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', } # Make sure autosectionlabel targets are unique From 942b78799876853db78f2ac57a60cca973a41a61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 18:20:04 +0100 Subject: [PATCH 07/16] conf: deduplicate configurations --- conf.py | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/conf.py b/conf.py index ea82e2c..4de4400 100644 --- a/conf.py +++ b/conf.py @@ -22,8 +22,15 @@ project = 'Black Magic Debug' copyright = '2022-2023, Piotr Esden-Tempski ; 2022-2023, Rachel Mant ' author = 'Piotr Esden-Tempski , Rachel Mant ' -language = 'en' -html_baseurl = 'https://black-magic.org' +language = 'en' + +# -- Project information not required by sphinx ------------------------------ + +project_decription = 'The Plug&Play MCU Debugger' + +# URLs +github_org_slug = 'blackmagic-debug' +github_bmd_slug = 'blackmagic' # -- General configuration --------------------------------------------------- @@ -70,6 +77,8 @@ # -- Options for HTML output ------------------------------------------------- +html_baseurl = 'https://black-magic.org' + # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # @@ -78,9 +87,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, @@ -100,7 +109,7 @@ ] } -blog_baseurl = "https://black-magic.org" +blog_baseurl = html_baseurl blog_authors = { 'esden': ('Piotr Esden-Tempski', 'https://github.com/esden'), @@ -193,8 +202,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 From 619a25dde21f9f88ff0878bfcb362315c669f0f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 18:23:03 +0100 Subject: [PATCH 08/16] conf: add extlink extension Helps with the common pattern of having many external links that point to URLs on one and the same site --- conf.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/conf.py b/conf.py index 4de4400..baaf7fa 100644 --- a/conf.py +++ b/conf.py @@ -29,6 +29,8 @@ project_decription = 'The Plug&Play MCU Debugger' # URLs +netloc_1b2 = '1bitsquared.com' + github_org_slug = 'blackmagic-debug' github_bmd_slug = 'blackmagic' @@ -42,6 +44,7 @@ 'myst_parser', 'sphinx_favicon', 'sphinx.ext.autosectionlabel', + 'sphinx.ext.extlinks', 'sphinx.ext.githubpages', 'sphinx.ext.graphviz', 'sphinx.ext.napoleon', @@ -57,6 +60,13 @@ '.md': 'markdown', } +extlinks = { + '1b2-product': (build_url(netloc_1b2, 'products/%s'), '1BitSquared US store product %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 From cb38ce9ad0db55e2165330127b6e3fec8d17c3f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 18:52:13 +0100 Subject: [PATCH 09/16] misc: use ref with autosectionlabel targets for self section referencing --- getting-started.md | 4 ++-- hacking/hacking.md | 2 +- hacking/target-cortex-m.md | 4 ++-- hardware.md | 8 ++++---- index.md | 10 +++++----- knowledge/faq.md | 5 ++--- knowledge/pinouts.md | 6 +++--- knowledge/terminology.md | 2 +- usage/gdb-automation.md | 2 +- usage/platformio.md | 12 ++++++------ usage/rtt.md | 6 +++--- usage/swo.md | 2 +- 12 files changed, 31 insertions(+), 32 deletions(-) diff --git a/getting-started.md b/getting-started.md index 963b206..4ead8a1 100644 --- a/getting-started.md +++ b/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 `. ## 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. @@ -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`. Don't use the tty version of this device as this one will freeze gdb when it tries to open it. diff --git a/hacking/hacking.md b/hacking/hacking.md index cc4acb5..d49d995 100644 --- a/hacking/hacking.md +++ b/hacking/hacking.md @@ -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. diff --git a/hacking/target-cortex-m.md b/hacking/target-cortex-m.md index 4273840..2a2543e 100644 --- a/hacking/target-cortex-m.md +++ b/hacking/target-cortex-m.md @@ -83,7 +83,7 @@ to the 10-pin debug target connector is: * PicoBlade Pin 3 (purple) => 10-pin connector pin 2 * PicoBlade Pin 4 (black) => 10-pin connector pin 3 or 5 -For more information on what connections are being made here, see the [pinout glossary](../knowledge/pinouts.md). +For more information on what connections are being made here, see the {ref}`knowledge/pinouts:pinout glossary`. If you are using an older generation BMP that uses the 20-pin ARM debug connector, you will instead want to connect the green wire to pin 9 of the JTAG connector, purple to pin 7, and black to any even pin on the JTAG connector @@ -91,7 +91,7 @@ other than pin 2. If you set one BMP to debug another, then you can load firmware using GDB into the BMP. If you are simply building the firmware and evaluating its function by reading the output from `DEBUG_*` statements then you will need to use -`bmputil` or `dfu-util` to update the firmware. (see [Updating the Firmware](../upgrade.md)). +`bmputil` or `dfu-util` to update the firmware. (see {ref}`upgrade:firmware upgrade`). ### Debugging newer generations diff --git a/hardware.md b/hardware.md index 7a421c9..3bd4066 100644 --- a/hardware.md +++ b/hardware.md @@ -13,7 +13,7 @@ The following is a list of official hardware supported by the native target that **Status** Active -**Source** [Vendors](index.md#getting-hardware) +**Source** {ref}`Vendors` **Schematic** TODO @@ -34,7 +34,7 @@ New, slightly larger form factor than previous versions to accommodate the large **Status** Legacy (not in production) -**Source** [Vendors](index.md#getting-hardware) +**Source** {ref}`Vendors` **Schematic** [bmpm_v2_1c_schematic.pdf](_assets/bmpm_v2_1c_schematic.pdf) **Schematic** [bmpm_v2_1e_schematic.pdf](_assets/bmpm_v2_1e_schematic.pdf) @@ -58,7 +58,7 @@ Same form factor as the predecessor BMPM2. Following is a list of main differenc **Status** Legacy (not in production) -**Source** [Vendors](index.md#getting-hardware) +**Source** {ref}`Vendors` **Schematic** [bmpm_v2_0f_schematic.pdf](_assets/bmpm_v2_0f_schematic.pdf) @@ -75,7 +75,7 @@ Same form factor as the predecessor BMPM1. Following is a list of main differenc **Status** Legacy (not in production) -**Source** [Getting Hardware](index.md#getting-hardware) +**Source** {ref}`index:getting hardware` **Schematic** [blackmagic_mini.pdf](_assets/blackmagic_mini.pdf) diff --git a/index.md b/index.md index e5b2eaa..16174d7 100644 --- a/index.md +++ b/index.md @@ -95,11 +95,11 @@ The Black Magic GDB server features: * Implements USB DFU class for easy firmware upgrade as updates become available. * Works with Windows, Linux and Mac environments. -All you need is to install the [GNU cross compilation toolchain](https://en.wikipedia.org/wiki/Cross_compiler), containing [GCC](https://gcc.gnu.org/) and [GDB](https://www.sourceware.org/gdb/) for your microcontroller. Plug the Black Magic Probe hardware, running the Black Magic Debug firmware, into your computer. Instruct your GDB to use the BMP as your remote target using the `target extended-remote *serial_port*` command and you are off to the races. Further details are found in [Getting Started](getting-started.md). +All you need is to install the [GNU cross compilation toolchain](https://en.wikipedia.org/wiki/Cross_compiler), containing [GCC](https://gcc.gnu.org/) and [GDB](https://www.sourceware.org/gdb/) for your microcontroller. Plug the Black Magic Probe hardware, running the Black Magic Debug firmware, into your computer. Instruct your GDB to use the BMP as your remote target using the `target extended-remote *serial_port*` command and you are off to the races. Further details are found in {ref}`getting started`. If you are an embedded development beginner Black Magic Probe is also a great choice for you. But expect more of a Unix command line experience than a Windows [*klickybunti*](https://www.urbandictionary.com/define.php?term=klickibunti) GUI. -If anything is unclear or hard to understand [let us know](index.md#contact). Our goal is to make the documentation on this website comprehensive enough that it is all you need to get started with microcontroller development and debugging using the Black Magic Probe. +If anything is unclear or hard to understand {ref}`let us know `. Our goal is to make the documentation on this website comprehensive enough that it is all you need to get started with microcontroller development and debugging using the Black Magic Probe. ## Supported Targets @@ -128,14 +128,14 @@ The session goes through the following steps: ## Support the Project -The best way to support the project is purchasing the official [Black Magic Probe hardware](#getting-hardware). If you would like to support the project beyond that please consider supporting these individuals and organizations: +The best way to support the project is purchasing the official {ref}`Black Magic Probe hardware `. If you would like to support the project beyond that please consider supporting these individuals and organizations: * [Piotr Esden-Tempski (GitHub Sponsors)](https://github.com/sponsors/esden) * [Rachel Mant (GitHub Sponsors)](https://github.com/sponsors/dragonmux) * [1BitSquared (Patreon)](https://www.patreon.com/1bitsquared) ## Getting Hardware -The official Black Magic Probe hardware was specifically designed with Black Magic Debug in mind and the proceeds from the sales directly support and further the development of the software. See the [Support the Project](#support-the-project) section for other means of sponsoring the development of Black Magic Debug. +The official Black Magic Probe hardware was specifically designed with Black Magic Debug in mind and the proceeds from the sales directly support and further the development of the software. See the {ref}`index:support the project` section for other means of sponsoring the development of Black Magic Debug. The official Black Magic Probe hardware is available from these distributors in alphabetical order: * DE: [1BitSquared Germany](http://1bitsquared.de/products/black-magic-probe) Black Magic Probe V2.3 (Newest) @@ -155,7 +155,7 @@ The official Black Magic Probe hardware is available from these distributors in ## Black Magic Debug App (BMDA) -You can also compile the Black Magic Debug as a stand alone application instead of a firmware that you can flash onto a microcontroller. This mode resembles the way OpenOCD is used as an "application in the middle". Please find more details on the [hardware page](hardware.md#black-magic-debug-app). +You can also compile the Black Magic Debug as a stand alone application instead of a firmware that you can flash onto a microcontroller. This mode resembles the way OpenOCD is used as an "application in the middle". Please find more details on the {ref}`hardware page `. ## Contact: * If you have questions or suggestions feel free to join us in our chat [![Discord](https://img.shields.io/discord/613131135903596547?logo=discord)](https://discord.gg/P7FYThy) diff --git a/knowledge/faq.md b/knowledge/faq.md index baccd35..3a2c02b 100644 --- a/knowledge/faq.md +++ b/knowledge/faq.md @@ -38,8 +38,7 @@ There is experimental support for Cortex-A (ARMv7-A architecture). This is bein ## Where can I get the hardware? - -The official Black Magic Probe hardware is available from multiple vendors. An up to date list is kept on the [project main page](index.md#getting-hardware). +The official Black Magic Probe hardware is available from multiple vendors. An up to date list is kept on the {ref}`index:getting hardware`. ## Where can I find the BMP schematics? * [Black Magic Probe Mini v2.1](https://github.com/blackmagic-debug/blackmagic/wiki/files/bmpm_v2_1c_schematic.pdf) @@ -164,4 +163,4 @@ Because Texas Instruments... but we are working on it. :) If you want to help wi ## How do I upgrade to a more recent version? -Follow the [upgrade](/upgrade.md) instructions. +Follow the {ref}`upgrade` instructions. diff --git a/knowledge/pinouts.md b/knowledge/pinouts.md index bbe2cc4..089e30a 100644 --- a/knowledge/pinouts.md +++ b/knowledge/pinouts.md @@ -6,7 +6,7 @@ In the world of JTAG/SWD debuggers there is a plethora of different connectors. ![](../_pinouts/unified-legend.svg) -This connector is backwards compatible with the ubiquitous [ARM Cortex 10pin Debug connector](#arm-cortex-10pin-debug-connector). We have introduced this connector on the Black Magic Probe V2.3 hardware. To add the UART connections you will have to adjust the jumpers on the back of the board: +This connector is backwards compatible with the ubiquitous {ref}`knowledge/pinouts:arm cortex 10pin debug connector`. We have introduced this connector on the Black Magic Probe V2.3 hardware. To add the UART connections you will have to adjust the jumpers on the back of the board: - Cut the default RX jumpers with a sharp hobby knife. (These are the middle pad and the pad closest to the board edge.) You might want to test them using the continuity function on a multimeter to make sure they're disconnected. - Solder together the middle RX pad and the RX pad farthest from the board edge. @@ -24,7 +24,7 @@ There are several main connectors that are standard/very common on boards that u ![](../_pinouts/arm-cortex-10-legend.svg) -This is the connector provided on the Black Magic Probe debugger and is the most common JTAG/SWD connector. Keep in mind that since Black Magic Probe V2.3 we provide jumpers on the back side of the PCB allowing the user to change the connector to the [Black Magic Debug Unified Connector (BMDU)](#black-magic-debug-unified-connector-bmdu). +This is the connector provided on the Black Magic Probe debugger and is the most common JTAG/SWD connector. Keep in mind that since Black Magic Probe V2.3 we provide jumpers on the back side of the PCB allowing the user to change the connector to the {ref}`knowledge/pinouts:black magic debug unified connector (bmdu)`. ### ARM Cortex 20pin Debug & Trace Connector @@ -44,7 +44,7 @@ This connector is the old and trusty ARM JTAG connector. It is a bigger pitch (0 ![](../_pinouts/stdc14-legend.svg) -This is a custom connector that STMicroelectronics invented. It is backwards compatible with the [ARM Cortex 10Pin Debug Connector](#arm-cortex-10pin-debug-connector), so one can plug a 14pin ribbon cable into a 10pin debug connector if the connector is not fully shrouded. The ribbon cable will then overhang the connector by two pins on each side. If your target has this 14pin connector you can connect the Black Magic Probe by connecting a 14pin ribbon cable to the Black Magic Probe ([1BitSquared](https://1bitsquared.com/products/stdc14-idc-cable) is offering these cables in their store). +This is a custom connector that STMicroelectronics invented. It is backwards compatible with the {ref}`knowledge/pinouts:arm cortex 10pin debug connector`, so one can plug a 14pin ribbon cable into a 10pin debug connector if the connector is not fully shrouded. The ribbon cable will then overhang the connector by two pins on each side. If your target has this 14pin connector you can connect the Black Magic Probe by connecting a 14pin ribbon cable to the Black Magic Probe ([1BitSquared](https://1bitsquared.com/products/stdc14-idc-cable) is offering these cables in their store). ## SEGGER 20pin Debug Connector diff --git a/knowledge/terminology.md b/knowledge/terminology.md index 12b487c..be4bba0 100644 --- a/knowledge/terminology.md +++ b/knowledge/terminology.md @@ -2,7 +2,7 @@ Black Magic Debug consists of multiple elements that have fairly similar naming that can be confusing. To make this Change Log bit easier to decipher here is a little bit of history and term explanation. -Black Magic Debug (BMD) was originally designed as just a firmware for a purpose made hardware called Black Magic Probe (BMP) that can speak the GNU Debugger (GDB) “remote” serial protocol. The original BMP hardware is also called “native” as over time additional “Host” platforms were added that the firmware could be loaded onto. (Such host hardware can be an STM32F4 discovery board, or ST-Link hardware and [many more](../hardware.md)). +Black Magic Debug (BMD) was originally designed as just a firmware for a purpose made hardware called Black Magic Probe (BMP) that can speak the GNU Debugger (GDB) “remote” serial protocol. The original BMP hardware is also called “native” as over time additional “Host” platforms were added that the firmware could be loaded onto. (Such host hardware can be an STM32F4 discovery board, or ST-Link hardware and {ref}`many more `). Additionally BMD can also be compiled as a desktop program. We call it Black Magic (Debug) App and is formally known as **hosted**. It can act as a software in the middle, similar to the way OpenOCD works. In this case BMP is only acting as a USB to JTAG/SWD translator and the Black Magic App does all the heavy lifting. Additionally this also allows the use of BMA with other probe hardware running non Black Magic Firmware (BMF), like for example: SEGGER J-Link, ST-Link, sw-link, FTDI and more. diff --git a/usage/gdb-automation.md b/usage/gdb-automation.md index c115d99..cb54ac8 100644 --- a/usage/gdb-automation.md +++ b/usage/gdb-automation.md @@ -51,7 +51,7 @@ arm-none-eabi-gdb -nx --batch \ ## Makefile -If you are using GNU Makefiles for your project you can add a `make flash` target. Reusing the script from the [Commandline](#commandline) section above the target like that can look something like this: +If you are using GNU Makefiles for your project you can add a `make flash` target. Reusing the script from the {ref}`Commandline ` section above the target like that can look something like this: ```makefile diff --git a/usage/platformio.md b/usage/platformio.md index dc35e24..d00cd2d 100644 --- a/usage/platformio.md +++ b/usage/platformio.md @@ -7,11 +7,11 @@ **Frameworks:** Arduino, ARTIK SDK, CMSIS, Energia, ESP-IDF, libOpenCM3, mbed, Pumbaa, Simba, SPL, STM32Cube, WiringPi ## Contents -- [PIO Unified Debugger](#pio-unified-debugger) -- [Quick Start](#quick-start) -- [Debugging from CLI](#debugging-from-cli) -- [Advanced configuration](#advanced-configuration) -- [Issues and support](#issues-and-support) +- {ref}`usage/platformio:pio unified debugger` +- {ref}`usage/platformio:quick start` +- {ref}`usage/platformio:debugging from cli` +- {ref}`usage/platformio:advanced configuration` +- {ref}`usage/platformio:issues and support` ## PIO Unified Debugger @@ -30,7 +30,7 @@ See a full list of [compatible boards for Black Magic Probe](http://docs.platfor 1. Install [PlatformIO IDE](https://platformio.org/platformio-ide?utm_source=github&utm_medium=blackmagic). 2. Create a new project using "PlatformIO Home > New Project" wizard (🏠 icon on the toolbar) -3. Edit **Project Configuration File** [platformio.ini](http://docs.platformio.org/en/latest/projectconf.html?utm_source=github&utm_medium=blackmagic) and set Black Magic Probe as default tool for debugging and programming/uploading, update `upload/debug` port following [this guide](gdb-commands.md): +3. Edit **Project Configuration File** [platformio.ini](http://docs.platformio.org/en/latest/projectconf.html?utm_source=github&utm_medium=blackmagic) and set Black Magic Probe as default tool for debugging and programming/uploading, update `upload/debug` port following {ref}`this guide `: ```ini [env:someboard] diff --git a/usage/rtt.md b/usage/rtt.md index d1eeec1..a3fbcda 100644 --- a/usage/rtt.md +++ b/usage/rtt.md @@ -8,13 +8,13 @@ the host: * Real-Time Transfer (RTT). To enable RTT in [Black Magic Debug](https://black-magic.org) (BMD) Firmware, the `ENABLE_RTT=1` flag has to be -set during compilation. For more details refer to the [Build Instructions](#build-instructions) section. +set during compilation. For more details refer to the {ref}`usage/rtt:build instructions` section. The RTT solution implemented in BMD uses a novel way to detect RTT automatically, making it fast and convenient. ## Usage -This example uses Linux as operating system. For Windows and macOS see the [Operating Systems](#operating-systems) section. +This example uses Linux as operating system. For Windows and macOS see the {ref}`usage/rtt:operating systems` section. In one window open a terminal emulator (minicom, putty, etc) and connect to the USB UART: ``` @@ -180,7 +180,7 @@ without specifying an identifier string. ## Operating Systems -[Configuration](../getting-started.md) instructions for Windows, Linux and MacOS. +{ref}`Configuration ` instructions for Windows, Linux and MacOS. ### Windows diff --git a/usage/swo.md b/usage/swo.md index 3c6f737..305505a 100644 --- a/usage/swo.md +++ b/usage/swo.md @@ -81,4 +81,4 @@ Viewers: ![](https://github.com/compuphase/Black-Magic-Probe-Book/raw/master/doc/bmtrace.png) * [orbuculum](https://github.com/orbcode/orbuculum) (linux, command line) Advanced. Has gdb init scripts and target c source in the Support/ directory. * [swo_listen](https://github.com/blackmagic-debug/blackmagic/blob/master/scripts/swolisten.c) (linux, command line) -* [bmp_traceswo](https://github.com/nickd4/bmp_traceswo) and [fork](https://github.com/tristanseifert/bmp_traceswo) (linux, command line) [detailed write-up](traceswo.md) +* [bmp_traceswo](https://github.com/nickd4/bmp_traceswo) and [fork](https://github.com/tristanseifert/bmp_traceswo) (linux, command line) {ref}`detailed write-up ` From 49a01450174129ceeae84f4f7599ef2e3b180ffe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 18:52:39 +0100 Subject: [PATCH 10/16] getting-started: link to https --- getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started.md b/getting-started.md index 4ead8a1..3669ec2 100644 --- a/getting-started.md +++ b/getting-started.md @@ -27,7 +27,7 @@ On Windows, when you first connect, the Black Magic Probe should be detected as __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:__ 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) From 5525389b86c91d04074c077256be19d618040408 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 19:39:53 +0100 Subject: [PATCH 11/16] conf: add url builder helper --- conf.py | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/conf.py b/conf.py index baaf7fa..28c968a 100644 --- a/conf.py +++ b/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 -------------------------------------------------------------- @@ -87,7 +98,7 @@ # -- Options for HTML output ------------------------------------------------- -html_baseurl = 'https://black-magic.org' +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. @@ -122,7 +133,7 @@ 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 From 6cbad7063e998fa4eb9e3cc2216506f869396063 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 19:47:34 +0100 Subject: [PATCH 12/16] extlink: add 1b2-product --- conf.py | 4 ++++ hacking/target-cortex-m.md | 4 ++-- hardware.md | 2 +- index.md | 4 ++-- knowledge/faq.md | 12 ++++++------ knowledge/pinouts.md | 6 +++--- 6 files changed, 18 insertions(+), 14 deletions(-) diff --git a/conf.py b/conf.py index 28c968a..542b49d 100644 --- a/conf.py +++ b/conf.py @@ -41,6 +41,7 @@ def build_url(netloc='', path='', params='', query='', fragment='', scheme='http # URLs netloc_1b2 = '1bitsquared.com' +netloc_1b2_eu = netloc_1b2.replace('.com', '.de') github_org_slug = 'blackmagic-debug' github_bmd_slug = 'blackmagic' @@ -72,7 +73,10 @@ def build_url(netloc='', path='', params='', query='', fragment='', scheme='http } extlinks = { + '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'), } # Produce warnings for hard-coded external links that can be replaced with extlinks diff --git a/hacking/target-cortex-m.md b/hacking/target-cortex-m.md index 2a2543e..4019a85 100644 --- a/hacking/target-cortex-m.md +++ b/hacking/target-cortex-m.md @@ -75,7 +75,7 @@ and a PicoBlade serial port cable, you can push the connectors on the serial por 10-pin debug target connector. The connection sequence from the PicoBlade -(with the [1BitSquared cable](https://1bitsquared.com/products/black-magic-01in-pin-header-serial-cable)) +(with the {1b2-product}`1BitSquared cable`) to the 10-pin debug target connector is: * PicoBlade Pin 1 (red) => 10-pin connector pin 1 @@ -97,7 +97,7 @@ the firmware and evaluating its function by reading the output from `DEBUG_*` st With newer generation (v2.1 hardware and newer) BMPs, there is a dedicated set of 0.05" (1.27mm) pin headers provided to allow connecting one BMP to another using a -[1BitSquared JTAG SWD adaptor](https://1bitsquared.com/collections/accessories/products/jtag-swd-adapter) +{1b2-product}`1BitSquared JTAG SWD adaptor` or the 5-pin variant of this which includes the ~RST signal too. To use this, simply plug the adaptor in as labeled on the BMP you want to debug, connect a 10-pin IDC cable between it diff --git a/hardware.md b/hardware.md index 3bd4066..8e3a7ae 100644 --- a/hardware.md +++ b/hardware.md @@ -43,7 +43,7 @@ Same form factor as the predecessor BMPM2. Following is a list of main differenc * Replaces the TXS0108 bidirectional level shifter with dual supply 74LVC2T45 bus transceivers. This improves the line drive strength and expands the target voltage range to 1.8V-5V (previous design was limited to 1.8V-3.3V) * Dedicated reset line drive MOSFET circuitry with 10k pull-up ensuring good open-drain RST line drive with monitoring. -* Exposed the BMP side SWD lines on dedicated pads, allowing for easier programming and debugging of the probe firmware. It is much easier now to program and debug the BMP firmware using a second BMP. The pinout is compatible with the [SWD adapter by 1Bitsquared](https://1bitsquared.com/products/jtag-swd-adapter). +* Exposed the BMP side SWD lines on dedicated pads, allowing for easier programming and debugging of the probe firmware. It is much easier now to program and debug the BMP firmware using a second BMP. The pinout is compatible with the {1b2-product}`SWD adapter by 1Bitsquared`. * Increased LED distance from each other for better visual separation. * (V2.1e revision) Added a normally open jumper to allow the connection of the `TRACESWO` signal to `UART1_RX` on pin `PB7`. This pin is also the highest order bit of the hardware version. Because of that, all BMPM V2.1e have the hardware version stored as a user `Data0` option byte at address `0x1FFFF804`. The hardware version corresponding to V2.1e is `0x04`. Firmware that implements UART SWO decoding should check the hardware version in the option bytes first. (this feature is not yet supported in current blackmagic probe firmware) diff --git a/index.md b/index.md index 16174d7..64f4b75 100644 --- a/index.md +++ b/index.md @@ -138,8 +138,8 @@ The best way to support the project is purchasing the official {ref}`Black Magic The official Black Magic Probe hardware was specifically designed with Black Magic Debug in mind and the proceeds from the sales directly support and further the development of the software. See the {ref}`index:support the project` section for other means of sponsoring the development of Black Magic Debug. The official Black Magic Probe hardware is available from these distributors in alphabetical order: - * DE: [1BitSquared Germany](http://1bitsquared.de/products/black-magic-probe) Black Magic Probe V2.3 (Newest) - * USA: [1BitSquared US](http://1bitsquared.com/collections/frontpage/products/black-magic-probe) Black Magic Probe V2.3 (Newest) + * DE: {1b2-product-eu}`1BitSquared Germany ` Black Magic Probe V2.3 (Newest) + * USA: {1b2-product}`1BitSquared US ` Black Magic Probe V2.3 (Newest) * USA: [Adafruit Industries](https://www.adafruit.com/product/3839) Black Magic Probe with JTAG Cable and Serial Cable - V2.3 (Newest) ## Other Hardware supported by Black Magic Debug: diff --git a/knowledge/faq.md b/knowledge/faq.md index 3a2c02b..f831aab 100644 --- a/knowledge/faq.md +++ b/knowledge/faq.md @@ -47,7 +47,7 @@ The official Black Magic Probe hardware is available from multiple vendors. An u * [Original Black Magic Probe](https://github.com/blackmagic-debug/blackmagic/wiki/files/blackmagic-1.0.pdf) ## What are those JTAG/SWD connectors and cables? -The JTAG/SWD connector is [FTSH-105-01-F-DV-K from Samtec](https://www.samtec.com/products/ftsh-105-01-f-dv-k) (Buy: [Digi-key](http://www.digikey.com/product-detail/en/FTSH-105-01-F-DV-K/FTSH-105-01-F-DV-K-ND/2649974), [1BitSquared](https://1bitsquared.com/products/jtag-swd-smd-connector)). +The JTAG/SWD connector is [FTSH-105-01-F-DV-K from Samtec](https://www.samtec.com/products/ftsh-105-01-f-dv-k) (Buy: [Digi-key](http://www.digikey.com/product-detail/en/FTSH-105-01-F-DV-K/FTSH-105-01-F-DV-K-ND/2649974), {1b2-product}`1BitSquared `). The JTAG/SWD connector is a 0.05" (50mil/1.27mm) pitch, 2 row 10pin connector. The Samtec version is the only one that includes a keying shroud and does not occupy a large space on the PCB. There are other manufacturers that make connectors that can be used too. Here are a few options: * Amphenol FCI 20021121-00010C4LF unshrouded SMD (Buy: [Digi-key](https://www.digikey.com/product-detail/en/amphenol-fci/20021121-00010C4LF/609-3695-1-ND/2209147)) @@ -58,7 +58,7 @@ The JTAG/SWD connector is a 0.05" (50mil/1.27mm) pitch, 2 row 10pin connector. T * CNC Tech 3220-10-0100-00 shrouded TH (Buy: [Digi-key](https://www.digikey.com/product-detail/en/cnc-tech/3220-10-0100-00/1175-1627-ND/3883661)) * And many many more ... 😸 -The JTAG/SWD cable is [FFSD-05-D-xx.xx-01-N](https://www.samtec.com/products/ffsd-05-d-06.00-01-n) where the `x` stand for the length of the cable. Common length is 6 inches. (Buy: [Digi-key](https://www.digikey.com/product-detail/en/samtec-inc/FFSD-05-D-06.00-01-N/SAM8218-ND/1106577), [1BitSquared](https://1bitsquared.com/products/jtag-idc-cable)) +The JTAG/SWD cable is [FFSD-05-D-xx.xx-01-N](https://www.samtec.com/products/ffsd-05-d-06.00-01-n) where the `x` stand for the length of the cable. Common length is 6 inches. (Buy: [Digi-key](https://www.digikey.com/product-detail/en/samtec-inc/FFSD-05-D-06.00-01-N/SAM8218-ND/1106577), {1b2-product}`1BitSquared `) You can build your own JTAG/SWD ribbon cable using the following materials. (consider just an example there are many manufacturers making 1.27mm pitch IDC crimps and ribbons) * CNC Tech 3230-10-0103-00 IDC crimp with polarizing key. (Buy: [Digi-key](https://www.digikey.com/product-detail/en/cnc-tech/3230-10-0103-00/1175-1646-ND/3883463)) @@ -76,15 +76,15 @@ The UART cable can be built by hand using the following materials: The UART cable can also be built with pre crimped wires: * [Digi-key](https://www.digikey.com/short/08n0q938) Molex Picoblade pre-crimped cables, you can choose from all kinds of colors as well as doublesided or single sided crimps. -* [1BitSquared](https://1bitsquared.com/products/picoblade-wire-kit) pre-crimped cable assortment +* {1b2-product}`1BitSquared ` pre-crimped cable assortment There are also pre made UART cables: -* [1BitSquared](https://1bitsquared.com/products/black-magic-01in-pin-header-serial-cable) UART to 0.1" pin header pigtail cable. -* [1BitSquared](https://1bitsquared.com/products/serial-interface-cable) UART to [Paparazzi UAV](http://paparazziuav.org) autopilot cable. +* {1b2-product}`1BitSquared ` UART to 0.1" pin header pigtail cable. +* {1b2-product}`1BitSquared ` UART to [Paparazzi UAV](http://paparazziuav.org) autopilot cable. ## Where can I find different JTAG/SWD connectors? (Adapters & Cables) -Many vendors provide adapters allowing easy connection between different JTAG/SWD and UART interfaces. For example [1BitSquared](https://1bitsquared.com/collections/embedded-hardware) offers a wide range of different adapters and cables. There is also a collection of adapter designs that you can find on the [1BitSquared GitHub Page](https://github.com/1bitsquared/1b2-adapter-collection) that you can use as basis for your custom adapter. If there is an adapter missing for your specific application it is usually quite easy to put one together using [KiCad](http://kicad.org/) and order the needed board from [OSHPark](https://oshpark.com/). +Many vendors provide adapters allowing easy connection between different JTAG/SWD and UART interfaces. For example {1b2}`1BitSquared ` offers a wide range of different adapters and cables. There is also a collection of adapter designs that you can find on the [1BitSquared GitHub Page](https://github.com/1bitsquared/1b2-adapter-collection) that you can use as basis for your custom adapter. If there is an adapter missing for your specific application it is usually quite easy to put one together using [KiCad](http://kicad.org/) and order the needed board from [OSHPark](https://oshpark.com/). ## Are binary firmware images available for download? diff --git a/knowledge/pinouts.md b/knowledge/pinouts.md index 089e30a..6e59db9 100644 --- a/knowledge/pinouts.md +++ b/knowledge/pinouts.md @@ -32,7 +32,7 @@ This is the connector provided on the Black Magic Probe debugger and is the most This connector is an expansion of the ARM Cortex 10pin debug connector and adds the parallel trace interface (Embedded Trace Macrocell). This connector can be directly used with the [ORBTrace Mini](https://orbcode.org/orbtrace-mini/). -If your target has the 20pin connector and you would like to connect the Black Magic Probe to that target. You can use a 10 to 20 pin ribbon cable that allows the connection of one half of the pins to the Black Magic Probe. ([1BitSquared](https://1bitsquared.com/products/jtag-swd-10pin-to-20pin-idc-cable) is offering this cable in their store). +If your target has the 20pin connector and you would like to connect the Black Magic Probe to that target. You can use a 10 to 20 pin ribbon cable that allows the connection of one half of the pins to the Black Magic Probe. ({1b2-product}`1BitSquared store ` is offering these cables). ## ARM JTAG Connector @@ -44,7 +44,7 @@ This connector is the old and trusty ARM JTAG connector. It is a bigger pitch (0 ![](../_pinouts/stdc14-legend.svg) -This is a custom connector that STMicroelectronics invented. It is backwards compatible with the {ref}`knowledge/pinouts:arm cortex 10pin debug connector`, so one can plug a 14pin ribbon cable into a 10pin debug connector if the connector is not fully shrouded. The ribbon cable will then overhang the connector by two pins on each side. If your target has this 14pin connector you can connect the Black Magic Probe by connecting a 14pin ribbon cable to the Black Magic Probe ([1BitSquared](https://1bitsquared.com/products/stdc14-idc-cable) is offering these cables in their store). +This is a custom connector that STMicroelectronics invented. It is backwards compatible with the {ref}`knowledge/pinouts:arm cortex 10pin debug connector`, so one can plug a 14pin ribbon cable into a 10pin debug connector if the connector is not fully shrouded. The ribbon cable will then overhang the connector by two pins on each side. If your target has this 14pin connector you can connect the Black Magic Probe by connecting a 14pin ribbon cable to the Black Magic Probe ({1b2-product}`1BitSquared store ` is offering these cables). ## SEGGER 20pin Debug Connector @@ -52,7 +52,7 @@ This is a custom connector that STMicroelectronics invented. It is backwards com This is a custom connector used on SEGGER J-Link and J-Trace debug probes, designed to be loosely compatible with the {ref}`knowledge/pinouts:arm jtag connector`. -Targets using this connector can be directly interfaced with {ref}`hardware:native hardware` probes using a 20Pin JTAG adapter board found on the [1BitSquared](https://1bitsquared.com/collections/accessories/products/20pin-jtag-adapter) store. +Targets using this connector can be directly interfaced with {ref}`hardware:native hardware` probes using a 20Pin JTAG adapter board found on the {1b2-product}`1BitSquared store <20pin-jtag-adapter>`. SEGGER J-Link probes using this connector can interface directly with targets using the {ref}`knowledge/pinouts:black magic debug unified connector (bmdu)` using the same 20Pin JTAG adapter board. From 6a5fd3da9dc8419e841a453168f8b12b92dd9efb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 19:51:59 +0100 Subject: [PATCH 13/16] extlink: add BMD github related --- conf.py | 5 +++++ getting-started.md | 2 +- hacking/contrib.md | 4 ++-- hacking/hacking.md | 6 +++--- hacking/target-clock-generation.md | 12 ++++++------ hacking/target-drivers.md | 24 ++++++++++++------------ hardware.md | 8 ++++---- index.md | 16 ++++++++-------- knowledge/faq.md | 16 ++++++++-------- upgrade.md | 22 +++++++++++----------- usage/swo.md | 6 +++--- 11 files changed, 63 insertions(+), 58 deletions(-) diff --git a/conf.py b/conf.py index 542b49d..24bf88c 100644 --- a/conf.py +++ b/conf.py @@ -40,8 +40,10 @@ def build_url(netloc='', path='', params='', query='', fragment='', scheme='http 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' @@ -73,6 +75,9 @@ def build_url(netloc='', path='', params='', query='', fragment='', scheme='http } 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'), diff --git a/getting-started.md b/getting-started.md index 3669ec2..9c860fd 100644 --- a/getting-started.md +++ b/getting-started.md @@ -25,7 +25,7 @@ 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 `. __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: diff --git a/hacking/contrib.md b/hacking/contrib.md index 592871f..4f96e72 100644 --- a/hacking/contrib.md +++ b/hacking/contrib.md @@ -3,7 +3,7 @@ ## 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` * 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/) @@ -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`. diff --git a/hacking/hacking.md b/hacking/hacking.md index d49d995..33e79cf 100644 --- a/hacking/hacking.md +++ b/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` 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` 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`. 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 diff --git a/hacking/target-clock-generation.md b/hacking/target-clock-generation.md index cb93236..93d991c 100644 --- a/hacking/target-clock-generation.md +++ b/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`. 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`. 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` 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`` 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` 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`. These are the values from the linear regression called out in the above section - workbook sheet "Data", cells B9 and B12. diff --git a/hacking/target-drivers.md b/hacking/target-drivers.md index 04d5024..c486143 100644 --- a/hacking/target-drivers.md +++ b/hacking/target-drivers.md @@ -2,24 +2,24 @@ ## External target API -You can find the public API in [`target.h`](https://github.com/blackmagic-debug/blackmagic/blob/main/src/include/target.h), used by the GDB server. Nothing defined in `src/target` outside of this header should be accessed from outside of `src/target/*` +You can find the public API in {bmd-gh}``target.h``, used by the GDB server. Nothing defined in `src/target` outside of this header should be accessed from outside of `src/target/*` ## Internal target API There are several internal API headers: -* [`target/target_internal.h`](https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/target_internal.h) +* {bmd-gh}``target/target_internal.h`` This header contains structure definitions and convenience functions for use in target support implementations. Specific target implementations fill in the function pointers in these structures for their device specific implementations. -* [`target/target_probe.h`](https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/target_probe.h) +* {bmd-gh}``target/target_probe.h`` This header contains declarations for all the *_probe functions so they're all declared in one central place. This header works in tandem with `target/target_probe.c` to allow any target support implementation to be switched off as-needed without this breaking the build. ## Raw JTAG Devices -Supported JTAG devices are defined in [target/jtag_devs.c](https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/jtag_devs.c) +Supported JTAG devices are defined in {bmd-gh}`target/jtag_devs.c` The `.handler` function is called when a device's ID Code matches the `.idcode` field with `.idmask` applied. It is the responsibility of the handler function to instantiate a new target with `target_new` and fill in @@ -28,7 +28,7 @@ the access function pointers. ### Raw JTAG access There is a global structure of function pointers, `jtag_proc` defined in -[`jtagtap.h`](https://github.com/blackmagic-debug/blackmagic/blob/main/src/include/jtagtap.h), which is +{bmd-gh}`jtagtap.h`, which is automatically initialised to provide access to raw JTAG bus access routines: ```c @@ -64,7 +64,7 @@ There are also some helper macros defined for running certain known sequences on ### TAP-layer access There are higher level access functions defined in -[`target/jtag_scan.h`](https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/jtag_scan.h). +{bmd-gh}`target/jtag_scan.h`. These functions provide higher level access to the JTAG IR and DR registers: @@ -83,12 +83,12 @@ void jtag_dev_shift_dr(uint8_t dev_index, uint8_t *data_out, const uint8_t *data There are a few moving parts to the ADIv5 (ARM Debug Interface v5) implementation. The most important ones are: * The debug interface logic itself found in - [`target/adiv5.c`](https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/adiv5.c). + {bmd-gh}``target/adiv5.c``. * The generic logic for Cortex-M parts which is found in - [`target/cortexm.c`](https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/cortexm.c). + {bmd-gh}``target/cortexm.c``. Please note, this presently supports the ARMv6-M and ARMv7-M profiles only. * The generic logic for Cortex-A parts which is found in - [`target/cortexa.c`](https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/cortexa.c). + {bmd-gh}``target/cortexa.c``. Please note, this presently supports the ARMv7-M profile only. ### ADIv5 Coresight identification @@ -100,7 +100,7 @@ specification. When a device is identified during scan that talks ADIv5, the various Coresight CIDR and PIDR values get read out automatically and decoded. A list of known component class values can be found at the top of `adiv5.c` and a list of known JEP-106 manufacturer codes (encoded in the PIDR register for each ROM table chunk that must be read) -can be found in the [`target/adiv5.h`](https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/adiv5.h) +can be found in the {bmd-gh}``target/adiv5.h`` header. Once an AP has been identified as belonging to either a Cortex-M or a Cortex-A core, the ADIv5 code dispatches to @@ -294,9 +294,9 @@ static bool skeleton_flash_write(target_flash_s *flash, target_addr_t dest, cons ``` In addition to this, you *must* declare your new probe routine in -[`target/target_probe.h`](https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/target_probe.h), +{bmd-gh}``target/target_probe.h``, and also define a weak linked stub for it in -[`target/target_probe.c`](https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/target_probe.c) +{bmd-gh}``target/target_probe.c`` The existing stubs should serve as a decent example for how to do this. diff --git a/hardware.md b/hardware.md index 8e3a7ae..bc06733 100644 --- a/hardware.md +++ b/hardware.md @@ -120,7 +120,7 @@ You can compile the firmware for an ST-Link debugger. These are often included o ## ST-Link v2 -Instructions to restore an ST-Link v2 with recent original ST firmware can be found on [GitHub in the stlink platform README](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/stlink#reverting-to-original-st-firmware-with-running-bmp-firmware). +Instructions to restore an ST-Link v2 with recent original ST firmware can be found on {bmd-gh}`GitHub in the stlink platform README`. ## F4 Discovery @@ -128,7 +128,7 @@ You can run the Black Magic Probe firmware on the "target" processor of an ST F4 ## Black Pill F4: F401CC / F401CE / F411CE -The black magic firmware can be built and flashed to Black Pill boards with STM32F401CC, STM32F401CE and STM32F411CE microcontrollers. Since these microcontrollers have slightly different hardware specifications in terms of flash, sram and clock frequency, each microcontroller has its own platform. The platforms share [common code](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/common/blackpill-f4). This page also contains build and firmware upgrade instructions. +The black magic firmware can be built and flashed to Black Pill boards with STM32F401CC, STM32F401CE and STM32F411CE microcontrollers. Since these microcontrollers have slightly different hardware specifications in terms of flash, sram and clock frequency, each microcontroller has its own platform. The platforms share {bmd-gh}`common code`. This page also contains build and firmware upgrade instructions. ## SW Link @@ -146,7 +146,7 @@ The `stlink` platform does not reuse the SWD debug pins. | SWDIO | PB14 | | SWCLK | PA5 | -For the detailed pinout see [stlink platform.h](https://github.com/blackmagic-debug/blackmagic/blob/main/src/platforms/stlink/platform.h). +For the detailed pinout see {bmd-gh}`stlink platform.h`. The code can be build using ``` @@ -162,7 +162,7 @@ The `swlink` platform remaps the SWD debug pins as bit-bang SWD output. Full JTA | SWDIO | PA13 | | SWCLK | PA14 | -For the detailed pinout see [swlink platform.h](https://github.com/blackmagic-debug/blackmagic/blob/main/src/platforms/swlink/platform.h). +For the detailed pinout see {bmd-gh}`swlink platform.h`. ## LaunchPad ICDI diff --git a/index.md b/index.md index 64f4b75..3e1044c 100644 --- a/index.md +++ b/index.md @@ -144,14 +144,14 @@ The official Black Magic Probe hardware is available from these distributors in ## Other Hardware supported by Black Magic Debug: - * ST-Link v2, v2.1 and Blue Pill. See [stlink](https://github.com/blackmagic-debug/blackmagic/tree/master/src/platforms/stlink) - * ST-Link v3. See [stlinkv3](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/stlinkv3) - * STM8S Discovery (ST-Link V1). See [swlink](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/swlink) - * F4 Discovery (STM32F407). See [f4discovery](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/f4discovery) - * Black Pill F4 (STM32F401CC/STM32F401CE/STM32F411CE). See [blackpill-f401cc](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/blackpill-f401cc), [blackpill-f401ce](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/blackpill-f401ce), [blackpill-f411ce](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/blackpill-f411ce) - * TI LaunchPad Tiva C onboard programmer. See [launchpad-icdi](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/launchpad-icdi) - * [HydraBus](https://hydrabus.com/). See [hydrabus](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/hydrabus) - * [96Boards Carbon](https://www.96boards.org/product/carbon/). See [96_carbon](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/96b_carbon) + * ST-Link v2, v2.1 and Blue Pill. See {bmd-gh}`stlink` + * ST-Link v3. See {bmd-gh}`stlinkv3` + * STM8S Discovery (ST-Link V1). See {bmd-gh}`swlink` + * F4 Discovery (STM32F407). See {bmd-gh}`f4discovery` + * Black Pill F4 (STM32F401CC/STM32F401CE/STM32F411CE). See {bmd-gh}`blackpill-f401cc`, [blackpill-f411ce](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms/blackpill-f411ce>` + * TI LaunchPad Tiva C onboard programmer. See {bmd-gh}`launchpad-icdi` + * [HydraBus](https://hydrabus.com/). See {bmd-gh}`hydrabus` + * [96Boards Carbon](https://www.96boards.org/product/carbon/). See {bmd-gh}`96_carbon` ## Black Magic Debug App (BMDA) diff --git a/knowledge/faq.md b/knowledge/faq.md index f831aab..1fcee0f 100644 --- a/knowledge/faq.md +++ b/knowledge/faq.md @@ -41,10 +41,10 @@ There is experimental support for Cortex-A (ARMv7-A architecture). This is bein The official Black Magic Probe hardware is available from multiple vendors. An up to date list is kept on the {ref}`index:getting hardware`. ## Where can I find the BMP schematics? - * [Black Magic Probe Mini v2.1](https://github.com/blackmagic-debug/blackmagic/wiki/files/bmpm_v2_1c_schematic.pdf) - * [Black Magic Probe Mini v2.0](https://github.com/blackmagic-debug/blackmagic/wiki/files/bmpm_v2_0f_schematic.pdf) - * [Black Magic Probe Mini](https://github.com/blackmagic-debug/blackmagic/wiki/files/blackmagic_mini.pdf) - * [Original Black Magic Probe](https://github.com/blackmagic-debug/blackmagic/wiki/files/blackmagic-1.0.pdf) + * {bmd-gh}`Black Magic Probe Mini v2.1` + * {bmd-gh}`Black Magic Probe Mini v2.0` + * {bmd-gh}`Black Magic Probe Mini` + * {bmd-gh}`Original Black Magic Probe` ## What are those JTAG/SWD connectors and cables? The JTAG/SWD connector is [FTSH-105-01-F-DV-K from Samtec](https://www.samtec.com/products/ftsh-105-01-f-dv-k) (Buy: [Digi-key](http://www.digikey.com/product-detail/en/FTSH-105-01-F-DV-K/FTSH-105-01-F-DV-K-ND/2649974), {1b2-product}`1BitSquared `). @@ -88,7 +88,7 @@ Many vendors provide adapters allowing easy connection between different JTAG/SW ## Are binary firmware images available for download? -Automatically built firmware images for the official hardware are [here](https://github.com/blackmagic-debug/blackmagic/releases). +Automatically built firmware images for the official hardware are {bmd-gh}`here `. ## How can I access memory mapped I/O from GDB? @@ -109,7 +109,7 @@ set mem inaccessible-by-default off set {int}0x40048000 = 2 ``` -This solution is known to work on the LPC8xx/LPC11xx families of chips. If you are using something different refer to the reference manual and look for `SYSMEMREMAP` register. If the address differs please add it to this FAQ item or let us know in the [Discord #blackmagic channel](https://discord.gg/P7FYThy) or mailing list. For the discussion of this problem refer to issue [#99](https://github.com/blackmagic-debug/blackmagic/issues/99). +This solution is known to work on the LPC8xx/LPC11xx families of chips. If you are using something different refer to the reference manual and look for `SYSMEMREMAP` register. If the address differs please add it to this FAQ item or let us know in the [Discord #blackmagic channel](https://discord.gg/P7FYThy) or mailing list. For the discussion of this problem refer to {bmd-issue}`99`. ## It's annoying to look up an always-changing device name on Linux. @@ -147,7 +147,7 @@ There are a few advantages of the Black Magic Probe. BMP is open-source, meaning ## Why is XXX not supported? -Because nobody implemented the required functions yet. Look on [GitHub](https://github.com/blackmagic-debug/blackmagic/pulls) if there is a pending pull request for your target. Consider testing PRs that try to implement the desired target to help us triage merge of new hardware support. +Because nobody implemented the required functions yet. Look on {bmd-gh}`GitHub ` if there is a pending pull request for your target. Consider testing PRs that try to implement the desired target to help us triage merge of new hardware support. ## Why is Raspberry Pi 1 not supported? @@ -159,7 +159,7 @@ Because it is a 64Bit architecture. We are working on adding 64bit support but i ## Why is Beagle Bone Black not supported? -Because Texas Instruments... but we are working on it. :) If you want to help with that contact us on [![Discord](https://img.shields.io/discord/613131135903596547?logo=discord)](https://discord.gg/P7FYThy). See [issue #166](https://github.com/blackmagic-debug/blackmagic/issues/166) for details. +Because Texas Instruments... but we are working on it. :) If you want to help with that contact us on [![Discord](https://img.shields.io/discord/613131135903596547?logo=discord)](https://discord.gg/P7FYThy). See {bmd-issue}`166` for details. ## How do I upgrade to a more recent version? diff --git a/upgrade.md b/upgrade.md index 49ee2f0..ca49804 100644 --- a/upgrade.md +++ b/upgrade.md @@ -4,9 +4,9 @@ Download or compile the Black Magic Debug (BMD) firmware. Regarding firmware selection: -* You can find the newest pre-built binaries on the [GitHub Release Page](https://github.com/blackmagic-debug/blackmagic/releases). -* You can find the bleeding cutting edge binaries uploaded as assets on the ["build and upload" GitHub actions page](https://github.com/blackmagic-debug/blackmagic/actions/workflows/build-and-upload.yml), Click on the newest successful build and download the `blackmagic-firmware.zip` file. It contains binaries for all the supported platforms. -* When using the daily builds expect breaking changes. Please report issues on [our issue page](https://github.com/blackmagic-debug/blackmagic/issues) or ask on our Discord server. +* You can find the newest pre-built binaries on the {bmd-gh}`GitHub Release Page`. +* You can find the bleeding cutting edge binaries uploaded as assets on the {bmd-gh}`"build and upload" GitHub actions page`, Click on the newest successful build and download the `blackmagic-firmware.zip` file. It contains binaries for all the supported platforms. +* When using the daily builds expect breaking changes. Please report issues on {bmd-issue}`our issue page<>` or ask on our Discord server. Upgrade the firmware of the Black Magic Debug Probe using either: - bmputil @@ -15,7 +15,7 @@ Upgrade the firmware of the Black Magic Debug Probe using either: ### bmputil -Clone and build the [bmputil](https://github.com/blackmagic-debug/bmputil) tool. +Clone and build the {black-magic-org-gh}`bmputil` tool. Plug your Black Magic Probe into your computer and run the following command: @@ -35,7 +35,7 @@ Plug the Black Magic Probe into your computer and run the following command: sudo dfu-util -d 1d50:6018,:6017 -s 0x08002000:leave -D blackmagic-native.bin ``` -To upgrade non-native hardware see the readme of the different [platforms on GitHub](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms). +To upgrade non-native hardware see the readme of the different {bmd-gh}`platforms on GitHub`. ```{note} If `dfu-util` fails to switch your BMP into bootloader mode, or you feel like you might have **bricked** your BMP, you can also plug in your BMP while holding down the button. This will force the BMP to stay in the bootloader on power up. @@ -43,7 +43,7 @@ If `dfu-util` fails to switch your BMP into bootloader mode, or you feel like yo ### stlink-tool -The firmware on an ST-Link can be upgraded using [blackmagic-debug/stlink-tool](https://github.com/blackmagic-debug/stlink-tool). +The firmware on an ST-Link can be upgraded using {black-magic-org-gh}`blackmagic-debug/stlink-tool`. To upgrade, run the following command: @@ -59,9 +59,9 @@ This software upgrades the firmware of the ST-Link probe, **not** the firmware o Download or compile the Black Magic Debug (BMD) firmware. Regarding firmware selection: -* You can find the newest pre-built binaries on the [GitHub Release Page](https://github.com/blackmagic-debug/blackmagic/releases). -* You can find the bleeding cutting edge binaries uploaded as assets on the ["build and upload" GitHub actions page](https://github.com/blackmagic-debug/blackmagic/actions/workflows/build-and-upload.yml), Click on the newest successful build and download the `blackmagic-firmware.zip` file. It contains binaries for all the supported platforms. -* When using the daily builds expect breaking changes. Please report issues on [our issue page](https://github.com/blackmagic-debug/blackmagic/issues) or ask on our Discord server. +* You can find the newest pre-built binaries on the {bmd-gh}`GitHub Release Page`. +* You can find the bleeding cutting edge binaries uploaded as assets on the {bmd-gh}`"build and upload" GitHub actions page`, Click on the newest successful build and download the `blackmagic-firmware.zip` file. It contains binaries for all the supported platforms. +* When using the daily builds expect breaking changes. Please report issues on {bmd-issue}`our issue page<>` or ask on our Discord server. Upgrade the firmware of the Black Magic Debug Probe using either: - bmputil @@ -70,7 +70,7 @@ Upgrade the firmware of the Black Magic Debug Probe using either: ### bmputil -Clone and build the [bmputil](https://github.com/blackmagic-debug/bmputil) tool. +Clone and build the {black-magic-org-gh}`bmputil` tool. Plug your Black Magic Probe into your computer and run the following command: @@ -91,7 +91,7 @@ Plug the Black Magic Probe into your computer and run the following command: dfu-util.exe -d 1d50:6018,:6017 -s 0x08002000:leave -D blackmagic.bin ``` -To upgrade non-native hardware see the readme of the different [platforms on GitHub](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms). +To upgrade non-native hardware see the readme of the different {bmd-gh}`platforms on GitHub`. You may need use [Zadig](https://tracker.iplocation.net/icsj/) to install the WinUSB driver. Both PID 0x6017 and 0x6018 need to be known to [Zadig](https://tracker.iplocation.net/icsj/). diff --git a/usage/swo.md b/usage/swo.md index 305505a..1977ef2 100644 --- a/usage/swo.md +++ b/usage/swo.md @@ -54,7 +54,7 @@ sets speed to 4500000 baud, and decodes only channels 0 and 2. The decoded SWO stream is written to the usb uart. Viewing SWO is simply connecting to the usb uart. ### linux -On linux, set up [udev-rules](https://github.com/blackmagic-debug/blackmagic/blob/master/driver/99-blackmagic.rules) and type +On linux, set up {bmd-gh}`udev-rules` and type ``` cat /dev/ttyBmpTarg ``` @@ -62,7 +62,7 @@ If you have not set up udev-rules, connect to the second of the two serial ports If the SWO stream is not shown, check baud rate. ### Windows -Black Magic Probe shows up in the device manager as two COM ports. For Windows 8 and 10, no drivers need to be installed for serial ports. For earlier versions, one can use an [.inf file](https://github.com/blackmagic-debug/blackmagic/tree/master/driver) that references the pre-installed serial driver. On Windows, connect [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) to the second of the two COM ports, labeled "Black Magic UART Port". +Black Magic Probe shows up in the device manager as two COM ports. For Windows 8 and 10, no drivers need to be installed for serial ports. For earlier versions, one can use an {bmd-gh}`.inf file` to the second of the two COM ports, labeled "Black Magic UART Port". SWO decoding in the probe does not need any special utilities and works on every os. For setups that use only a single channel this may be all you need. @@ -80,5 +80,5 @@ Viewers: * [bmtrace](https://github.com/compuphase/Black-Magic-Probe-Book) (graphical, windows, ubuntu). Configures bmp and target for you. Windows binaries. ![](https://github.com/compuphase/Black-Magic-Probe-Book/raw/master/doc/bmtrace.png) * [orbuculum](https://github.com/orbcode/orbuculum) (linux, command line) Advanced. Has gdb init scripts and target c source in the Support/ directory. -* [swo_listen](https://github.com/blackmagic-debug/blackmagic/blob/master/scripts/swolisten.c) (linux, command line) +* {bmd-gh}`swo_listen` * [bmp_traceswo](https://github.com/nickd4/bmp_traceswo) and [fork](https://github.com/tristanseifert/bmp_traceswo) (linux, command line) {ref}`detailed write-up ` From f24bbafd5e91a427edd77b1741d1661e68de1974 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 19:54:19 +0100 Subject: [PATCH 14/16] extlink: add github --- conf.py | 2 ++ getting-started.md | 2 +- hacking/contrib.md | 6 +++--- index.md | 4 ++-- knowledge/faq.md | 2 +- knowledge/links.md | 8 ++++---- upgrade.md | 5 ++--- usage/gdb-automation.md | 2 +- usage/rtt.md | 4 ++-- usage/swo.md | 12 ++++++------ 10 files changed, 24 insertions(+), 23 deletions(-) diff --git a/conf.py b/conf.py index 24bf88c..534b3a5 100644 --- a/conf.py +++ b/conf.py @@ -82,6 +82,8 @@ def build_url(netloc='', path='', params='', query='', fragment='', scheme='http '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 diff --git a/getting-started.md b/getting-started.md index 9c860fd..dae6f83 100644 --- a/getting-started.md +++ b/getting-started.md @@ -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`, 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. diff --git a/hacking/contrib.md b/hacking/contrib.md index 4f96e72..4326c1c 100644 --- a/hacking/contrib.md +++ b/hacking/contrib.md @@ -8,9 +8,9 @@ * 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. diff --git a/index.md b/index.md index 3e1044c..2c0bf48 100644 --- a/index.md +++ b/index.md @@ -129,8 +129,8 @@ The session goes through the following steps: ## Support the Project The best way to support the project is purchasing the official {ref}`Black Magic Probe hardware `. If you would like to support the project beyond that please consider supporting these individuals and organizations: -* [Piotr Esden-Tempski (GitHub Sponsors)](https://github.com/sponsors/esden) -* [Rachel Mant (GitHub Sponsors)](https://github.com/sponsors/dragonmux) +* {github}`Piotr Esden-Tempski (GitHub Sponsors) ` +* {github}`Rachel Mant (GitHub Sponsors) ` * [1BitSquared (Patreon)](https://www.patreon.com/1bitsquared) ## Getting Hardware diff --git a/knowledge/faq.md b/knowledge/faq.md index 1fcee0f..6fbe4c2 100644 --- a/knowledge/faq.md +++ b/knowledge/faq.md @@ -84,7 +84,7 @@ There are also pre made UART cables: ## Where can I find different JTAG/SWD connectors? (Adapters & Cables) -Many vendors provide adapters allowing easy connection between different JTAG/SWD and UART interfaces. For example {1b2}`1BitSquared ` offers a wide range of different adapters and cables. There is also a collection of adapter designs that you can find on the [1BitSquared GitHub Page](https://github.com/1bitsquared/1b2-adapter-collection) that you can use as basis for your custom adapter. If there is an adapter missing for your specific application it is usually quite easy to put one together using [KiCad](http://kicad.org/) and order the needed board from [OSHPark](https://oshpark.com/). +Many vendors provide adapters allowing easy connection between different JTAG/SWD and UART interfaces. For example {1b2}`1BitSquared ` offers a wide range of different adapters and cables. There is also a collection of adapter designs that you can find on the {github}`1BitSquared GitHub Page <1bitsquared/1b2-adapter-collection>` that you can use as basis for your custom adapter. If there is an adapter missing for your specific application it is usually quite easy to put one together using [KiCad](http://kicad.org/) and order the needed board from [OSHPark](https://oshpark.com/). ## Are binary firmware images available for download? diff --git a/knowledge/links.md b/knowledge/links.md index aca2ee8..7c9bc48 100644 --- a/knowledge/links.md +++ b/knowledge/links.md @@ -3,7 +3,7 @@ Projects useful to BMP users: - [atom-gdb-debugger](https://atom.io/packages/atom-gdb-debugger) - GDB integration for GitHub's [Atom editor](https://atom.io/) - [gcc-arm-embedded](https://launchpad.net/gcc-arm-embedded) - GNU ARM Embedded Toolchain -- [libopencm3](http://libopencm3.org/) ([on GitHub](https://github.com/libopencm3/libopencm3)) - Open source Cortex-M microcontroller library ([examples](https://github.com/libopencm3/libopencm3-examples)) +- [libopencm3](http://libopencm3.org/) ({github}`on GitHub `) - Open source Cortex-M microcontroller library ({github}`examples`) - [gdb](https://www.gnu.org/software/gdb/) - The GNU Project Debugger - [dfu-util](http://dfu-util.sourceforge.net/) - Device Firmware Upgrade Utilities - [stm32flash](https://sourceforge.net/projects/stm32flash/) - Flash STM32 over built-in serial bootloader @@ -14,10 +14,10 @@ EDA tools: MCU Debugger Software: - [OpenOCD](http://openocd.org/) - Open On-Chip Debugger -- [pyOCD](https://github.com/mbedmicro/pyOCD) - Open source python library for programming and debugging ARM Cortex-M microcontrollers using CMSIS-DAP +- {github}`pyOCD` - Open source python library for programming and debugging ARM Cortex-M microcontrollers using CMSIS-DAP - [probe-rs](https://probe.rs/) - embedded debugging toolkit written in Rust -- [pystlink](https://github.com/pavelrevak/pystlink) - Python tool for flashing and debugging STM32 devices using ST-LINK/V2 -- [texane/stlink](https://github.com/texane/stlink) - STM32 Discovery Line Linux Programmer +- {github}`pystlink` - Python tool for flashing and debugging STM32 devices using ST-LINK/V2 +- {github}`texane/stlink` - STM32 Discovery Line Linux Programmer MCU Debugger Protocols: - [CMSIS-DAP](https://developer.mbed.org/handbook/CMSIS-DAP) diff --git a/upgrade.md b/upgrade.md index ca49804..26b4244 100644 --- a/upgrade.md +++ b/upgrade.md @@ -105,10 +105,9 @@ If `dfu-util` fails to switch your BMP into bootloader mode, or you feel like yo ### stlink-tool -The firmware on an ST-Link can be upgraded using [dragonmux/stlink-tool](https://github.com/dragonmux/stlink-tool/tree/feature/compilation-fixes). - -The linked repository is forked from [UweBonnes/stlink-tool](https://github.com/UweBonnes/stlink-tool), which in turn is a fork from [jeanthom/stlink-tool](https://github.com/jeanthom/stlink-tool). The link points to a specific branch named `feature/compilation-fixes`. Please ensure to checkout to to this branch after cloning the repository, as both UweBonnes and dragonmux have made fixes that are not included in the repository by jeanthom. +The firmware on an ST-Link can be upgraded using {github}`dragonmux/stlink-tool`. +The linked repository is forked from {github}`UweBonnes/stlink-tool`, which in turn is a fork from {github}`jeanthom/stlink-tool`. The link points to a specific branch named `feature/compilation-fixes`. Please ensure to checkout to to this branch after cloning the repository, as both UweBonnes and dragonmux have made fixes that are not included in the repository by jeanthom. To upgrade, run the following command: diff --git a/usage/gdb-automation.md b/usage/gdb-automation.md index cb54ac8..fab568f 100644 --- a/usage/gdb-automation.md +++ b/usage/gdb-automation.md @@ -98,7 +98,7 @@ endif $(*).elf ``` -For a full example using this kind of a makefile target you can look at the [1Bitsy template project](https://github.com/1Bitsy/1bitsy-locm3-template). +For a full example using this kind of a makefile target you can look at the {github}`1Bitsy template project <1Bitsy/1bitsy-locm3-template>`. ## Windows Batch diff --git a/usage/rtt.md b/usage/rtt.md index a3fbcda..ee44dad 100644 --- a/usage/rtt.md +++ b/usage/rtt.md @@ -319,6 +319,6 @@ has to be also set appropriately, selecting the correct host target. ## Links - [OpenOCD](https://openocd.org/doc/html/General-Commands.html#Real-Time-Transfer-_0028RTT_0029) - - [probe-rs](https://probe.rs/) and [rtt-target](https://github.com/mvirkkunen/rtt-target) for the + - [probe-rs](https://probe.rs/) and {github}`rtt-target ` for the _rust_ programming language. - - [RTT Stream](https://github.com/koendv/Arduino-RTTStream) for Arduino on arm processors + - {github}`RTT Stream ` for Arduino on arm processors diff --git a/usage/swo.md b/usage/swo.md index 1977ef2..7448d9d 100644 --- a/usage/swo.md +++ b/usage/swo.md @@ -22,9 +22,9 @@ A setup with blue pills might look like this: Registers must be set up to configure the SWO pin for output. Different processors have different SWO setup. You can setup SWO in viewer, debugger, or target. -* [bmtrace](https://github.com/compuphase/Black-Magic-Probe-Book) configures target processor in the viewer, button *Configure target*. Supports stm32 and lpc. -* [orbuculum](https://github.com/orbcode/orbuculum) has scripts to configure the target in gdb, and stm32 c source to include in your build. -* [SerialWireOutput](https://github.com/koendv/SerialWireOutput) arduino library, does stm32 set up in code. Userland source for initializing, write() and flush(). +* {github}`bmtrace ` configures target processor in the viewer, button *Configure target*. Supports stm32 and lpc. +* {github}`orbuculum ` has scripts to configure the target in gdb, and stm32 c source to include in your build. +* {github}`SerialWireOutput ` arduino library, does stm32 set up in code. Userland source for initializing, write() and flush(). ## Black Magic Probe BMP receives SWO from the target and sends decoded SWO to a usb serial port, or undecoded SWO to a viewer. Target and probe: @@ -77,8 +77,8 @@ monitor traceswo The SWO stream is written to the usb trace port. (The usb trace port does not show up in /dev). If using async protocol, you can specify a baud rate: ``monitor traceswo 1125000``. The default for async is 2250000. Viewers: -* [bmtrace](https://github.com/compuphase/Black-Magic-Probe-Book) (graphical, windows, ubuntu). Configures bmp and target for you. Windows binaries. +* {github}`bmtrace ` (graphical, windows, ubuntu). Configures bmp and target for you. Windows binaries. ![](https://github.com/compuphase/Black-Magic-Probe-Book/raw/master/doc/bmtrace.png) -* [orbuculum](https://github.com/orbcode/orbuculum) (linux, command line) Advanced. Has gdb init scripts and target c source in the Support/ directory. +* {github}`orbuculum ` (linux, command line) Advanced. Has gdb init scripts and target c source in the Support/ directory. * {bmd-gh}`swo_listen` -* [bmp_traceswo](https://github.com/nickd4/bmp_traceswo) and [fork](https://github.com/tristanseifert/bmp_traceswo) (linux, command line) {ref}`detailed write-up ` +* {github}`bmp_traceswo ` and {github}`fork ` (linux, command line) {ref}`detailed write-up ` From b33f9ca986f27ed0c03b7802cc8802efd948b195 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 19:59:13 +0100 Subject: [PATCH 15/16] faq: link to filtered pull requests by New Target label --- knowledge/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/knowledge/faq.md b/knowledge/faq.md index 6fbe4c2..0ca3c56 100644 --- a/knowledge/faq.md +++ b/knowledge/faq.md @@ -147,7 +147,7 @@ There are a few advantages of the Black Magic Probe. BMP is open-source, meaning ## Why is XXX not supported? -Because nobody implemented the required functions yet. Look on {bmd-gh}`GitHub ` if there is a pending pull request for your target. Consider testing PRs that try to implement the desired target to help us triage merge of new hardware support. +Because nobody implemented the required functions yet. Look on {bmd-gh}`GitHub ` if there is a pending pull request for your target. Consider testing PRs that try to implement the desired target to help us triage merge of new hardware support. ## Why is Raspberry Pi 1 not supported? From 655f393e692d565b4011185709f0acd1fc4b3a6a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Gra=C3=A7a=20Silva?= Date: Tue, 1 Aug 2023 19:59:28 +0100 Subject: [PATCH 16/16] pinouts: use note blocks --- knowledge/pinouts.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/knowledge/pinouts.md b/knowledge/pinouts.md index 6e59db9..4bfd989 100644 --- a/knowledge/pinouts.md +++ b/knowledge/pinouts.md @@ -12,7 +12,9 @@ This connector is backwards compatible with the ubiquitous {ref}`knowledge/pinou - Solder together the middle RX pad and the RX pad farthest from the board edge. - Solder together the TX jumpers. (They default to unconnected.) -(TODO: Add Black Magic Probe V2.3 documentation) +```{todo} +Add Black Magic Probe V2.3 documentation +``` A drawback of configuring the BMDU jumpers this way is that connecting to a standard SWD connector might render the UART pins on the PicoBlade connector unusable while the SWD connector is attached. This is because a standard SWD connector will probably short the UART RX pin to GND, and might short the UART TX pin to GND. You can revert the solder jumpers to their default configuration if this is a problem. @@ -56,4 +58,6 @@ Targets using this connector can be directly interfaced with {ref}`hardware:nati SEGGER J-Link probes using this connector can interface directly with targets using the {ref}`knowledge/pinouts:black magic debug unified connector (bmdu)` using the same 20Pin JTAG adapter board. -Note that in both cases the adapter board does not allow for UART or J-Link Kickstart power (pin 19) to be used. +```{note} +In both cases the adapter board does not allow for UART or J-Link Kickstart power (pin 19) to be used. +```