Updated README, added HACKING.

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

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.

src/stm32/Makefile.inc

@@ -1,5 +1,6 @@
-CC = arm-cortexm3-eabi-gcc
+CROSS_COMPILE ?= arm-cortexm3-eabi-
-OBJCOPY = arm-cortexm3-eabi-objcopy
+CC = $(CROSS_COMPILE)gcc
+OBJCOPY = $(CROSS_COMPILE)objcopy
 
 CFLAGS += -Istm32/include
 LDFLAGS_BOOT = -lopencm3_stm32 -Wl,--defsym,_stack=0x20005000 \