Print undecode chip_id too

[fw/stlink] / README

diff --git a/README b/README
index 920786ebf407b57d062bafbfbba5ac5484630004..1eb6d26173fa48103d0036d284afa27889eb22c1 100644 (file)
--- a/README
+++ b/README
@@ -1,12 +1,66 @@
+IMPORTANT SHORT TERM NOTICE:
+If you are targetting F1 devices, with either stlinkv1 or v2 hardware, you
+_need_ to use karlp's libwork2 branch.  
+
+If you are targetting F4, you _need_ to use texane's master
+
+If you are targetting F2 or L1, please let us know how it goes!
+
 HOWTO
 =====
 
+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.
+
+Common requirements
+~~~~~~~~~~~~~~~~~~~
+
+libusb-1.0  (You probably already have this, but you'll need the 
+development version to compile)
+
+IF YOU HAVE AN STLINKv1
+~~~~~~~~~~~~~~~~~~~~~~~
+The STLINKv1's SCSI emulation is very broken, so the best thing to do
+is tell your operating system to completely ignore it.
+
+Options (do one of these before you plug it in)
+   *) modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i
+or *)1. add "options usb-storage quirks=483:3744:i" to /etc/modprobe.conf
+   *)2. modprobe -r usb-storage && modprobe usb-storage
+or *)1. cp stlink_v1.modprobe.conf /etc/modprobe.d
+   *)2. modprobe -r usb-storage && modprobe usb-storage
+
+IF YOU HAVE AN STLINKv2
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You're ready to go :)
+
 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
+$ make && [sudo] ./gdbserver/st-util 
+
+There are a few options:
+
+./gdbserver/st-util - usage:
 
-Then, in gdb:
-(gdb) target remote :1234
+  -h, --help        Print this help
+  -vXX, --verbose=XX    specify a specific verbosity level (0..99)
+  -v, --verbose specify generally verbose logging
+  -s X, --stlink_version=X
+            Choose what version of stlink to use, (defaults to 2)
+  -1, --stlinkv1    Force stlink version 1
+  -p 4242, --listen_port=1234
+            Set the gdb server listen port. (default port: 4242)
+
+Then, in gdb: (remember, you need to run an _ARM_ gdb, not an x86 gdb)
+(gdb) target remote :4242
 
 Have fun!
 
@@ -15,17 +69,29 @@ 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:1111
-Remote debugging using localhost:1111
+(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 :1111' is good enough
+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, 49-stlinkv*.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/stlinkv2_XX or /dev/stlinkv1_XX file, with the appropriate permissions.
+This is currently all the device is for, (only one stlink of each version is supported at 
+any time presently)
+
 Running programs from SRAM
 ==========================
 
@@ -44,6 +110,7 @@ If you would link your executable to 0x08000000 and then do
 (gdb) load firmware.elf
 then it would be written to the memory.
 
+
 FAQ
 ===
 
@@ -61,3 +128,24 @@ Q: At some point I use GDB command `next', and it hangs.
 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'.
+
+Currently known working combinations of programmer and target
+=============================================================
+
+STLink v1 (as found on the 32VL Discovery board)
+
+Known Working Targets:
+* STM32F100xx (Medium Density VL)
+* STM32F103 (according to jpa- o n##stm32
+
+No information:
+* everything else!
+
+
+STLink v2 (as found on the 32L and F4 Discovery boards)
+Known Working Targets:
+* STM32F100xx (Medium Density VL, as on the 32VL Discovery board)
+* ?
+
+Please report any and all known working combinations so I can update this!
+