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)
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.