Return to fusd.h CVS log

Jump to this file's LXR Page

Up to [CENS] / emstar / fusd

first version of all files

/*
 * FUSD: the Framework for User-Space Devices
 *
 * Public header function for user-space library.  This is the API
 * that user-space device drivers should write to.
 */

#include <sys/types.h>

/* FUSD_NOREPLY is a special error code.  If a user-space driver 
 * implementing a system call returns FUSD_NOREPLY, the calling 
 * application will be blocked.  When conditions enable a response
 * to the system call (e.g. the read or write has completed), the
 * user-space driver must call the fusd_return() function.     */
#define FUSD_NOREPLY  400

/* FUSD defines several bitmasks for describing which channels of  
 * notification are being requested or signaled.  These flags are
 * used in the arguments and return value of the notify() callback. */
#define FUSD_NOTIFY_INPUT   0x1
#define FUSD_NOTIFY_OUTPUT  0x2
#define FUSD_NOTIFY_EXCEPT  0x4

struct fusd_file_info; /* forward decl */

/* our current (embryonic) fusd_file_operations supports 4 operations:
 * open, close, read and write.  first argument to all of them is a
 * fusd_file_info structure that lets you manage state between calls
 * (defined below). 
 * 
 *  notify() is called when the application requests to be notified
 *           when the file status changes (i.e. the driver side of select()).
 *           If the file is not ready, the user-space driver must block
 *           until it is.  notify() returns the flags that are ready.
 *
 *  unblock() is called when the application holding a file goes away 
 *           but pending system calls are still blocked.  If blocked, 
 *           the user-space driver must call fusd_return() (typically
 *           with the error code EINTR) and clean up any extant state.
 *
 */
struct fusd_file_operations {
  int (*open) (struct fusd_file_info *file);
  int (*close) (struct fusd_file_info *file);
  ssize_t (*read) (struct fusd_file_info *file, char *buffer, size_t length,
		   loff_t *offset);
  ssize_t (*write) (struct fusd_file_info *file, const char *buffer,
		    size_t length, loff_t *offset);
  int (*ioctl) (struct fusd_file_info *file, int request, ssize_t len, void *data);
  int (*notify) (struct fusd_file_info *file, int flags);
  int (*unblock) (struct fusd_file_info *file);  
};


/* state-keeping structure passed to device driver callbacks */
struct fusd_file_info {
  void *device_info;		/* This is set by the library to
				 * whatever you passed to
				 * fusd_register.  Changing this in a
				 * file_operations callback has no
				 * effect. */

  void *private_data;		/* File-specific data you can change
				 * in a file_operations callback.
				 * e.g., you can set this in an open()
				 * callback, then get it in a
				 * corresponding read() callback. */

  unsigned int flags;		/* Kept synced with file->f_flags */
  pid_t pid;			/* PID of process making the request */

  /* other info might be added later, e.g. state needed to complete
     operations... */
};


/*************************** Library Functions ****************************/

/* fusd_register: create a device file and register callbacks for it
 *
 * Arguments:
 *
 *    name - the name of the device file, to be created wherever devfs
 *    is mounted (usually dev).  example: pass "mydevice" will create
 *    /dev/mydevice.
 *
 *    mode - the file protections to be given to the device
 *
 *    device_info - you can provide arbitrary data that will later be
 *    passed back to your driver's callbacks in file->device_info.
 *    value has no effect on FUSD itself.
 *
 *    fops - a table of callbacks to be called for this device; see
 *    structure above.
 *
 * Return value:
 *    On failure, -1 is returned and errno is set to indicate the error.
 *
 *    On success, a valid file descriptor is returned which represents
 *    the control channel to your new device.  You should never read
 *    from or write to that control channel directcly, but you can
 *    select on it to see when it needs attention (see fusd_run and
 *    fusd_dispatch).
 */

int fusd_register(char *name, mode_t mode, void *device_info,
		  struct fusd_file_operations *fops);


/* fusd_unregister: unregister a previously registered device
 *
 * Arguments:
 *    fd - the file descriptor previously returned to you by fusd_register.
 *
 * Return value:
 *    0 on success.
 *   -1 on failure with errno set to indicate the failure.
 */
int fusd_unregister(int fd);


/* fusd_return: unblock a previously blocked system call
 * 
 * Arguments:
 *   file - the file info struct that was previously blocked
 *   retval - the return value that would have been returned by the
 *            returning system call
 *    
 * Return value:
 *   0 on success.
 *  -1 on failure with errno set to indicate the failure
 */
int fusd_return(struct fusd_file_info *file, ssize_t retval);


/* fusd_dispatch: handles an event on a fusd file descriptor
 * 
 * Arguments:
 *   fd - the file descriptor of the device that received an event
 *    
 * Return value:
 *   0 on success.
 *  -1 on failure with errno set to indicate the failure
 */
int fusd_dispatch(int fd);