.TH USBFS 2.SH NAMEusbreadbuf,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.3venum {	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.3vstruct Fid {	int	fid;	Qid	qid;	int	omode;	Fid*	next;	void*	aux;};.sp 0.3vstruct 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.3vtypedef int (*Dirgen)(Usbfs*, Qid, int, Dir*, void*);.sp 0.3vlong	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.3vextern char Enotfound[], Etoosmall[], Eio[], Eperm[], Ebadcall[],	Ebadfid[], Einuse[], Eisopen[], Ebadctl[];.sp 0.3vextern Usbfs usbdirfs;extern int usbfsdebug;.EE.SH DESCRIPTIONThis library provides an alternative to.IR 9p (2)for implementing a file server within a USB driver.Drivers using thislibrary may be embedded into.IR usbd (4).It may be also desirable to use this library when drivers arenot embedded because it is tailored to work well with thelibrary for handling USB devices..PPA USB file system is described by a.I Usbfsstructure.In most cases, the driver is not responsible for the root of thefile tree.It is customary that a driver creates a file serverfor each device handled and links all of them to a root directoryimplemented by the.I usbdirfsfile system implemented by the library.This root directory is bound to.B /devin most cases..PP.I Usbdirfsimplements a root directory populated by named file trees,each one described by a.B Usbfsstructure..PPThe field.B Usbfs.namecontains the name for the root directory of the file system, usuallya directory seen at.BI /dev/ namewhen the driver is embedded..PP.B Usbfs.qidmaintains a value used to decorate qids for the file tree.This may be ignored when.I usbdirfsis not used.Otherwise,.I usbdirfsassigns a unique value kept at the high 32 bits of.B Qid.pathfor all files on each file tree bound to it.Each.I Usbfsserver must bitwise OR.B Usbfs.qidto all.B Qid.pathvalues returned by its functions.In the same way,functions usually clear bits in.B Usbfs.qidbefore processing.B Qid.pathvalues supplied as input..PPThe 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 ofinterest, and also permits releasing the device whenno request is outstanding..PPThe field.B Usbfs.auxis 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 Usbfsmay never be.BR nil ).These functions must return -1 upon failureand set the error string to reflect the cause of a failure..PPIn all the functions, a 9P fid is represented by a.B Fidstructure.It contains the 9P.IR fid ,the corresponding.IR qid ,and an auxiliary pointer for the driver to use.Open.IR fid shave a valid open mode in.I omodewhile others have.B ONONEto indicate that the.I fidis not open.The library takes care of whichfidsexist and which ones do not..PP.I Walkmust walk.I fto.I name(a single name, not a file path)in the supplied.IR fs .Its implementation should update the qid in.I fto reflect the walk.This function must bitwise OR any returned Qid with.B Usbfs.qid ,if.I usbdirfsis used..PP.I Clonemust clone fid.I ofonto.I nfso that,upon successful completion,.I nfalso refers to the file that.I frefers to.An implementation must update the Qid of the clonedfid.If this function is not supplied, the library copies the.I auxfield to the cloned fid..PP.I Clunkclunks.IR f .It usually releases data kept in the.I auxfield, but may beset to.B nilotherwise..PP.I Openprepares the fid.I ffor 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 Readreads up to.I countbytes into.I datastarting at.I offsetin the file referenced by.IR f ..I Writeis the counterpart.To read from directories,the function.I usbdirreadmay be called.It returns the return value of.I reador -1..I usbdirreadcalls.I gento iterate through files as needed.The.B Dirgenfunction will be called with index values of 0and up to ask for the first file and following files.To read from data already in buffers, the function.I usbreadbufmay help.It must be given the arguments suppliedby the user, plus the buffer and buffer size..PP.I Statmust fill.I dwith the directory entry for the file identified by.IR q.As an aid,.I dis initialized to fake access and modification times,and user and group ids.Also, the field.B namein.I dis initialized to point to a 40-byte buffer.If the file name fits,it may be copied directly into.B d->namewithout allocating memory for that purpose.Otherwise.B d->namemust be initialized to point to static memory..PPThe function.I endis called upon termination of the file tree torelease resources..PPCalling.I usbfsinitstarts a file server for.I fthat mounts itself at.I mntand posts.I srvat.IR srv (3).In most cases, the file system supplied is.IR usbdirfs .The.I flagis used for.IR mount(see.IR bind (2)).Once.I usbdirfsis started, calls to.IR usbfsaddadd a file tree implemented by.I dfsto the root directory of.I usbdirfsandcalls to.I usbfsdelremove that binding (and release resources includingthe reference to the USB device)..PPVarious error strings are declared as an aid.The global.B usbfsdebugmay be set to trigger diagnostics and protocol tracing..SH EXAMPLESee.B /sys/src/cmd/usb/diskfor an example driver that uses this library.Looking at an example is strongly suggestedto see how reference counts for the USB deviceand 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)