======================================= The Black Magic Debug Project -- README ======================================= The Black Magic Debug Probe is gadget providing an in-application debug capability for ARM Cortex-M microcontrollers. It interfaces with the GDB, the GNU source level debugger over the USB bus, and communicates with the target microcontroller over either a JTAG or Serial Wire debug port. Currently supported microcontrollers: - ST STM32 Family - TI/LMI Stellaris Family - NXP LPC11xx Family - Atmel SAM3X Getting started =============== The Black Magic Probe is available as a built-up product form Black Sphere Technologies. Contact should you wish to order one. If you would like to work on the project see the file HACKING for developer's info. 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. The GDB remote debugging protocol is implemented over this virtual character stream. To connect your ARM GDB to the target device use the following commands: (gdb) target extended-remote /dev/ttyACM0 (gdb) mon jtag_scan (gdb) attach 1 The command 'mon 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. The peripheral registers are not included in the memory map provided to GDB. I suggest you add the command "set mem inaccessible-by-default off' to your '.gdbinit'. That will allow you to access addresses outside of the memory map. It will treat anything outside of the memory map as RAM. Semihosting support =================== Standard ARMv6-M/ARMv7-M semihosting is supported, i.e. you can build your application in a special way to have calls to certain functions (open(), close(), read(), write(), lseek(), rename(), unlink(), stat(), isatty(), system()) executed on the debugging host itself. To make use of these facilities, add --specs=rdimon.specs and -lrdimon to the linker flags for your firmware. If you're going to use stdin, stdout or stderr (e.g. via printf()/scanf()) and you're not using newlib's crt0 (by specifying -nostartfiles), you need to add this to your initialisation: void initialise_monitor_handles(void); initialise_monitor_handles(); Project layout ============== driver/ - Windows drivers for the Black Magic probe hardware. flashstub/ - Source code for flash programming stubs in target drivers. hardware/ - Schematic (gschem) and PCB layout for the Black Magic Probe hardware/contrib/ - User contributed hardware variants. libopencm3/ - Submodule for the libopencm3 library needed for stm32 platforms. scripts/ - Python scripts useful for programming devices. src/ - Firmware source code for the Black Magic debug probe. upgrade/ - Alternate firmware upgrade tool written in C.