diff --git a/HACKING b/HACKING index ee1fc24..f53c89e 100644 --- a/HACKING +++ b/HACKING @@ -1,73 +1 @@ -======================================== -The Black Magic Debug Project -- HACKING -======================================== - -The Black Magic Probe consists of both hardware and firmware components. -The hardware design resides in the 'hardware' directory and the firmware -resides in the 'src' directory. - - -Compiling for the native hardware ---------------------------------- -Run -git submodule init -git submodule update -after cloning blackmagic to fill the libopencm3 directory. - -To build the firmware for the standard hardware platform run 'make' in the -src directory. You will require a GCC cross compiler for ARM Cortex-M3 -targets. You will also need to have the libopenstm32 library installed. -The default makefile assumes the target is arm-cortexm3-eabi, but -you can override this on the command line: - -make CROSS_COMPILE=arm-none-eabi- - -This will result in binary files: -blackmagic - ELF binary of the Black Magic debug probe. -blackmagic.bin - Flat binary of the Black Magic debug probe, load at 0x8002000. -blackmagic_dfu - ELF binary of the Black Magic DFU bootloader. -blackmagic_dfu.bin - Flat binary of the DFU bootloader, load at 0x8000000. - -If you already have a JTAG/SWD debug probe that can be used to load these -binaries to your target hardware. If not the SystemMemory bootloader can -be used to load the DFU bootloader: -../scripts/bootprog.py blackmagic_dfu.bin - -This requires an appropriate cable to connect the PC serial port to the probe. -See the schematic for more information. - -Once the DFU bootloader is loaded, the Black Magic application can be loaded -over USB: -(First connect the probe and observe the flashing red led) -../scripts/stm32_mem.py blackmagic.bin - -The device should reset and re-enumerate as a CDC-ACM device implementing -the GDB protocol. - -Errors when compiling libopencm3 -------------------------------- -If while compiling libopencm3 you get an error like -arm-none-eabi/bin/ld: error: cdcacm.elf uses VFP register arguments, \ - arm-none-eabi/lib/thumb/v7m/libc.a(lib_a-memcpy-stub.o) does not -your toolchain and libopencm3 disagree on the calling convention for floation -point functions on the F4. Change in -lib/stm32/f4/Makefile and examples/stm32/f4/Makefile.include all apperance of --mfloat-abi=hard to -mfloat-abi=soft -This doesn't matter for blackmagic, as it doesn't use floating point. - -Compiling as a Linux application using FT2232 hardware ------------------------------------------------------- -The Black Magic application can also be compiled as a native PC application -which will use an FT2232 device to implement the physical JTAG interface. -This is not the intended mode of operation, but is useful for debugging, -experimentation, and if you don't have the actual hardware. - -First, get the VID/PID for your FT2232 device using 'lsusb'. Edit the file -'src/libftdi/platform.h' and change the VID/PID to match your hardware. -Compile the application with the command: - -make PROBE_HOST=libftdi - -Running the application 'blackmagic' will start a GDB server on TCP port 2000. - - +See https://github.com/blacksphere/blackmagic/wiki/Hacking diff --git a/README b/README index 9c10013..7703671 100644 --- a/README +++ b/README @@ -1,74 +1 @@ -======================================= -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. - +See https://github.com/blacksphere/blackmagic/wiki