From e7dd313a963f653127a0931ff44323b28298f863 Mon Sep 17 00:00:00 2001 From: Kevin O'Connor Date: Fri, 28 Jun 2019 19:14:55 -0400 Subject: [PATCH] docs: Add information on using OpenOCD to Bootloaders.md Add information on using OpenOCD. Add information on flashing the SAMD21 and SAMD51 with OpenOCD. Signed-off-by: Kevin O'Connor --- docs/Bootloaders.md | 190 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 176 insertions(+), 14 deletions(-) diff --git a/docs/Bootloaders.md b/docs/Bootloaders.md index 23fb519e..ae4d8721 100644 --- a/docs/Bootloaders.md +++ b/docs/Bootloaders.md @@ -190,31 +190,71 @@ SAMD21 micro-controllers (Arduino Zero) The SAMD21 bootloader is flashed via the ARM Serial Wire Debug (SWD) interface. This is commonly done with a dedicated SWD hardware dongle. -Alternatively, it appears one can use a Raspberry Pi with OpenOCD as a -programmer (see: -[https://learn.adafruit.com/programming-microcontrollers-using-openocd-on-raspberry-pi](https://learn.adafruit.com/programming-microcontrollers-using-openocd-on-raspberry-pi) -). +Alternatively, one can use a +[Raspberry Pi with OpenOCD](#running-openocd-on-the-raspberry-pi). -Unfortunately, there are two common bootloaders deployed on the -SAMD21. One comes standard with the "Arduino Zero" and the other comes -standard with the "Arduino M0". +To flash a bootloader with OpenOCD use a chip config similar to: +``` +set CHIPNAME at91samd21g18 +source [find target/at91samdXX.cfg] +``` +Obtain a bootloader - for example: +``` +wget 'https://github.com/arduino/ArduinoCore-samd/raw/1.8.3/bootloaders/zero/samd21_sam_ba.bin' +``` +Flash with OpenOCD commands similar to: +``` +at91samd bootloader 0 +program samd21_sam_ba.bin verify +``` -The Arduino Zero uses an 8KiB bootloader (the application must be -compiled with a start address of 8KiB). One can enter the bootloader +The most common bootloader on the SAMD21 is the one found on the +"Arduino Zero". It uses an 8KiB bootloader (the application must be +compiled with a start address of 8KiB). One can enter this bootloader by double clicking the reset button. To flash an application use something like: ``` -bossac -U -p "$(FLASH_DEVICE)" --offset=0x2000 -w out/klipper.bin -v -b -R +bossac -U -p /dev/ttyACM0 --offset=0x2000 -w out/klipper.bin -v -b -R ``` -The Arduino M0 uses a 16KiB bootloader (the application must be -compiled with a start address of 16KiB). To flash an application, -reset the micro-controller and run the flash command within the first -few seconds of boot - something like: +In contrast, the "Arduino M0" uses a 16KiB bootloader (the application +must be compiled with a start address of 16KiB). To flash an +application on this bootloader, reset the micro-controller and run the +flash command within the first few seconds of boot - something like: ``` avrdude -c stk500v2 -p atmega2560 -P /dev/ttyACM0 -u -Uflash:w:out/klipper.elf.hex:i ``` +SAMD51 micro-controllers (Adafruit Metro-M4 and similar) +======================================================== + +Like the SAMD21, the SAMD51 bootloader is flashed via the ARM Serial +Wire Debug (SWD) interface. To flash a bootloader with +[OpenOCD on a Raspberry Pi](#running-openocd-on-the-raspberry-pi) use +a chip config similar to: +``` +set CHIPNAME at91samd51g19 +source [find target/atsame5x.cfg] +``` +Obtain a bootloader - several bootloaders are available from +[https://github.com/adafruit/uf2-samdx1/releases/latest](https://github.com/adafruit/uf2-samdx1/releases/latest). For example: +``` +wget 'https://github.com/adafruit/uf2-samdx1/releases/download/v3.7.0/bootloader-itsybitsy_m4-v3.7.0.bin' +``` +Flash with OpenOCD commands similar to: +``` +at91samd bootloader 0 +program bootloader-itsybitsy_m4-v3.7.0.bin verify +at91samd bootloader 16384 +``` + +The SAMD51 uses a 16KiB bootloader (the application must be compiled +with a start address of 16KiB). To flash an application use something +like: +``` +bossac -U -p /dev/ttyACM0 --offset=0x4000 -w out/klipper.bin -v -b -R +``` + STM32F103 micro-controllers (Blue Pill devices) =============================================== @@ -276,3 +316,125 @@ start address of 16KiB. The easiest way to flash an application with this bootloader is to copy the application file (eg, `out/klipper.bin`) to a file named `firmware.bin` on an SD card, and then to reboot the micro-controller with that SD card. + +Running OpenOCD on the Raspberry PI +=================================== + +OpenOCD is a software package that can perform low-level chip flashing +and debugging. It can use the GPIO pins on a Raspberry Pi to +communicate with a variety of ARM chips. + +This section describes how one can install and launch OpenOCD. It is +derived from the instructions at: +[https://learn.adafruit.com/programming-microcontrollers-using-openocd-on-raspberry-pi](https://learn.adafruit.com/programming-microcontrollers-using-openocd-on-raspberry-pi) + +Begin by downloading and compiling the software (each step may take +several minutes and the "make" step may take 30+ minutes): + +``` +sudo apt-get update +sudo apt-get install autoconf libtool telnet +mkdir ~/openocd +cd ~/openocd/ +git clone http://openocd.zylin.com/openocd +cd openocd +./bootstrap +./configure --enable-sysfsgpio --enable-bcm2835gpio --prefix=/home/pi/openocd/install +make +make install +``` + +## Configure OpenOCD + +Create an OpenOCD config file: + +``` +nano ~/openocd/openocd.cfg +``` + +Use a config similar to the following: + +``` +# Uses RPi pins: GPIO25 for SWDCLK, GPIO24 for SWDIO, GPIO18 for nRST +source [find interface/raspberrypi2-native.cfg] +bcm2835gpio_swd_nums 25 24 +bcm2835gpio_srst_num 18 +transport select swd + +# Set the chip (at91samd51j19 in this example) +set CHIPNAME at91samd51j19 +source [find target/atsame5x.cfg] + +# Set the adapter speed +adapter_khz 40 +adapter_nsrst_delay 100 +adapter_nsrst_assert_width 100 + +init +targets +reset halt +``` + +## Wire the Raspberry Pi to the target chip + +Poweroff both the the Raspberry Pi and the target chip before wiring! +Verify the target chip uses 3.3V prior to connecting to a Raspberry +Pi! + +Connect GND, SWDCLK, SWDIO, and RST on the target chip to GND, GPIO25, +GPIO24, and GPIO18 respectively on the Raspberry Pi. + +Then power up the Raspberry Pi and provide power to the target chip. + +## Run OpenOCD + +Run OpenOCD: + +``` +cd ~/openocd/ +sudo ~/openocd/install/bin/openocd -f ~/openocd/openocd.cfg +``` + +The above should cause OpenOCD to emit some text messages and then +wait (it should not immediately return to the Unix shell prompt). If +OpenOCD exits on its own or if it continues to emit text messages then +double check the wiring. + +Once OpenOCD is running and is stable, one can send it commands via +telnet. Open another ssh session and run the following: + +``` +telnet 127.0.0.1 4444 +``` + +(One can exit telnet by pressing ctrl+] and then running the "quit" +command.) + +## OpenOCD and gdb + +It is possible to use OpenOCD with gdb to debug Klipper. The following +commands assume one is running gdb on a desktop class machine. + +Add the following to the OpenOCD config file: + +``` +bindto 0.0.0.0 +gdb_port 44444 +``` + +Restart OpenOCD on the Raspberry Pi and then run the following Unix +command on the desktop machine: + +``` +cd /path/to/klipper/ +gdb out/klipper.elf +``` + +Within gdb run: + +``` +target remote octopi:44444 +``` + +(Replace "octopi" with the host name of the Raspberry Pi.) Once gdb is +running it is possible to set breakpoints and to inspect registers.