USBFS(2) 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,
Page 1 Plan 9 (printed 12/22/24)
USBFS(2) USBFS(2)
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 implement-
ing a file server within a USB driver. Drivers using this
library may be embedded into usbd(4). It may be also desir-
able to use this library when drivers are not embedded
because it is tailored to work well with the library 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 direc-
tory 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 assigns 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 Usbfs.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 functions to quickly locate the device
of interest, and also permits releasing 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 implemented (and their corre-
sponding fields in Usbfs may never be nil). These functions
Page 2 Plan 9 (printed 12/22/24)
USBFS(2) USBFS(2)
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 supplied 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 update 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 performs 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 arguments supplied by the user, plus the buffer
and buffer size.
Stat must fill d with the directory entry for the file iden-
tified 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
Page 3 Plan 9 (printed 12/22/24)
USBFS(2) USBFS(2)
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)
Page 4 Plan 9 (printed 12/22/24)