glenda.party
term% ls -F
term% cat index.txt
USBFS(2)                      System Calls Manual                     USBFS(2)



NAME
       usbreadbuf,  usbfsadd, usbfsdel, usbdirread, usbfsinit, usbdirfs, usbfs
       - USB device driver file system library

SYNOPSIS
       #include <u.h>
       #include <libc.h>
       #include <thread.h>
       #include "../lib/usb.h"
       #include "../lib/usbfs.h"
       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 */
       };
       struct Fid {
               int     fid;
               Qid     qid;
               int     omode;
               Fid*    next;
               void*   aux;
       };
       struct Usbfs {
               char    name[Namesz];
               uvlong  qid;
               Dev*    dev;
               void*   aux;
               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);
       };
       typedef int (*Dirgen)(Usbfs*, Qid, int, Dir*, void*);
       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);
       extern char Enotfound[], Etoosmall[], Eio[], Eperm[], Ebadcall[],
               Ebadfid[], Einuse[], Eisopen[], Ebadctl[];
       extern Usbfs usbdirfs;
       extern int usbfsdebug;

DESCRIPTION
       This library provides an alternative to 9p(2) for implementing  a  file
       server within a USB driver.  Drivers using this library may be embedded
       into usbd(4).  It may be also desirable to use this library when  driv‐
       ers  are  not embedded because it is tailored to work well with the li‐
       brary for handling USB devices.

       A USB file system is described by a 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 usbdirfs
       file system implemented by the library.  This root directory  is  bound
       to /dev in most cases.

       Usbdirfs  implements  a  root  directory populated by named file trees,
       each one described by a Usbfs structure.

       The field Usbfs.name contains the name for the root  directory  of  the
       file  system,  usually a directory seen at /dev/name when the driver is
       embedded.

       Usbfs.qid maintains a value used to decorate qids for  the  file  tree.
       This may be ignored when usbdirfs is not used.  Otherwise, usbdirfs as‐
       signs a unique value kept at the high 32 bits of Qid.path for all files
       on  each  file tree bound to it.  Each Usbfs server must bitwise OR Us‐
       bfs.qid to all Qid.path values returned by its functions.  In the  same
       way,  functions  usually  clear  bits  in  Usbfs.qid  before processing
       Qid.path values supplied as input.

       The USB device handled by a file tree is referenced from Usbfs.dev (and
       a  reference must be counted for it).  This permits the following func‐
       tions to quickly locate the device of interest, and  also  permits  re‐
       leasing the device when no request is outstanding.

       The  field  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 walk, open, read, write, and stat, must be imple‐
       mented (and their corresponding fields in  Usbfs  may  never  be  nil).
       These functions must return -1 upon failure and set the error string to
       reflect the cause of a failure.

       In all the functions, a 9P fid is represented by a Fid  structure.   It
       contains  the  9P  fid, the corresponding qid, and an auxiliary pointer
       for the driver to use.  Open fids have a valid open mode in omode while
       others  have  ONONE  to indicate that the fid is not open.  The library
       takes care of which fids exist and which ones do not.

       Walk must walk f to name (a single name, not a file path) in  the  sup‐
       plied fs.  Its implementation should update the qid in f to reflect the
       walk.  This function must bitwise OR any returned Qid with Usbfs.qid  ,
       if usbdirfs is used.

       Clone must clone fid of onto nf so that, upon successful completion, nf
       also refers to the file that f refers to.  An implementation  must  up‐
       date  the Qid of the cloned fid.  If this function is not supplied, the
       library copies the aux field to the cloned fid.

       Clunk clunks f.  It usually releases data kept in the  aux  field,  but
       may be set to nil otherwise.

       Open  prepares  the  fid f for I/O according to 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 per‐
       forms most permission checking.

       Read reads up to count bytes into data starting at offset in  the  file
       referenced  by f.  Write is the counterpart.  To read from directories,
       the function usbdirread may be called.  It returns the return value  of
       read  or  -1.  usbdirread calls gen to iterate through files as needed.
       The 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 usbreadbuf may help.  It must be given the  argu‐
       ments supplied by the user, plus the buffer and buffer size.

       Stat must fill d with the directory entry for the file identified by q.
       As an aid, d is initialized to fake access and modification times,  and
       user  and group ids.  Also, the field name in d is initialized to point
       to a 40-byte buffer.  If the file name fits, it may be copied  directly
       into  d->name  without  allocating  memory for that purpose.  Otherwise
       d->name must be initialized to point to static memory.

       The function end is called upon termination of the file tree to release
       resources.

       Calling  usbfsinit starts a file server for f that mounts itself at mnt
       and posts srv at srv(3).  In most cases, the file  system  supplied  is
       usbdirfs.   The flag is used for mount (see bind(2)).  Once usbdirfs is
       started, calls to usbfsadd add a file tree implemented by  dfs  to  the
       root  directory  of  usbdirfs and calls to usbfsdel remove that binding
       (and release resources including the reference to the USB device).

       Various error strings are declared as an aid.   The  global  usbfsdebug
       may be set to trigger diagnostics and protocol tracing.

EXAMPLE
       See /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.

SOURCE
       /sys/src/cmd/usb/lib

SEE ALSO
       usb(2), usb(3), usb(4), usbd(4)



                                                                      USBFS(2)