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 {
struct Fid {
struct Usbfs {
typedef int (*Dirgen)(Usbfs*, Qid, int, Dir*, void*); long usbreadbuf(void *data, long count,
void usbfsdel(Usbfs *dfs); int usbdirread(Usbfs*f, Qid q, char *data, long cnt,
void usbfsdirdump(void); extern char Enotfound[], Etoosmall[], Eio[], Eperm[], Ebadcall[],
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 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 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 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 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 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 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) |