Getting Started

Getting started with Bloom

Download and installation

Downloads and installation instructions can be found on the Download page.

Any debug tools that were connected during the installation of Bloom may need to be disconnected and reconnected, due to the udev rule changes made during the installation.

Project configuration

Create a project configuration file (bloom.yaml) in the project directory, via the init command:

$ cd /path/to/project;
$ bloom init;

Adjust the configuration for your debugging environment (debug tool, target, etc). See the configuration page for more on configuring your project via bloom.yaml.

Installing GDB for AVR debugging

This step can be skipped if avr-gdb version 10.1 or later is already installed.

Bloom exposes a GDB server, to which GDB will connect. GDB must be configured to support the debugging of AVR programs. avr-gdb is a prebuilt GDB binary, specifically configured to support AVR debugging.

Most Linux package repositories host an avr-gdb package. The package name varies across repositories.

Before relying on a package manager to install a prebuilt avr-gdb binary, users must first ensure that their operating system's package repository hosts a fairly recent version of the package.

In order for Bloom to operate correctly, the recommended avr-gdb version is 10.1 or later. Using an earlier version of avr-gdb may result in compatibility issues. Any version predating 8.1 will likely fail to connect to Bloom's GDB server.

Debian/Ubuntu

For users of Debian 11/Ubuntu 21.10 or later, avr-gdb can be installed via the package manager's repository:

$ sudo apt-get install gdb-avr;

For users of Debian 10/Ubuntu 20.04 or earlier, the system's package repository will likely host an outdated version of avr-gdb (<10.1). In this case, avr-gdb should be installed via the Debian package hosted on the Debian 11 repository. This package can be manually downloaded via https://packages.debian.org/bullseye/amd64/gdb-avr/download, and installed via the following command:

$ sudo apt install path/to/downloaded/package.deb

If the above command fails due to unresolvable dependencies, building avr-gdb from source may be required.

Arch Linux

For Arch Linux users, avr-gdb can be installed via the following command:

$ sudo pacman -S avr-gdb;

RPM-based systems

For users of RPM-based systems, there doesn't appear to be any recent avr-gdb RPM package available to download. Building avr-gdb from source may be required.

Start Bloom

Upon creating your project configuration file (bloom.yaml), Bloom can now be started via the bloom command.

At startup, Bloom will look for the project configuration file (bloom.yaml) in the working directory. Be sure to start Bloom from the correct directory.

$ bloom [ENVIRONMENT_NAME]

Replace "[ENVIRONMENT_NAME]" with the name of the environment (defined in bloom.yaml) that you wish to select. Or leave blank to have Bloom fall back to the "default" environment.

Bloom will indicate when it's ready to accept incoming GDB connections:

$ bloom
2022-07-24 18:45:10 BST [MT] [3]: [INFO] Selected environment: "default"
2022-07-24 18:45:10 BST [TC] [4]: [INFO] Starting TargetController
2022-07-24 18:45:10 BST [TC] [5]: [INFO] Connecting to debug tool
2022-07-24 18:45:10 BST [TC] [6]: [INFO] Debug tool connected
2022-07-24 18:45:10 BST [TC] [7]: [INFO] Debug tool name: MPLAB Snap
2022-07-24 18:45:10 BST [TC] [8]: [INFO] Debug tool serial:
2022-07-24 18:45:10 BST [TC] [9]: [INFO] Activating target
2022-07-24 18:45:11 BST [TC] [10]: [INFO] Target activated
2022-07-24 18:45:11 BST [TC] [11]: [INFO] AVR8 target promoted to megaAVR target
2022-07-24 18:45:12 BST [TC] [12]: [INFO] Target ID: 0x1e950f
2022-07-24 18:45:12 BST [TC] [13]: [INFO] Target name: ATmega328P
2022-07-24 18:45:12 BST [DS] [14]: [INFO] Starting DebugServer
2022-07-24 18:45:12 BST [DS] [15]: [INFO] Selected DebugServer: AVR GDB Remote Serial Protocol Debug Server
2022-07-24 18:45:12 BST [DS] [16]: [INFO] GDB RSP address: 127.0.0.1
2022-07-24 18:45:12 BST [DS] [17]: [INFO] GDB RSP port: 1442
2022-07-24 18:45:12 BST [DS] [18]: [INFO] DebugServer ready
2022-07-24 18:45:12 BST [DS] [19]: [INFO] Waiting for GDB RSP connection
2022-07-24 18:45:12 BST [MT] [20]: [INFO] Starting Insight
2022-07-24 18:45:12 BST [MT] [21]: [INFO] Insight ready

From this point, a connection can be established via GDB. This can be handled by an IDE such as CLion, or, directly via avr-gdb's CLI. For more information on debugging with CLion and Bloom, see Debugging embedded systems with CLion and Bloom.

Establish a connection with Bloom's GDB server via the avr-gdb CLI

This step is only necessary for those who wish to use avr-gdb's CLI (as opposed to an IDE) to debug their AVR program.

IDEs such as CLion will automatically perform this step upon the start of a debug session.

A connection with Bloom's GDB server can be established via avr-gdb's command line interface (CLI), using the target remote command.

Bloom's GDB server does not support the 'extended remote' protocol - please do not use the target extended remote command to connect to Bloom.

Start GDB

Run avr-gdb and pass the path to the ELF executable of the AVR program that is to be debugged.

$ avr-gdb /path/to/avr/program.elf
GNU gdb (GDB) 11.0.50.20210520-git
Copyright (C) 2021 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=x86_64-pc-linux-gnu --target=avr".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word"...
(gdb)

Establish a connection with Bloom

From the GDB console, use the target remote command to establish a connection with Bloom's GDB server.

(gdb) target remote localhost:1442
Remote debugging using localhost:1442
0x00007000 in ?? ()
(gdb)

In the example above, localhost:1442 is the address and port on which Bloom's GDB server is configured to listen (see Bloom's debug server configuration for more).

Once a connection has been established, Bloom will automatically reset the target to its reset vector. In the example above, the target's reset vector is 0x00007000 (the start address of the target's boot section in program memory).

In the example above, GDB fails to map the program memory address (0x00007000) to an instruction in the selected AVR program. This is because the instruction stored at that address is part of the bootloader program, which is separate to the program that was selected when starting avr-gdb (it is common practice to keep the bootloader program separate from the main program).

GDB now possesses control of the target. Program flow control, memory access and other debugging operations can now take place.

(gdb) continue
Continuing.
^C
Program received signal SIGINT, Interrupt.
0x000005f2 in eeprom_write_byte ()
(gdb) backtrace
#0  0x000005f2 in eeprom_write_byte ()
#1  0x000000bc in main () at /path/to/project/src/main.cpp:23
(gdb)

In the example above, the continue command was used to begin target execution. Shortly after, Ctrl+C was pressed, to interrupt target execution. Then, the backtrace command was used to view the current call trace.

Programming the AVR target

Support for programming was introduced in version 0.10.0.

GDB's load command can be used to upload any program changes to the target.

(gdb) target remote localhost:1442
Remote debugging using localhost:1442
0x00007000 in ?? ()

... Perform debugging operations here ...
... Make changes to source code and then rebuild ELF ...

(gdb) load
Loading section .text, size 0x60e lma 0x0
Start address 0x00000000, load size 1550
Transfer rate: 186 bytes/sec, 1550 bytes/write.
(gdb)

Bloom does not currently support EEPROM access via GDB. Programming an ELF with an EEPROM section will likely fail with GDB reporting an error closely resembling the following:

(gdb) load
Loading section .eeprom, size 0xc lma 0x810000
Load failed
(gdb)

Support for EEPROM access via GDB will be introduced in a future release. See the corresponding ticket for more.

Upon the invocation of the load command, GDB will reload the ELF executable and instruct Bloom to update the target's program memory.

Upon the completion of programming, Bloom will automatically reset the target to its reset vector.

Upon the completion of programming and Bloom's automatic resetting of the target, GDB may attempt to reset the target for a second time, by updating the target's program counter to point to the start address of the program being debugged. This may result in unexpected behaviour, as the start address of the program being debugged may differ from the reset vector.

Running monitor reset immediately after load will ensure that the target has been properly reset to its reset vector.

From this point, debugging can be resumed with the newly applied changes.

Questions or feedback?

Questions can be raised on Bloom's GitHub discussions page (GitHub account required). Please feel free to submit any questions or feedback via a new discussion.