nusb: implement aijus stable uniqueue device names

instead of naming devices by ther dynamically assigned device address,
we hash device uniqueue fields from the device descriptor and produce
a 5 digit hex string that will identify the device across machines.

when there is a collision (less than 1% chance with 100 devices),
usbd will append the device address to the name to make it uniqueue
for this machine.

the hname is passed to drivers in the devid argument, which now has
the form addr:hname, where the colon and hname can be omited (for backwards
compatibility).

when the new behaviour isnt desired, nousbhname= environment variable
can be defined giving the old behaviour.

4 files changed, 50 insertions, 17 deletions

diff --git a/sys/man/2/nusb b/sys/man/2/nusb
index dfca0cf5c..681a76fbf 100644
--- a/sys/man/2/nusb
+++ b/sys/man/2/nusb
@@ -28,6 +28,7 @@ struct Dev {
 	Usbdev*	usb;		/* USB description */
 	void*	aux;		/* for the device driver */
 	void	(*free)(void*);	/* idem. to release aux */
+	char*	hname;		/* hash name, uniqueue for device */
 };
 .sp 0.3v
 struct Usbdev {
@@ -119,7 +120,7 @@ Dev*	openep(Dev *d, int id);
 int	unstall(Dev *dev, Dev *ep, int dir);
 int	usbcmd(Dev *d, int type, int req,
 		int value, int index, uchar *data, int count);
-Dev*	getdev(int id);
+Dev*	getdev(char *devid);
 .sp 0.3v
 extern int usbdebug;	/* more messages for bigger values */
 .EE
diff --git a/sys/man/4/nusb b/sys/man/4/nusb
index efcc95eab..fc5d16e42 100644
--- a/sys/man/4/nusb
+++ b/sys/man/4/nusb
@@ -88,23 +88,41 @@ attachment. It provides a filesystem with the file
 .B usbevent
 (usually seen as
 .BR /dev/usbevent )
-which, when read, returns a 5 column, space separated line of
+which, when read, returns a 6 column, space separated line of
 text, one for each event. The columns are:
 .B attach
 or
 .B detach
-.I devid
+followed by
+.I addr
 .I vid
 .I did
+.I csp
 and
-.I csp .
-All but
-.I devid
-are formatted as 4 digit hexadecimal. This file is read by
+.I hname .
+The
+.I addr
+is the decimal device address assigned.
+.I Vid
+and
+.I did
+are formatted as 4 digit hexadecimal.
+.I Csp
+is the device class, subclass, protocol indentifier
+formatd as 6 digit hexadecimal.
+.I Usbd
+assigns a stable device uniqueue name based on the
+device descriptor for
+.I hname .
+This information is read by
 .IR nusbrc (8)
 and the
+.I addr
+and
+.I hname
+are passed to a suitable driver as
 .I devid
-is passed to a suitable driver.
+in the form \fIaddr\fB:\fIhname
 .SS Keyboards and mice
 .I Kb
 supports USB keyboards and mice either as separate USB devices
@@ -123,13 +141,10 @@ configures and manages USB mass storage devices. It
 provides a file system (usually seen under
 .BR /dev )
 that includes one directory per storage device, named
-.BI sdU N . M
-in correspondence with the usb device number and the storage
-unit number (or LUN).
-For example, LUN number 2 on
-.B /dev/usb/ep3.0
-can be accessed through
-.BR /dev/sdU3.2 .
+.BI sdU N [. M ]
+in correspondence with the usb device uniqueue name
+and the storage unit number (or LUN). The LUN is omited
+for single lun devices.
 .PP
 The storage device directory contains the usual files
 served by
@@ -183,7 +198,7 @@ provides a file system (usually seen under
 that includes one directory per USB serial port, named
 .BI eiaU N
 or
-.BI eiaU N . M.
+.BI eiaU N [. M ].
 In this directory there are two files,
 .BR eiaU ,
 similar to
diff --git a/sys/man/8/nusbrc b/sys/man/8/nusbrc
index 2105be95b..b6c5e5814 100644
--- a/sys/man/8/nusbrc
+++ b/sys/man/8/nusbrc
@@ -15,9 +15,21 @@ or
 .IR cpurc (8)),
 .I nusbrc
 handles the startup and shutdown of usb drivers on physical
-device attach and detach events.
+device attach and detach events by reading
+.B /dev/usbevent
+file.
 .SH SOURCE
 .B /rc/bin/nusbrc
 .B /sys/src/9/boot/nusbrc
 .SH "SEE ALSO"
 .IR nusb (4)
+.SH BUGS
+Usb devices appear as files under
+.B /dev
+and
+.B /shr
+identified by the devices uniqueue name assigned by usbd.
+When the environment variable
+.I nousbhname
+is defined, devies are named by ther dynamically assigned
+usb device address instead. This emulates the old behaviour.
diff --git a/sys/man/8/plan9.ini b/sys/man/8/plan9.ini
index 70c04e8fc..6d936f86b 100644
--- a/sys/man/8/plan9.ini
+++ b/sys/man/8/plan9.ini
@@ -812,6 +812,11 @@ It is not on by default because it causes problems on some laptops.
 .SS \fLusbwait=\fIvalue\fP
 This changes the sleep time from the default 2 to value in cases of
 USB devices taking a long time to come online.
+.SS \fLnousbhname=\fP
+When defined,
+.IR nusbrc (8)
+will use the dynamically assigned usb device address to name
+usb devices instead of the device uniqueue name.
 .SS VIDEO
 .SS \fLmonitor=\fIvalue\fP
 .SS \fLvgasize=\fIvalue\fP