Subversion Repositories planix.SVN

.TH USBFS 2

.SH NAME

usbreadbuf,

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.3v

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 */

};

.sp 0.3v

struct Fid {

	int	fid;

	Qid	qid;

	int	omode;

	Fid*	next;

	void*	aux;

};

.sp 0.3v

struct 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.3v

typedef int (*Dirgen)(Usbfs*, Qid, int, Dir*, void*);

.sp 0.3v

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);

.sp 0.3v

extern char Enotfound[], Etoosmall[], Eio[], Eperm[], Ebadcall[],

	Ebadfid[], Einuse[], Eisopen[], Ebadctl[];

.sp 0.3v

extern Usbfs usbdirfs;

extern int usbfsdebug;

.EE

.SH DESCRIPTION

This library provides an alternative to

.IR 9p (2)

for implementing a file server within a USB driver.

Drivers using this

library may be embedded into

.IR 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.

.PP

A USB file system is described by a

.I 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

.I usbdirfs

file system implemented by the library.

This root directory is bound to

.B /dev

in most cases.

.PP

.I Usbdirfs

implements a root directory populated by named file trees,

each one described by a

.B Usbfs

structure.

.PP

The field

.B Usbfs.name

contains the name for the root directory of the file system, usually

a directory seen at

.BI /dev/ name

when the driver is embedded.

.PP

.B Usbfs.qid

maintains a value used to decorate qids for the file tree.

This may be ignored when

.I usbdirfs

is not used.

Otherwise,

.I usbdirfs

assigns a unique value kept at the high 32 bits of

.B Qid.path

for all files on each file tree bound to it.

Each

.I Usbfs

server must bitwise OR

.B Usbfs.qid

to all

.B Qid.path

values returned by its functions.

In the same way,

functions usually clear bits in

.B Usbfs.qid

before processing

.B Qid.path

values supplied as input.

.PP

The 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 of

interest, and also permits releasing the device when

no request is outstanding.

.PP

The field

.B 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

.IR walk ,

.IR open ,

.IR read ,

.IR write ,

and

.IR stat ,

must be implemented (and their corresponding fields in

.B Usbfs

may never be

.BR nil ).

These functions must return -1 upon failure

and set the error string to reflect the cause of a failure.

.PP

In all the functions, a 9P fid is represented by a

.B Fid

structure.

It contains the 9P

.IR fid ,

the corresponding

.IR qid ,

and an auxiliary pointer for the driver to use.

Open

.IR fid s

have a valid open mode in

.I omode

while others have

.B ONONE

to indicate that the

.I fid

is not open.

The library takes care of which

fids

exist and which ones do not.

.PP

.I Walk

must walk

.I f

to

.I name

(a single name, not a file path)

in the supplied

.IR fs .

Its implementation should update the qid in

.I f

to reflect the walk.

This function must bitwise OR any returned Qid with

.B Usbfs.qid ,

if

.I usbdirfs

is used.

.PP

.I Clone

must clone fid

.I of

onto

.I nf

so that,

upon successful completion,

.I nf

also refers to the file that

.I f

refers to.

An implementation must update the Qid of the cloned

fid.

If this function is not supplied, the library copies the

.I aux

field to the cloned fid.

.PP

.I Clunk

clunks

.IR f .

It usually releases data kept in the

.I aux

field, but may be

set to

.B nil

otherwise.

.PP

.I Open

prepares the fid

.I f

for 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 Read

reads up to

.I count

bytes into

.I data

starting at

.I offset

in the file referenced by

.IR f .

.I Write

is the counterpart.

To read from directories,

the function

.I usbdirread

may be called.

It returns the return value of

.I read

or -1.

.I usbdirread

calls

.I gen

to iterate through files as needed.

The

.B 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

.I usbreadbuf

may help.

It must be given the arguments supplied

by the user, plus the buffer and buffer size.

.PP

.I Stat

must fill

.I d

with the directory entry for the file identified by

.IR q.

As an aid,

.I d

is initialized to fake access and modification times,

and user and group ids.

Also, the field

.B name

in

.I d

is initialized to point to a 40-byte buffer.

If the file name fits,

it may be copied directly into

.B d->name

without allocating memory for that purpose.

Otherwise

.B d->name

must be initialized to point to static memory.

.PP

The function

.I end

is called upon termination of the file tree to

release resources.

.PP

Calling

.I usbfsinit

starts a file server for

.I f

that mounts itself at

.I mnt

and posts

.I srv

at

.IR srv (3).

In most cases, the file system supplied is

.IR usbdirfs .

The

.I flag

is used for

.IR mount

(see

.IR bind (2)).

Once

.I usbdirfs

is started, calls to

.IR usbfsadd

add a file tree implemented by

.I dfs

to the root directory of

.I usbdirfs

and

calls to

.I usbfsdel

remove that binding (and release resources including

the reference to the USB device).

.PP

Various error strings are declared as an aid.

The global

.B usbfsdebug

may be set to trigger diagnostics and protocol tracing.

.SH EXAMPLE

See

.B /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.

.SH SOURCE

.B /sys/src/cmd/usb/lib

.SH "SEE ALSO"

.IR usb (2),

.IR usb (3),

.IR usb (4),

.IR usbd (4)