aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--HACKING58
-rw-r--r--README25
-rw-r--r--src/stm32/Makefile.inc5
3 files changed, 86 insertions, 2 deletions
diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..c1e2f5b
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,58 @@
+========================================
+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
+---------------------------------
+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.
+
+
+Compiling as a Linux application using FT2232 hardware
+------------------------------------------------------
+The Black Magic application can also be compiled as a native Linux 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/linux/platform.h' and change the VID/PID to match your hardware.
+Compile the application with the command:
+
+make HOST=linux
+
+Running the application 'blackmagic' will start a GDB server on TCP port 2000.
+
+
diff --git a/README b/README
index b91903f..76ada7b 100644
--- a/README
+++ b/README
@@ -13,6 +13,31 @@ Currently supported microcontrollers:
- ST STM32 Family
- TI/LMI Stellaris Family
+
+Getting started
+===============
+The Black Magic Probe is available as a built-up product form Black
+Sphere Technologies. Contact <sales@blacksphere.co.nz> 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.
+
+
Project layout
==============
flashstub/ - Source code for flash programming stubs in target drivers.
diff --git a/src/stm32/Makefile.inc b/src/stm32/Makefile.inc
index d9bc876..20a1329 100644
--- a/src/stm32/Makefile.inc
+++ b/src/stm32/Makefile.inc
@@ -1,5 +1,6 @@
-CC = arm-cortexm3-eabi-gcc
-OBJCOPY = arm-cortexm3-eabi-objcopy
+CROSS_COMPILE ?= arm-cortexm3-eabi-
+CC = $(CROSS_COMPILE)gcc
+OBJCOPY = $(CROSS_COMPILE)objcopy
CFLAGS += -Istm32/include
LDFLAGS_BOOT = -lopencm3_stm32 -Wl,--defsym,_stack=0x20005000 \