nusb: fix documentation, cleanup, remove /sys/src/cmd/usb

2 files changed, 6 insertions, 421 deletions

diff --git a/sys/man/2/usb b/sys/man/2/nusb
index d6f949f98..e771cb56f 100644
--- a/sys/man/2/usb
+++ b/sys/man/2/nusb
@@ -1,17 +1,15 @@
-.TH USB 2
+.TH NUSB 2
 .SH NAME
 usbcmd,
 classname,
 closedev,
 configdev,
 devctl,
-finddevs,
+getdev,
 loaddevstr,
-matchdevcsp,
 opendev,
 opendevdata,
 openep,
-startdevs,
 unstall,
 class,
 subclass,
@@ -22,7 +20,6 @@ CSP \- USB device driver library
 .ta 8n +8n +8n +8n +8n +8n +8n
 #include <u.h>
 #include <libc.h>
-#include <thread.h>
 #include "../lib/usb.h"
 .sp 0.3v
 struct Dev {
@@ -118,18 +115,15 @@ int	configdev(Dev *d);
 int	devctl(Dev *dev, char *fmt, ...);
 void*	emallocz(ulong size, int zero);
 char*	estrdup(char *s);
-int	finddevs(int (*matchf)(char*,void*), void *farg, char** dirs, int ndirs);
 char*	hexstr(void *a, int n);
 char*	loaddevstr(Dev *d, int sid);
-int	matchdevcsp(char *info, void *a);
 Dev*	opendev(char *fn);
 int	opendevdata(Dev *d, int mode);
 Dev*	openep(Dev *d, int id);
-void	startdevs(char *args, char *argv[], int argc,
-		int (*mf)(char*,void*), void*ma, int (*df)(Dev*,int,char**));
 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);
 .sp 0.3v
 extern int usbdebug;	/* more messages for bigger values */
 .EE
@@ -140,27 +134,14 @@ It is not intended for user programs using USB devices.
 See
 .IR usb (3)
 for a description of the interfaces provided for that purpose.
-For drivers that provide a file system and may be embedded into
-.IR usbd ,
-the library includes a file system implementation toolkit described in
-.IR usbfs (2).
 .PP
 Usb drivers rely on
 .IR usb (3)
 to perform I/O through USB as well as on
-.IR usbd (4)
+.IR usbd
 to perform the initial configuration for the device's setup endpoint.
 The rest of the work is up to the driver and is where this library may help.
 .PP
-In most cases, a driver locates the devices of interest and configures them
-by calling
-.I startdevs
-and
-then sets up additional endpoints as needed (by calling
-.IR openep )
-to finally perform I/O by reading and writing the
-data files for the endpoints.
-.PP
 An endpoint as provided by
 .IR usb (3)
 is represented by a
@@ -238,54 +219,6 @@ to the library are kept unparsed at
 as an aid for the driver
 (which should know how to parse them and what to do with the information).
 .SS Configuration
-.I Startdevs
-is a wrapper that locates devices of interest, loads their configuration
-information, and starts a
-.IR thread (2)'s
-.I proc
-for each device located so that it executes
-.I f
-as its main entry point. The entry point is called with a pointer to
-the
-.B Dev
-for the device it has to process,
-.BR argc ,
-and
-.BR argv .
-Devices are located either from the arguments (after options) in
-.IR argv ,
-if any,
-or by calling the helper function
-.I mf
-with the argument
-.I ma
-to determine (for each device available) if the device belongs to
-the driver or not. If the function returns -1 then the device is not for us.
-.PP
-In many cases,
-.I matchdevcsp
-may be supplied as
-.I mf
-along with a (null terminated) vector of CSP values supplied as
-.IR ma .
-This function returns 0 for any device with a CSP matching one in the
-vector supplied as an argument and -1 otherwise.
-In other cases (eg., when a particular vendor and device ids are the
-ones identifying the device) the driver must include its own function
-and supply it as an argument to
-.IR startdevs .
-The first argument of the function corresponds to the information
-known about the device (the second line in its
-.B ctl
-file).
-.I Openep
-creates the endpoint number
-.I id
-for the device
-.I d
-and returns a
-.B Dev
-structure to operate on it (with just the control file open).
 .PP
 .I Opendev
 creates a
@@ -306,11 +239,6 @@ loads and parses its configuration information.
 After calling it, the device is ready for I/O and the USB description in
 .B Dev.usb
 is valid.
-When using
-.IR startdevs
-it is not desirable to call this function (because
-.IR startdevs
-already calls it).
 .PP
 Control requests for an endpoint may be written by calling
 .I devctl
@@ -450,11 +378,9 @@ and memory must be released by the caller.
 returns the string obtained by reading the device string descriptor number
 .IR sid .
 .SH SOURCE
-.B /sys/src/cmd/usb/lib
+.B /sys/src/cmd/nusb/lib
 .SH "SEE ALSO"
-.IR usbfs (2),
 .IR usb (3),
-.IR usb (4),
-.IR usbd (4).
+.IR nusb (4).
 .SH BUGS
 Not heavily exercised yet.
diff --git a/sys/man/2/usbfs b/sys/man/2/usbfs
deleted file mode 100644
index 6c76280a8..000000000
--- a/sys/man/2/usbfs
+++ /dev/null
@@ -1,341 +0,0 @@
-.TH USBFS 2
-.SH NAME
-usbreadbuf,
-usbfsadd,
-usbfsdel,
-usbdirread,
-usbfsinit,
-usbdirfs,
-usbfs \- USB device driver file system library
-.SH SYNOPSIS
-.EX
-.ta 8n +8n +8n +8n +8n +8n +8n
-#include <u.h>
-#include <libc.h>
-#include <thread.h>
-#include "../lib/usb.h"
-#include "../lib/usbfs.h"
-.sp 0.3v
-enum {
-	Hdrsize	= 128,		/* plenty of room for headers */
-	Msgsize	= 8 * 1024,
-	Bufsize	= Hdrsize + Msgsize,
-	Namesz = 40,
-	Errmax = 128,
-	ONONE = ~0,		/* omode in Fid when not open */
-};
-.sp 0.3v
-struct Fid {
-	int	fid;
-	Qid	qid;
-	int	omode;
-	Fid*	next;
-	void*	aux;
-};
-.sp 0.3v
-struct Usbfs {
-	char	name[Namesz];
-	uvlong	qid;
-	Dev*	dev;
-	void*	aux;
-.sp 0.3v
-	int	(*walk)(Usbfs *fs, Fid *f, char *name);
-	void	(*clone)(Usbfs *fs, Fid *of, Fid *nf);
-	void	(*clunk)(Usbfs *fs, Fid *f);
-	int	(*open)(Usbfs *fs, Fid *f, int mode);
-	long	(*read)(Usbfs *fs, Fid *f,
-			void *data, long count, vlong offset);
-	long	(*write)(Usbfs *fs, Fid*f,
-			void *data, long count, vlong offset);
-	int	(*stat)(Usbfs *fs, Qid q, Dir *d);
-	void	(*end)(Usbfs *fs);
-};
-.sp 0.3v
-typedef int (*Dirgen)(Usbfs*, Qid, int, Dir*, void*);
-.sp 0.3v
-long	usbreadbuf(void *data, long count,
-		vlong offset, void *buf, long n);
-void	usbfsadd(Usbfs *dfs);
-void	usbfsdel(Usbfs *dfs);
-int	usbdirread(Usbfs*f, Qid q, char *data, long cnt,
-		vlong off, Dirgen gen, void *arg);
-void	usbfsinit(char* srv, char *mnt, Usbfs *f, int flag);
-void	usbfsdirdump(void);
-.sp 0.3v
-extern char Enotfound[], Etoosmall[], Eio[], Eperm[], Ebadcall[],
-	Ebadfid[], Einuse[], Eisopen[], Ebadctl[];
-.sp 0.3v
-extern Usbfs usbdirfs;
-extern int usbfsdebug;
-.EE
-.SH DESCRIPTION
-This library provides an alternative to
-.IR 9p (2)
-for implementing a file server within a USB driver.
-Drivers using this
-library may be embedded into
-.IR usbd (4).
-It may be also desirable to use this library when drivers are
-not embedded because it is tailored to work well with the
-library for handling USB devices.
-.PP
-A USB file system is described by a
-.I Usbfs
-structure.
-In most cases, the driver is not responsible for the root of the
-file tree.
-It is customary that a driver creates a file server
-for each device handled and links all of them to a root directory
-implemented by the
-.I usbdirfs
-file system implemented by the library.
-This root directory is bound to
-.B /dev
-in most cases.
-.PP
-.I Usbdirfs
-implements a root directory populated by named file trees,
-each one described by a
-.B Usbfs
-structure.
-.PP
-The field
-.B Usbfs.name
-contains the name for the root directory of the file system, usually
-a directory seen at
-.BI /dev/ name
-when the driver is embedded.
-.PP
-.B Usbfs.qid
-maintains a value used to decorate qids for the file tree.
-This may be ignored when
-.I usbdirfs
-is not used.
-Otherwise,
-.I usbdirfs
-assigns a unique value kept at the high 32 bits of
-.B Qid.path
-for all files on each file tree bound to it.
-Each
-.I Usbfs
-server must bitwise OR
-.B Usbfs.qid
-to all
-.B Qid.path
-values returned by its functions.
-In the same way,
-functions usually clear bits in
-.B Usbfs.qid
-before processing
-.B Qid.path
-values supplied as input.
-.PP
-The USB device handled by a file tree is referenced from
-.B Usbfs.dev
-(and a reference must be counted for it).
-This permits the following functions to quickly locate the device of
-interest, and also permits releasing the device when
-no request is outstanding.
-.PP
-The field
-.B Usbfs.aux
-is for the device to use.
-The rest of the fields implement the 9P protocol for the device.
-Not all the operations need be implemented.
-Only
-.IR walk ,
-.IR open ,
-.IR read ,
-.IR write ,
-and
-.IR stat ,
-must be implemented (and their corresponding fields in
-.B Usbfs
-may never be
-.BR nil ).
-These functions must return -1 upon failure
-and set the error string to reflect the cause of a failure.
-.PP
-In all the functions, a 9P fid is represented by a
-.B Fid
-structure.
-It contains the 9P
-.IR fid ,
-the corresponding
-.IR qid ,
-and an auxiliary pointer for the driver to use.
-Open
-.IR fid s
-have a valid open mode in
-.I omode
-while others have
-.B ONONE
-to indicate that the
-.I fid
-is not open.
-The library takes care of which
-fids
-exist and which ones do not.
-.PP
-.I Walk
-must walk
-.I f
-to
-.I name
-(a single name, not a file path)
-in the supplied
-.IR fs .
-Its implementation should update the qid in
-.I f
-to reflect the walk.
-This function must bitwise OR any returned Qid with
-.B Usbfs.qid ,
-if
-.I usbdirfs
-is used.
-.PP
-.I Clone
-must clone fid
-.I of
-onto
-.I nf
-so that,
-upon successful completion,
-.I nf
-also refers to the file that
-.I f
-refers to.
-An implementation must update the Qid of the cloned
-fid.
-If this function is not supplied, the library copies the
-.I aux
-field to the cloned fid.
-.PP
-.I Clunk
-clunks
-.IR f .
-It usually releases data kept in the
-.I aux
-field, but may be
-set to
-.B nil
-otherwise.
-.PP
-.I Open
-prepares the fid
-.I f
-for I/O according to
-.IR mode .
-The open mode in the fid is updated by the library upon return.
-The library checks trivial cases like opening already-open fids.
-The implementation performs most permission checking.
-.PP
-.I Read
-reads up to
-.I count
-bytes into
-.I data
-starting at
-.I offset
-in the file referenced by
-.IR f .
-.I Write
-is the counterpart.
-To read from directories,
-the function
-.I usbdirread
-may be called.
-It returns the return value of
-.I read
-or -1.
-.I usbdirread
-calls
-.I gen
-to iterate through files as needed.
-The
-.B Dirgen
-function will be called with index values of 0
-and up to ask for the first file and following files.
-To read from data already in buffers, the function
-.I usbreadbuf
-may help.
-It must be given the arguments supplied
-by the user, plus the buffer and buffer size.
-.PP
-.I Stat
-must fill
-.I d
-with the directory entry for the file identified by
-.IR q.
-As an aid,
-.I d
-is initialized to fake access and modification times,
-and user and group ids.
-Also, the field
-.B name
-in
-.I d
-is initialized to point to a 40-byte buffer.
-If the file name fits,
-it may be copied directly into
-.B d->name
-without allocating memory for that purpose.
-Otherwise
-.B d->name
-must be initialized to point to static memory.
-.PP
-The function
-.I end
-is called upon termination of the file tree to
-release resources.
-.PP
-Calling
-.I usbfsinit
-starts a file server for
-.I f
-that mounts itself at
-.I mnt
-and posts
-.I srv
-at
-.IR srv (3).
-In most cases, the file system supplied is
-.IR usbdirfs .
-The
-.I flag
-is used for
-.IR mount
-(see
-.IR bind (2)).
-Once
-.I usbdirfs
-is started, calls to
-.IR usbfsadd
-add a file tree implemented by
-.I dfs
-to the root directory of
-.I usbdirfs
-and
-calls to
-.I usbfsdel
-remove that binding (and release resources including
-the reference to the USB device).
-.PP
-Various error strings are declared as an aid.
-The global
-.B usbfsdebug
-may be set to trigger diagnostics and protocol tracing.
-.SH EXAMPLE
-See
-.B /sys/src/cmd/usb/disk
-for an example driver that uses this library.
-Looking at an example is strongly suggested
-to see how reference counts for the USB device
-and the file system are handled.
-.SH SOURCE
-.B /sys/src/cmd/usb/lib
-.SH "SEE ALSO"
-.IR usb (2),
-.IR usb (3),
-.IR usb (4),
-.IR usbd (4)