Update documentation removing all sg-utils notes

Just libusb now. Verified the modprobe.conf on Ubuntu 10.04
2011-11-04 01:56:22 +00:00 · 2011-11-04 01:56:22 +00:00 · b463d50c5b
commit b463d50c5b
--- a/10-stlink.rules
+++ b/10-stlink.rules
@ -1,43 +0,0 @@
-# This file was taken from arm-utilites project, located at
-# http://code.google.com/p/arm-utilities/, which is licensed under GPL3.
-# An explicit permission to include any code from that project in
-# this one under BSD license was granted by arm-utilites author, Donald Becker.
-
-# This file watches for a STMicro ST-Link or STM32VLDiscovery board
-# and creates a device named /dev/stlink
-# See udev(7) for syntax.
-#
-# Written 2010,2011 by Donald Becker
-#
-# The STLink on the Discovery has a USB ID 0483:3744 and presents itself
-# as a mass storage (i.e. SCSI) device.  The SCSI emulation is signficantly
-# broken, and the kernel spews error reports for a while until it is
-# accepted.  Further problems are encountered when if it is automatically
-# mounted.
-#
-# Options that may prevent the mount are
-# ENV{UDISKS_PRESENTATION_HIDE}:="1",
-# ENV{UDISKS_PRESENTATION_NOPOLICY}:="1",
-# ENV{DM_UDEV_DISABLE_DISK_RULES_FLAG}:="1"
-
-ACTION!="add|change", GOTO="stlink_rules_end"
-
-SUBSYSTEMS=="usb", ATTR{idVendor}=="0483", ATTR{idProduct}=="3744", \
-   MODE="0664", GROUP="tape", NAME="stlinkusb%n", ENV{STLINK}="1", \
-   ENV{UDISKS_PRESENTATION_HIDE}:="1", \
-   ENV{UDISKS_PRESENTATION_NOPOLICY}:="1", \
-   ENV{DM_UDEV_DISABLE_DISK_RULES_FLAG}:="1", \
-   OPTIONS="last_rule"
-
-# Other possible settings:
-# OPTIONS="last_rule", ATTRS{vendor}=="STM32"
-
-KERNEL=="sg[0-9]*", MODE="0664", GROUP:="tape", \
-  NAME+="stlink-sg%n", SYMLINK+="stlink", \
-  ENV{UDISKS_PRESENTATION_HIDE}:="1", \
-  ENV{UDISKS_PRESENTATION_NOPOLICY}:="1", \
-  ENV{DM_UDEV_DISABLE_DISK_RULES_FLAG}:="1"
-
-SUBSYSTEM=="scsi", ATTR{vendor}=="STM32", MODE="0664", GROUP="tape", NAME="stlinksg-scsi%n", SYMLINK+="stlinkscsi", OPTIONS="last_rule"
-
-LABEL="stlink_rules_end"
--- a/50
+++ b/50
@ -11,22 +11,47 @@ called stlink and there are 2 versions:
 . 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
+Common requirements
+~~~~~~~~~~~~~~~~~~~

-Then, you need to install the package libsgutils2-dev. On Ubuntu:
-# sudo apt-get install libsgutils2-dev
+libusb-1.0  (You probably already have this, but you'll need the 
+development version to compile)

-LIBUSB is required for both cases.
+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 [/dev/sgX]
+$ make && [sudo] ./gdbserver/st-util 

-Currently, the GDB server listening port is hardcoded to 4242:
+There are a few options:

-Then, in gdb:
+./gdbserver/st-util - usage:
+
+  -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!
@ -50,13 +75,14 @@ for GDB.
 Setting up udev rules
 =====================

-For convenience, you may install udev rules file, 10-stlink.rules, located
+For convenience, you may install udev rules file, 49-stlinkv2.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.
+Udev will now create a /dev/stlinkv2_XX file, with the appropriate permissions.
+This is currently all the device is for, (only one stlinkv2 is supported at 
+any time presently)

 Running programs from SRAM
 ==========================
--- a/3
+++ b/3
@ -7,9 +7,6 @@
 . documentation
 . make README points to doc/tutorial

-. remove libsg dependency using:
-https://github.com/afaerber/stlink/tree/master/libstlink
-
 . compile and test a realtime kernel, for instance:
 http://www.chibios.org/dokuwiki/doku.php?id=chibios:articles:stm32l_discovery
 svn checkout https://chibios.svn.sourceforge.net/svnroot/chibios/trunk ;
--- a/src/stlink-sg.c
+++ b/src/stlink-sg.c
@ -12,7 +12,6 @@
 The stlink related constants kindly provided by Oliver Spencer (OpenOCD)
 for use in a GPL compatible license.

- Code format ~ TAB = 8, K&R, linux kernel source, golang oriented
 Tested compatibility: linux, gcc >= 4.3.3

 The communication is based on standard USB mass storage device
@ -31,10 +30,18 @@
 CBW 		- Command Block Wrapper
 CSW		- Command Status Wrapper
 RFU		- Reserved for Future Use
- scsi_pt	- SCSI pass-through
- sg		- SCSI generic

- * usb-storage.quirks
+ Originally, this driver used scsi pass through commands, which required the
+ usb-storage module to be loaded, providing the /dev/sgX links.  The USB mass
+ storage implementation on the STLinkv1 is however terribly broken, and it can 
+ take many minutes for the kernel to give up.
+ 
+ However, in Nov 2011, the scsi pass through was replaced by raw libusb, so 
+ instead of having to let usb-storage struggle with the device, and also greatly 
+ limiting the portability of the driver, you can now tell usb-storage to simply
+ ignore this device completely.
+   
+ usb-storage.quirks
 http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/kernel-parameters.txt
 Each entry has the form VID:PID:Flags where VID and PID are Vendor and Product
 ID values (4-digit hex numbers) and Flags is a set of characters, each corresponding
@ -54,18 +61,17 @@

 Example: quirks=0419:aaf5:rl,0421:0433:rc
 http://permalink.gmane.org/gmane.linux.usb.general/35053
+ 
+ For the stlinkv1, you just want the following

- modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:l
+ modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i

 Equivalently, you can add a line saying

- options usb-storage quirks=483:3744:l
+ options usb-storage quirks=483:3744:i

 to your /etc/modprobe.conf or /etc/modprobe.d/local.conf (or add the "quirks=..."
 part to an existing options line for usb-storage).
-
- https://wiki.kubuntu.org/Kernel/Debugging/USB explains the protocoll and 
- would allow to replace the sg access to pure libusb access
 */


--- a/stlink.modprobe.conf
+++ b/stlink.modprobe.conf
@ -1 +0,0 @@
-options usb-storage quirks=483:3744:l
--- a/stlink_v1.modprobe.conf
+++ b/stlink_v1.modprobe.conf
@ -0,0 +1 @@
+options usb-storage quirks=483:3744:i