platforms: update instructions to reference meson and its respective …

…produced binaries instead of make

Co-Authored-By: dragonmux <[email protected]>

README.md

@@ -56,7 +56,7 @@ Breakpoint 1, main () at /devel/en_apps/gpio/f4_discovery/../gpio.c:70
 
 ### Black Magic Debug App
 
-You can also build the Black Magic Debug suite as a PC program called Black Magic Debug App (BMDA)
+You can also build the Black Magic Debug suite as a PC program called Black Magic Debug App (BMDA).
 
 This builds the same GDB server that is running on the Black Magic Probe.
 While connection to the Black Magic Probe GDB server is via serial line,
@@ -104,53 +104,60 @@ connected target. Use `-h`/`--help` to get a list of supported options.
 
 #### OS specific remarks
 
-On *BSD and macOS, using `/dev/tty.usbmodemXXX` should work but unresolved discussions indicate a hanging `open()` call on the second invocation. If that happens, try with `/dev/cu.usbmodemXXX`.
+On *BSD and macOS, you should use `/dev/cu.usbmodemXXX`. There are unresolved issues with trying to
+use the `/dev/tty.usbmodemXXX` device node involving how it operates under the hood.
 
 ## Getting started
 
 ### Requirements
 
 When developing this project, the following tools are required:
 
- * [git](https://git-scm.com)
- * [meson](https://mesonbuild.com/Getting-meson.html) (version 0.61 or greater)
- * [ninja](https://ninja-build.org)
+* [git](https://git-scm.com)
+* [meson](https://mesonbuild.com/Getting-meson.html) (version 0.61 or greater)
+* [ninja](https://ninja-build.org)
 
 Additionally, depending on if you want to build/work on the firmware or Black Magic Debug App (BMDA), you also need:
 
 #### Black Magic Debug Firmware
 
- * [`arm-none-eabi-gcc`](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/downloads) (from ARM, self-built and distro-supplied is currently broken)
+* [`arm-none-eabi-gcc`](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/downloads) (from ARM, self-built and distro-supplied is currently broken)
 
-If you wish to use the older [gnu-rm](https://developer.arm.com/downloads/-/gnu-rm) ARM toolchain, this is fine and works well.
+If you wish to use the older [gnu-rm](https://developer.arm.com/downloads/-/gnu-rm) ARM toolchain,
+this is fine and works well.
 
-If you have a toolchain from other sources and find problems, check if it's an issue with your toolchain first, and if not then open an issue, or better, submit a pull request with a fix.
+If you have a toolchain from other sources and find problems, check if it's an issue with your toolchain first,
+and if not then open an issue, or better, submit a pull request with a fix.
 
 #### Black Magic Debug App
 
- * [GCC](https://gcc.gnu.org) or Clang (Clang is not strictly officially supported)
+* [GCC](https://gcc.gnu.org) or Clang (Clang is not officially supported)
 
 If you wish to enable support for 3rd party probes, and not only the official native hardware, you will also need:
 
- * libusb1
- * libftdi1
- * libhidapi
+* libusb1
+* libftdi1
+* libhidapi
 
 ### Building
 
-The project is configured and built using the Meson build system, you will need to create a build directory and then configure the build depending on what you want.
+The project is configured and built using the Meson build system, you will need to create a build directory
+and then configure the build depending on what you want.
 
-The project has a couple of build options you may configure, which affect the resulting binaries, this is how you will configure the firmware for you respective probe, or enable certain features.
+The project has a couple of build options you may configure, which affect the resulting binaries.
+This is how you will configure the firmware for your respective probe, or enable certain features.
 
 A non-exhaustive list of project options:
- * probe: Hardware platform where the BMD firmware will run
- * targets: Enabled debug targets
- * debug_output: Enable debug output (for debugging the BMD stack, not debug targets)
- * rtt_support: Enable RTT (Real Time Transfer) support
+
+* `probe`: Hardware platform where the BMD firmware will run
+* `targets`: Enabled debug targets
+* `debug_output`: Enable debug output (for debugging the BMD stack, not debug targets)
+* `rtt_support`: Enable RTT (Real Time Transfer) support
 
 You may see all available project options and valid values under  `Project options` in the output of the `meson configure` command.
 
 The following commands are ran from the root of your clone of the `blackmagic` repository:
+
 ```sh
 cd /path/to/repository/blackmagic
 ```
@@ -162,34 +169,39 @@ To build the firmware you need to configure the probe hardware the firmware will
 For convenience, a cross-file for each supported hardware probe is available which provides a sane default configuration for it.
 
 The build configuration command for the native probe may look like:
+
 ```sh
 meson setup build --cross-file cross-file/native.ini
 ```
 
 Note that even if you are using the pre-configured cross-file, you may still override it's defaults with `-Doption=value` in the same configuration command, or later as highlighted in [Changing the build configuration](#changing-the-build-configuration).
 
 Alternatively (for advanced users), if you wish to configure manually, for instance while writing support for a new probe, or a different toolchain, you can run:
+
 ```sh
 meson setup build --cross-file cross-file/arm-none-eabi.ini -Dprobe=native -Dtargets=cortexm,stm
 ```
 
 You now should have a `build` directory from where you can build the firmware, this is also where your binary files will appear.
 
 The command `meson compile` will build the default targets, you may omit `-C build` if you run the command from within the `build` directory:
+
 ```sh
 meson compile -C build
 ```
 
 You should now see the resulting binaries in `build`, in this case:
- - `blackmagic_native_firmware.bin`
- - `blackmagic_native_firmware.elf`
+
+* `blackmagic_native_firmware.bin`
+* `blackmagic_native_firmware.elf`
 
 These are the binary files you will use to flash to your probe.
 
 ##### region `rom' overflowed
 
 It may happen, while working with non default configurations or the project's latest version from Git, that the firmware does not fit in the available space for the configured probe, this could look something like:
-```
+
+```console
 arm-none-eabi/bin/ld: region `rom' overflowed by 4088 bytes
 Memory region         Used Size  Region Size  %age Used
              rom:      135160 B       128 KB    103.12%
@@ -198,6 +210,7 @@ collect2: error: ld returned 1 exit status
 ```
 
 This is not unexpected, as some hardware probe have limited space for firmware. You can get around it by disabling some features or targets support:
+
 ```sh
 meson configure build -Dtargets=cortexm,stm -Drtt_support=false
 ```
@@ -207,39 +220,47 @@ meson configure build -Dtargets=cortexm,stm -Drtt_support=false
 The Black Magic Debug App (BMDA) is always built by default, even for firmware builds. So long as all its dependencies are found, you can find the executable under the `build` directory, named simply `blackmagic`.
 
 If you wish to build only BMDA, you can set the hardware `probe` option to an empty string `-Dprobe=''`, this is the default value:
+
 ```sh
 meson setup build
 ```
 
 You now should have a `build` directory from where you can build the app, this is also where your executable will appear.
 
 The command `meson compile` will build the default targets, you may omit `-C build` if you run the command from within the `build` directory:
+
 ```sh
 meson compile -C build
 ```
 
 You should now see the resulting executable in `build`:
- - `blackmagic`
+
+* `blackmagic`
 
 ### Changing the build configuration
 
 You may change the configuration at any time after configuring the project, if may also change the default options while configuring for the first time.
 
 Changing options at configure time:
+
 ```sh
 meson setup build -Ddebug_output=true
 ```
 
 Changing options after configuration:
+
 ```sh
 meson configure build -Dtargets=cortexm,stm
 ```
+
 Alternatively, you can use the equivalent but more verbose `meson setup` command:
+
 ```sh
 meson setup build --reconfigure -Dtargets=cortexm,stm
 ```
 
 Keep in mind that when changing the configured probe, the other default options will not change, and you may end up with a configuration that does not make sense for it. In such cases it's best to use the *cross-file* for the probe, not just change the `probe` option. For this you will need to use the `meson setup` command again:
+
 ```sh
 meson setup build --reconfigure --cross-file=cross-file/bluepill.ini
 ```
@@ -250,21 +271,26 @@ You can have multiple build directories! So if you are regularly building firmwa
 
 ### Working with an existing clone (used before the new meson build system was introduced)
 
-If you are working with an existing clone of the project where you used the old `make` build system, or simply initialized the submodules, you may encounter issues while trying the new `meson` workflow, this may look something like:
-```
+If you are working with an existing clone of the project where you used the old `make` build system,
+or simply initialized the submodules, you may encounter issues while trying the new Meson workflow,
+this may look something like:
+
+```console
 fatal: Fetched in submodule path 'deps/libopencm3', but it did not contain bed4a785eecb6c9e77e7491e196565feb96c617b. Direct fetching of that commit failed.
 ```
 
 To get around this try running the following commands:
+
 ```sh
 cd deps/libopencm3
 git remote set-url origin https://github.com/blackmagic-debug/libopencm3
 cd ../..
 git submodule update
 ```
 
-Alternatively, the nuclear option:
-*BEWARE, THIS WILL ERASE ANY CHANGES THAT HAVE NOT BEEN PUSHED UPSTREAM*
+Alternatively, the nuclear option
+(**BEWARE, THIS WILL ERASE ANY CHANGES THAT HAVE NOT BEEN PUSHED UPSTREAM**)
+
 ```sh
 git submodule deinit --force --all
 meson subprojects purge --confirm

src/platforms/96b_carbon/README.md

@@ -34,9 +34,8 @@ The order matches that of the SWD pins for easy hook up.
 
 ## How to Build
 
-    cd blackmagic
-    make clean
-    make PROBE_HOST=96b_carbon
+    meson setup build --cross-file=cross-file/96b_carbon.ini
+    meson compile -C build
 
 ## Flashing using dfu-util
 

src/platforms/common/blackpill-f4/README.md

@@ -33,19 +33,19 @@ In the following commands replace `blackpill-f4x1cx` with the platform you are u
 To build the code using the default pinout, run:
 
 ```sh
-cd blackmagic
-make clean
-make PROBE_HOST=blackpill-f4x1cx
+meson setup build --cross-file=cross-file/blackpill-f4x1cx.ini
+meson compile -C build
 ```
 
 or, to use alternative pinout 1, run:
 
 ```sh
-cd blackmagic
-make clean
-make PROBE_HOST=blackpill-f4x1cx ALTERNATIVE_PINOUT=1
+meson setup build --cross-file=cross-file/blackpill-f4x1cx.ini -Dalternative_pinout=1
+meson compile -C build
 ```
 
+TODO: No easy way ATM of configuring this on the meson buildsystem.
+
 or, if you are using a PCB (printed circuit board) as a shield for your Black Pill F4, run:
 
 ```sh

src/platforms/f072/README.md

@@ -24,26 +24,29 @@ system bootloader is used. This gives additional 4 kB for the BMP firmware.
 
 Get into ST bootloader mode with reset or repower and BOOT pulled high. If BMP firmware is already loaded and running, dfu-util can also invoke the bootloader.
 
-```
+```sh
 dfu-util -d 1d50:6018 -e
 ```
 
 List the available devices
 
-```
+```sh
 dfu-util -l
 ```
 
-dfu-util should now list "[0483:df11]" and "@Internal Flash  /0x08000000/064*0002Kg".Compilethe firmware with:
+dfu-util should now list "[0483:df11]" and "@Internal Flash  /0x08000000/064*0002Kg".
 
+Compile the firmware with:
+
+```sh
+meson setup build --cross-file=cross-file/f072.ini
+meson compile -C build
 ```
- make PROBE_HOST=f072 clean && make PROBE_HOST=f072
- ```
 
 Load firmware:
 
- ```
- dfu-util -d 0483:df11 -a 0 -s 0x08000000:leave -D blackmagic.bin
- ```
+```sh
+dfu-util -d 0483:df11 -a 0 -s 0x08000000:leave -D blackmagic_f072_firmware.bin
+```
 
 Multiple BMP devices or STM devices on the USB bus may require additional dfu-util arguments for device selection.

src/platforms/f3/README.md

@@ -23,28 +23,28 @@ For simpicity, the ST system bootloader is used. This saves additional 4 kB for
 
 Get into ST bootloader mode with reset or repower and BOOT pulled high. If BMP firmware is already loaded and running, dfu-util can also invoke the bootloader.
 
-```
+```sh
 dfu-util -d 1d50:6018 -e
 ```
 
 List the available devices
 
-```
+```sh
 dfu-util -l
 ```
 
-dfu-util should now list "[0483:df11]" "@Internal Flash  /0x08000000/064*0002Kg"
-. Compile the firmware with
+dfu-util should now list "[0483:df11]" "@Internal Flash  /0x08000000/064*0002Kg".
 
+Compile the firmware with:
+```sh
+meson setup build --cross-file=cross-file/f3.ini
+meson compile -C build
 ```
- make PROBE_HOST=f3 clean && make PROBE_HOST=f3
- ```
 
 Load firmware
 
-```
- dfu-util -d 0483:df11 -a 0 -s 0x08000000:leave -D blackmagic.bin
-
+```sh
+dfu-util -d 0483:df11 -a 0 -s 0x08000000:leave -D blackmagic_f3_firmware.bin
 ```
 
 Multiple BMP devices or STM devices on the USB bus may require additional dfu-util arguments for device selection.

src/platforms/hosted/README.md

@@ -1,7 +1,9 @@
 # PC-Hosted BMP
-Compile in src with "make PROBE_HOST=hosted". This needs minimal external
-support.  "make PROBE_HOST=hosted HOSTED_BMP_ONLY=0" will compile support for FTDI,
-STLink, CMSIS-DAP and J-Link probes, but requires external libraries.
+Compile with:
+```sh
+meson setup build
+meson compile -C build
+```
 
 ## Description
 PC-hosted BMP run on the PC and compiles as "blackmagic". When started,
@@ -72,12 +74,14 @@ in windows. Make sure to use the `mingw64` shell from msys2, otherwise,
 you may get compilation errors. You will need to install the libusb
 and libftdi libraries, and have the correct mingw compiler.
 You can use these commands to install dependencies, and build PC-hosted BMP
-from a mingw64 shell, from within the `src` directory:
+from a mingw64 shell, from within the `blackmagic` directory:
 ```
 pacman -S mingw-w64-x86_64-libusb --needed
 pacman -S mingw-w64-x86_64-libftdi --needed
 pacman -S mingw-w64-x86_64-gcc --needed
-PROBE_HOST=hosted make
+meson setup build
+cd build
+meson compile
 ```
 
 For support of other probes beside BMP, libusb access is needed. To prepare

src/platforms/hydrabus/README.md

@@ -24,15 +24,17 @@ How to Build
 ------------
 
 ```sh
-cd blackmagic
-make clean
-make PROBE_HOST=hydrabus
+meson setup build --cross-file=cross-file/hydrabus.ini
+meson compile -C build
 ```
 
 How to Flash the firmware with Windows
 --------------------------------------
 
-* After build:
-  * 1) Download files from https://github.com/hydrabus/hydrafw/tree/master/utils/windows_dfu_util
-  * 2) Force the F4 into system bootloader mode by jumpering "BOOT0" to "3V3" and "PB2/BOOT1" to "GND" and reset (RESET button). System bootloader should appear.
-  * 3) Run the command `DfuSeCommand.exe -c --de 0 -d --fn .\src\blackmagic.dfu`
+*THIS SECTION IS OUT OF DATE AND THE WORKFLOW IS KNOWN TO BE BROKEN*
+
+After build:
+  1. Download files from https://github.com/hydrabus/hydrafw/tree/master/utils/windows_dfu_util
+  2. Run the command: `python3 ../scripts/dfu-convert.py -i blackmagic_hydrabus_firmware.bin blackmagic_hydrabus_firmware.dfu`
+  3. Force the F4 into system bootloader mode by jumpering "BOOT0" to "3V3" and "PB2/BOOT1" to "GND" and reset (RESET button). System bootloader should appear.
+  4. Run the command: `DfuSeCommand.exe -c --de 0 -d --fn blackmagic_hydrabus_firmware.dfu`