added example instructions

README.md

@@ -8,17 +8,29 @@ Boot the RP2040 with the BOOTSEL button pressed, copy over pico-debug.uf2, and i
 
 To cater to different user situations, there are two versions of pico-debug: **MAXRAM** and **GIMMECACHE**
 
+Most users will prefer to use the **GIMMECACHE** version.
+
 With **pico-debug-maxram**, *all* 264kBytes of SRAM on the RP2040 is available for running user code; pico-debug shoehorns itself entirely into the 16kBytes of XIP_SRAM (aka flash cache).
 
 With **pico-debug-gimmecache**, 248kBytes (94% of total) of SRAM is available for running user code; pico-debug gives plenty of elbow room by occupying only 6% near the very top of SRAM, and unlike MAXRAM, leaves the flash cache operational.
 
 If viewing this on github, pre-built binaries are available for download on the right under "Releases".
 
+## How to use
+
+Please read [howto/README.md](howto/README.md) for instructions on how to start using pico-debug.
+
 ## Caveats whilst using pico-debug
 
+The executive summary is:
+
+pico-debug uses the USB port to provide debugging to the user, so the user's app can't be simultaneously using the USB port! :)
+
+The specifics are:
+
 - MAXRAM only: the flash cache cannot be used by the user code, as pico-debug is using this memory
 - GIMMECACHE only: SRAM 0x2003C000 to 0x2003FFFF must not be used by user code
-- user code cannot reconfigure the PLL and clocks, as the USB peripheral needs this
+- user code cannot reconfigure the PLL_USB, as the USB peripheral needs this
 - the USB peripheral is used to provide the debugger, so the user code cannot use it as well
 
 ## License

howto/README.md

@@ -0,0 +1,8 @@
+## building Pico applications
+
+Please follow the instructions in [building.md](building.md).
+
+## debugging Pico applications with pico-debug
+
+After building Pico applications, please follow the instructions in [openocd.md](openocd.md).
+

howto/building.md

@@ -0,0 +1,66 @@
+## Download the Pico SDK and examples
+
+Create a subdirectory to hold the files that you will download:
+
+```
+$ cd ~/
+$ mkdir pico
+$ cd pico
+```
+
+Clone the pico-sdk and pico-examples git repositories:
+
+*NOTE: a substitute for pico-sdk is presently utilized, since pico-sdk currently lacks important features.*
+
+```
+$ git clone https://github.com/majbthrd/pico-sdk.git --branch pll_init
+$ cd pico-sdk
+$ git submodule update --init
+$ cd ..
+$ git clone -b master https://github.com/raspberrypi/pico-examples.git
+```
+
+## Install the Toolchain
+
+```
+$ sudo apt update
+$ sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential
+```
+
+## Invoking cmake
+
+From the pico directory we created earlier, cd into pico-examples and create a build directory:
+
+```
+$ cd ~/pico/pico-examples
+$ mkdir build
+$ cd build
+```
+
+Set PICO_SDK_PATH to point to the previously created pico-sdk directory:
+
+```
+$ export PICO_SDK_PATH=../../pico-sdk
+```
+
+Invoke cmake to create the files needed for building debug versions of examples:
+
+```
+$ cmake -DCMAKE_BUILD_TYPE=Debug ..
+Using PICO_SDK_PATH from environment ('../../pico-sdk')
+PICO_SDK_PATH is ...
+   .
+   .
+   .
+-- Build files have been written to: ...
+```
+
+## Building of "picoboard_blinky"
+
+```
+$ cd ~/pico/pico-examples/build/picoboard/blinky
+$ make -j4
+```
+
+At this point, you have picoboard_blinky.uf2 as well as all the files to optionally debug with openocd, gdb, and pico-debug.
+

howto/openocd.md

@@ -0,0 +1,116 @@
+## Build openocd
+
+*Until the CMSIS-DAP pull request is accepted by Raspberry Pi, we'll have to use a fork of their fork.*
+
+```
+$ sudo apt install automake autoconf build-essential texinfo libtool libhidapi-dev libusb-1.0-0-dev
+$ git clone https://github.com/majbthrd/openocd.git --recursive --branch rp2040_cmsisdap_demo --depth=1
+$ cd openocd
+$ ./bootstrap
+$ ./configure --enable-cmsis-dap
+$ make -j4
+$ sudo make install
+```
+
+## Install GDB
+
+```
+$ sudo apt install gdb-multiarch
+```
+
+## Use GDB, OpenOCD, and pico-debug to debug 'blinky'
+
+Obtain "pico-debug-gimmecache.uf2" from the Releases at:
+
+https://github.com/majbthrd/pico-debug
+
+Boot the RP2040 with the BOOTSEL button pressed, copy over pico-debug-gimmecache.uf2 to the RP2040, and it immediately reboots as a CMSIS-DAP adapter (ready for OpenOCD to talk to it).
+
+```
+$ openocd -f interface/cmsis-dap.cfg -c "transport select swd" -c "adapter speed 4000" -f target/rp2040-core0.cfg
+```
+
+Your output should look something like this:
+
+```
+Info : Hardware thread awareness created
+Info : RP2040 Flash Bank Command
+Info : Listening on port 6666 for tcl connections
+Info : Listening on port 4444 for telnet connections
+Info : CMSIS-DAP: SWD  Supported
+Info : CMSIS-DAP: FW Version = 2.0.0
+Info : CMSIS-DAP: Interface Initialised (SWD)
+Info : SWCLK/TCK = 0 SWDIO/TMS = 0 TDI = 0 TDO = 0 nTRST = 0 nRESET = 0
+Info : CMSIS-DAP: Interface ready
+Info : clock speed 4000 kHz
+Info : SWD DPIDR 0x0bc12477
+Info : SWD DLPIDR 0x00000001
+Info : rp2040.core0: hardware has 4 breakpoints, 2 watchpoints
+Info : starting gdb server for rp2040.core0 on 3333
+Info : Listening on port 3333 for gdb connections
+```
+
+This OpenOCD terminal needs to be left open. So go ahead and open another terminal, in this one we’ll attach a gdb instance to OpenOCD:
+
+```
+$ cd ~/pico/pico-examples/build/picoboard/blinky
+$ gdb-multiarch picoboard-blinky.elf
+```
+
+Connect GDB to OpenOCD:
+
+```
+(gdb) target remote localhost:3333
+```
+
+and load picoboard-blinky.elf into flash:
+
+```
+(gdb) load
+Loading section .boot2, size 0x100 lma 0x10000000
+Loading section .text, size 0x4828 lma 0x10000100
+Loading section .rodata, size 0xd6c lma 0x10004928
+Loading section .binary_info, size 0x1c lma 0x10005694
+Loading section .data, size 0xa4c lma 0x100056b0
+Start address 0x100001e8, load size 24828
+Transfer rate: 8 KB/sec, 4138 bytes/write.
+```
+
+and then start it running:
+
+```
+(gdb) monitor reset init
+(gdb) continue
+```
+
+Or, if you want to set a breakpoint at main() before running the executable:
+
+```
+(gdb) monitor reset init
+(gdb) b main
+(gdb) continue
+Continuing.
+Note: automatically using hardware breakpoints for read-only addresses.
+
+Breakpoint 1, main () at ../main.c:48
+48	  sys_init();
+```
+
+before continuing after you have hit the breakpoint:
+
+```
+(gdb) continue
+```
+
+if the target is running, it can be interrupted with Ctrl-C, at which point another gdb prompt should appear:
+
+```
+(gdb)
+```
+
+To quit from gdb, type:
+
+```
+(gdb) quit
+```
+