Skip to content

Commit

Permalink
platforms: update instructions to reference meson and its respective …
Browse files Browse the repository at this point in the history
…produced binaries instead of make

Co-Authored-By: dragonmux <[email protected]>
  • Loading branch information
perigoso and dragonmux committed Jan 11, 2024
1 parent 18b1726 commit faa46d7
Show file tree
Hide file tree
Showing 9 changed files with 104 additions and 71 deletions.
75 changes: 50 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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, 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`.

## 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 strictly 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
```
Expand All @@ -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%
Expand All @@ -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
```
Expand All @@ -207,13 +220,15 @@ 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
```
Expand All @@ -226,20 +241,25 @@ You should now see the resulting executable in `build`:
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
```
Expand All @@ -250,21 +270,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
Expand Down
5 changes: 2 additions & 3 deletions src/platforms/96b_carbon/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
12 changes: 6 additions & 6 deletions src/platforms/common/blackpill-f4/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 11 additions & 8 deletions src/platforms/f072/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
18 changes: 9 additions & 9 deletions src/platforms/f3/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
14 changes: 9 additions & 5 deletions src/platforms/hosted/README.md
Original file line number Diff line number Diff line change
@@ -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,
Expand Down Expand Up @@ -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
Expand Down
16 changes: 9 additions & 7 deletions src/platforms/hydrabus/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
6 changes: 3 additions & 3 deletions src/platforms/stlink/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,10 +45,10 @@ NB: SWDIO/TMS is on P**B**14, not P**A**14.
## Upload BMP Firmware

* Keep the original ST Bootloader.
* Compile firmware with `make PROBE_HOST=stlink ST_BOOTLOADER=1`
* Upload firmware with stlink-tool from [stlink-tool](https://github.com/UweBonnes/stlink-tool/tree/stlinkv21)(*3).
* Compile firmware with the option `-Dbmd_bootloader=false`
* Upload firmware with stlink-tool from [stlink-tool](https://github.com/blackmagic-debug/stlink-tool)(*3).
* For ST-Link v2, as on older disco boards, un- and replug USB to enter the bootloader.
* Upload BMP firmware with `stlink-tool blackmagic.bin`
* Upload BMP firmware with `stlink-tool blackmagic_stlink_firmware.bin`
* For ST-Link v2, after each stlink replug, call either `blackmacic -t` or `stlink-tool` without arguments or on Linux use some udev rule like the one shown below to enter the BMP firmware

```sh
Expand Down
Loading

0 comments on commit faa46d7

Please sign in to comment.