X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=README;h=429b8511f7dc7060a6a522279ad3fe0b379b635d;hb=0ff09f90ce176d0700eb88ec1ee1ec3932978c73;hp=47c7c2f05e81bb47128f7fc15731cadb4d4de903;hpb=47bb36079b0dbfafc4fc54d3734f95de92587080;p=fw%2Fstlink

diff --git a/README b/README
index 47c7c2f..429b851 100644
--- a/README
+++ b/README
@@ -1,20 +1,68 @@
 HOWTO
 =====
 
-To run the gdb server, do (you do not need sudo if you have
-set up permissions correctly):
-$ make -C build && sudo ./build/st-util 1234 /dev/sg1
+First, you have to know there are several boards supported by the software.
+Those boards use a chip to translate from USB to JTAG commands. The chip is
+called stlink and there are 2 versions:
+. STLINKv1, present on STM32VL discovery kits,
+. STLINKv2, present on STM32L discovery and later kits.
+
+2 different transport layers are used:
+. STLINKv1 uses SCSI passthru commands over USB,
+. STLINKv2 uses raw USB commands.
+
+It means that if you are using a STM32VL board, you have to install and load
+SCSI related software. First, load the sg kernel module:
+# modprobe sg
+
+Then, you need to install the package libsgutils2-dev. On Ubuntu:
+# sudo apt-get install libsgutils2-dev
+
+LIBUSB is required for both cases.
+
+To run the gdb server, do (you do not need sudo if you have set up
+permissions correctly):
+$ make -C build && sudo ./build/st-util [/dev/sgX]
+
+Currently, the GDB server listening port is hardcoded to 4242:
 
 Then, in gdb:
-(gdb) target remote :1234
+(gdb) target remote :4242
 
 Have fun!
 
+Resetting the chip from GDB
+===========================
+
+You may reset the chip using GDB if you want. You'll need to use `target
+extended-remote' command like in this session:
+(gdb) target extended-remote localhost:4242
+Remote debugging using localhost:4242
+0x080007a8 in _startup ()
+(gdb) kill
+Kill the program being debugged? (y or n) y
+(gdb) run
+Starting program: /home/whitequark/ST/apps/bally/firmware.elf 
+
+Remember that you can shorten the commands. `tar ext :4242' is good enough
+for GDB.
+
+Setting up udev rules
+=====================
+
+For convenience, you may install udev rules file, 10-stlink.rules, located
+in the root of repository. You will need to copy it to /etc/udev/rules.d,
+and then either reboot or execute
+$ udevadm control --reload-rules
+
+Udev will now create a /dev/stlink file, which will point at appropriate
+/dev/sgX device. Good to not accidentally start debugging your flash drive.
+
 Running programs from SRAM
 ==========================
 
-You can run your firmware directly from SRAM if you want to.
-Just link it at 0x20000000 and do
+You can run your firmware directly from SRAM if you want to. Just link
+it at 0x20000000 and do
 (gdb) load firmware.elf
 
 It will be loaded, and pc will be adjusted to point to start of the
@@ -28,18 +76,20 @@ If you would link your executable to 0x08000000 and then do
 (gdb) load firmware.elf
 then it would be written to the memory.
 
-Caveats
-=======
+FAQ
+===
+
+Q: My breakpoints do not work at all or only work once.
 
-`continue' GDB command does not work: target does not step at
-all or steps with a turtle speed. Looks like there's something
-wrong with SCSI requests.
+A: Optimizations can cause severe instruction reordering. For example,
+if you are doing something like `REG = 0x100;' in a loop, the code may
+be split into two parts: loading 0x100 into some intermediate register
+and moving that value to REG. When you set up a breakpoint, GDB will
+hook to the first instruction, which may be called only once if there are
+enough unused registers. In my experience, -O3 causes that frequently.
 
-GDB sends requests for a multi-sectioned ELF files (most ones;
-having both .text and .rodata is enough) in a quite strange way which
-absolutely does not conform to flash page boundaries. Which is even more
-weird when you think about FlashErase requests which it sends correctly.
-And I couldn't think of a way which will resolve this correctly now.
+Q: At some point I use GDB command `next', and it hangs.
 
-Hardware breakpoints are not supported yet. You can still run your code from
-RAM, and then GDB will insert bkpt opcodes automagically.
+A: Sometimes when you will try to use GDB `next' command to skip a loop,
+it will use a rather inefficient single-stepping way of doing that.
+Set up a breakpoint manually in that case and do `continue'.