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,
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
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 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
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 func‐
tions 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 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
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 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 ALSOusb(2), usb(3), usb(4), usbd(4)USBFS(2)
