This section describes the upcalls a Coda FS driver can make to Venus.
Each of these upcalls make use of three structures: inputArgs
for communication from kernel to Venus, and
outputArgs
back from Venus to the kernel and finally downcalls
which are calls from Venus to the kernel initiated by Venus.
union inputArgs { struct cfs_in_hdr ih; /* NB: every struct below begins with an ih */ struct cfs_open_in cfs_open; struct cfs_close_in cfs_close; struct cfs_ioctl_in cfs_ioctl; struct cfs_getattr_in cfs_getattr; struct cfs_setattr_in cfs_setattr; struct cfs_access_in cfs_access; struct cfs_lookup_in cfs_lookup; struct cfs_create_in cfs_create; struct cfs_remove_in cfs_remove; struct cfs_link_in cfs_link; struct cfs_rename_in cfs_rename; struct cfs_mkdir_in cfs_mkdir; struct cfs_rmdir_in cfs_rmdir; struct cfs_readdir_in cfs_readdir; struct cfs_symlink_in cfs_symlink; struct cfs_readlink_in cfs_readlink; struct cfs_fsync_in cfs_fsync; struct cfs_inactive_in cfs_inactive; struct cfs_vget_in cfs_vget; struct cfs_rdwr_in cfs_rdwr; struct cfs_open_by_path_in cfs_open_by_path; };
union outputArgs { struct cfs_out_hdr oh; /* NB: every struct below begins with an oh */ struct cfs_root_out cfs_root; struct cfs_open_out cfs_open; struct cfs_ioctl_out cfs_ioctl; struct cfs_getattr_out cfs_getattr; struct cfs_lookup_out cfs_lookup; struct cfs_create_out cfs_create; struct cfs_mkdir_out cfs_mkdir; struct cfs_readdir_out cfs_readdir; struct cfs_readlink_out cfs_readlink; struct cfs_vget_out cfs_vget; struct cfs_purgeuser_out cfs_purgeuser; struct cfs_zapfile_out cfs_zapfile; struct cfs_zapdir_out cfs_zapdir; struct cfs_zapvnode_out cfs_zapvnode; struct cfs_purgefid_out cfs_purgefid; struct cfs_rdwr_out cfs_rdwr; struct cfs_replace_out cfs_replace; struct cfs_open_by_path_out cfs_open_by_path; };
union cfs_downcalls { /* CFS_FLUSH is also a down call */ struct cfs_purgeuser_out purgeuser; struct cfs_zapfile_out zapfile; struct cfs_zapdir_out zapdir; struct cfs_zapvnode_out zapvnode; struct cfs_purgefid_out purgefid; struct cfs_replace_out replace; };
The headers are common to all calls and contain process, authentication and opcode information:
struct cfs_in_hdr { unsigned long opcode; unsigned long unique; /* Keep multiple outstanding msgs distinct */ u_short pid; /* Common to all */ u_short pgid; /* Common to all */ u_short sid; /* to become the PAG */ struct coda_cred cred; /* to become a PAG */ }; /* Really important that opcode and unique are 1st two fields! */ struct cfs_out_hdr { unsigned long opcode; unsigned long unique; unsigned long result; };
Before going on let us elucidate the role of the various fields. The
inputArgs start with the opcode
which defines the type of service
requested from Venus. There are approximately 30 upcalls at present
which we will discuss. The unique
field labels the inputArg
with unique number which will identify the message uniquely. A
process and process group id are passed. Finally the credentials of
the caller are included.
Before delving into the specific calls we need to discuss a variety of data structures shared by the kernel and Venus.
The CodaCred
structure defines a variety of user and group id's as
they are set for the calling process. The vuid_t
and guid_t
are 32 bit unsigned integers. It also defines group member
ship in an array. On Unix the CodaCred has proven sufficient to
implement good security semantics for Coda but the structure may have
to undergo modification for the Windows environment when these mature.
struct CodaCred { vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, efftve, set, fs uid*/ vgid_t cr_gid, cr_egid, cr_sgid, cr_fsgid; /* same for groups */ vgid_t cr_groups[NGROUPS]; /* Group membership for caller */ };
NOTE It is questionable if we need CodaCreds in Venus. Finally Venus doesn't know about groups, although it does create files with the default uid/gid. Perhaps the list of group membership is superfluous.
The next item is the fundamental identifier used to identify Coda
files, the ViceFid
. A fid of a file uniquely defines a file or
directory in the Coda filesystem within a cell.
A cell is a group of Coda servers acting under the aegis of a single system control machine or SCM. See the Coda Administration manual for a detailed description of the role of the SCM.
typedef struct ViceFid { VolumeId Volume; VnodeId Vnode; Unique_t Unique; } ViceFid;
Each of the constituent fields: VolumeId, VnodeId
and
Unique_t
are unsigned 32 bit integers. We envisage that a
further field will need to be prefixed to identify the Coda cell; this
will probably take the form of a Ipv6 size IP address naming the Coda
cell through DNS.
The next important structure shared between Venus and the kernel are the attributes of the file. The following structure is used to exchange information. It has room for future extensions such as support for device files (currently not present in Coda).
struct coda_vattr { enum coda_vtype va_type; /* vnode type (for create) */ u_short va_mode; /* files access mode and type */ short va_nlink; /* number of references to file */ vuid_t va_uid; /* owner user id */ vgid_t va_gid; /* owner group id */ long va_fsid; /* file system id (dev for now) */ long va_fileid; /* file id */ u_quad_t va_size; /* file size in bytes */ long va_blocksize; /* blocksize preferred for i/o */ struct timespec va_atime; /* time of last access */ struct timespec va_mtime; /* time of last modification */ struct timespec va_ctime; /* time file changed */ u_long va_gen; /* generation number of file */ u_long va_flags; /* flags defined for file */ dev_t va_rdev; /* device special file represents */ u_quad_t va_bytes; /* bytes of disk space held by file */ u_quad_t va_filerev; /* file modification number */ u_int va_vaflags; /* operations flags, see below */ long va_spare; /* remain quad aligned */ };
Coda specific requests can be made by application through the pioctl
interface. The pioctl is implemented as an ordinary ioctl on a
ficticious file /coda/.CONTROL
. The piocl call opens this
file, gets a file handle and makes the ioctl call. Finally it closes
the file.
The kernel involvement in this is limited to providing the facility to open and close and pass the ioctl message and to verify that a path in the pioctl data buffers is a file in a Coda filesystem.
The kernel is handed a data packet of the form:
struct { const char *path; struct ViceIoctl vidata; int follow; } data;
where
struct ViceIoctl { caddr_t in, out; /* Data to be transferred in, or out */ short in_size; /* Size of input buffer <= 2K */ short out_size; /* Maximum size of output buffer, <= 2K */ };
The path
must be a Coda file, otherwise the ioctl
upcall
will not be made.
NOTE The data structures and code are a mess. We need to clean this up.
We now proceed to document the individual calls:
\newpage
Arguments
empty
struct cfs_root_out { ViceFid VFid; } cfs_root;
Description This call is made to Venus during the initialization
of the Coda filesystem. If the result
is zero, the cfs_root
structure contains the ViceFid of the root of the Coda filesystem. If
a non-zero result is generated, its value is a platform dependent
error code indicating the difficulty Venus encountered in locating the
root of the Coda filesystem.
\newpage
Summary Find the ViceFid and type of an object in a directory if it exists.
Arguments
struct cfs_lookup_in { ViceFid VFid; char *name; /* Place holder for data. */ } cfs_lookup;
struct cfs_lookup_out { ViceFid VFid; int vtype; } cfs_lookup;
Description This call is made to determine the ViceFid and
filetype of a directory entry. The directory entry requested carries
name name
and Venus will search the directory identified by
cfs_lookup_in.VFid
. The result
may indicate that the name
does not exist, or that difficulty was encountered in finding it
(e.g. due to disconnection). If the result
is zero, the field
cfs_lookup_out.VFid
contains the targets ViceFid and
cfs_lookup_out.vtype
the coda_vtype
giving the type of
object the name designates.
The name of the object is an 8 bit character string of maximum length CFS_MAXNAMLEN, currently set to 256 (including a 0 terminator.)
It is extremely important to realize that Venus bitwise or's the field
cfs_lookup.vtype
with CFS_NOCACHE
to indicate that the
object should not be put in the kernel name cache. Files in conflict or
uncovered mountpoints should never be cached by the kernel and each lookup
should make it to Venus.
NOTE The type of the vtype is currently wrong. It should be
coda_vtype
. Linux does not take note of CFS_NOCACHE
. It
should.
\newpage
Summary Get the attributes of a file.
Arguments
struct cfs_getattr_in { ViceFid VFid; struct coda_vattr attr; /* XXXXX */ } cfs_getattr;
struct cfs_getattr_out { struct coda_vattr attr; } cfs_getattr;
Description This call returns the attributes of the file identified by fid.
Errors Errors can occur if the object with fid does not exist, are unaccessible or if the caller does not have permission to fetch attributes.
Note Many kernel FS drivers (Linux, NT and Windows 95 need to acquire the attributes as well as the Fid for the instantiation of an internal "inode" or "FileHandle". A significant improvement in performance on such systems could be made by combining the lookup and getattr calls both at the Venus/kernel interaction level and at the RPC level.
The vattr
structure included in the input arguments is
superfluous and should be removed.
\newpage
Summary Set the attributes of a file.
Arguments
struct cfs_setattr_in { ViceFid VFid; struct coda_vattr attr; } cfs_setattr;
empty
Description The structure attr
is filled with attributes to
be changed in BSD style. Attributes not to be changed are set to -1,
apart from vtype
which is set to VNON
. Other are set to the
value to be assigned. The only attributes which the FS driver may
request to change are the mode, ownner, groupid, atime, mtime and
ctime. The return value indicates success or failure.
Errors A variety of errors can occur. The object may not exist, may be inaccessible, or permission may not be granted by Venus.
\newpage
Summary
Arguments
struct cfs_access_in { ViceFid VFid; int flags; } cfs_access;
empty
Description Verify if access to the object identified by VFid
for
operations described by flags
is permitted. The result indicates
if access will be granted. It is important to remember that Coda uses
ACL's to enforce protection and that ultimately the servers, not the
clients enforce the security of the system. The result of this call
will depend on wether a token is held by the user.
Errors The object may not exist, or the ACL describing the protection may not be accessible.
\newpage
Summary Invoked to create a file
Arguments
struct cfs_create_in { ViceFid VFid; struct coda_vattr attr; int excl; int mode; char *name; /* Place holder for data. */ } cfs_create;
struct cfs_create_out { ViceFid VFid; struct coda_vattr attr; } cfs_create;
Description This upcall is invoked to request creation of a
file. The file will be created in the directory identified by
VFid
, its name will be name
, and the mode will be
mode
. If excl
is set an error will be returned if the file
already exists. If the size field in attr is set to zero the file
will be truncated. The uid and gid of the file are set by converting
the CodaCred to a uid using a macro CRTOUID
(this macro is
platform dependent). Upon success the VFid and attributes of the file
are returned. The Coda FS Driver will normally instantiate a vnode,
inode or filehandle at kernel level for the new object.
Errors A variety of errors can occur. Permissions may be
insufficient. If the object exists and is not a file the error
EISDIR
is returned under Unix.
NOTE The packing of parameters is very inefficient and appears to
indicate confusion between the system call creat and the VFS operation
create. The VFS operation create is only called to create new
objects. This create call differs from the Unix one in that it is not
invoked to return a file descriptor. The trunctate and exclusive
options, together with the mode, could simply be part of the mode as
it is under Unix. There should be no flags argument; this is used in
open
(2) to return a filedescriptor for READ or WRITE mode.
The attributes of the directory should be returned too, since the size and mtime changed.
\newpage
Summary Create a new directory.
Arguments
struct cfs_mkdir_in { ViceFid VFid; struct coda_vattr attr; char *name; /* Place holder for data. */ } cfs_mkdir;
struct cfs_mkdir_out { ViceFid VFid; struct coda_vattr attr; } cfs_mkdir;
Description This call is similar to create
but creates a
directory. Only the mode
field in the input parameters is used
for creation. Upon successful creation, the attr
returned
contains the attributes of the new directory.
Errors As for create.
NOTE The input parameter should be changed to mode
instead
of attributes.
The attributes of the parent should be returned since the size and mtime changes.
\newpage
Summary Create a link to an existing file.
Arguments
struct cfs_link_in { ViceFid sourceFid; /* cnode to link *to* */ ViceFid destFid; /* Directory in which to place link */ char *tname; /* Place holder for data. */ } cfs_link;
empty
Description This call creates a link to the sourceFid
in the
directory identified by destFid
with name tname
. The source
must reside in the targets parent, i.e. the source must be have parent
destFid
, i.e. Coda does not support cross directory hard links.
Only the return value is relevant. It indicates success or the type
of failure.
Errors The usual errors can occur.\newpage
Summary create a symbolic link
Arguments
struct cfs_symlink_in { ViceFid VFid; /* Directory to put symlink in */ char *srcname; struct coda_vattr attr; char *tname; } cfs_symlink;
none
Description Create a symbolic link. The link is to be placed in
the directory identified by VFid
and named tname
. It should
point to the pathname srcname
. The attributes of the newly
created object are to be set to attr
.
Errors
NOTE The attributes of the target directory should be returned since its size changed.
\newpage
Summary Remove a file
Arguments
struct cfs_remove_in { ViceFid VFid; char *name; /* Place holder for data. */ } cfs_remove;
none
Description Remove file named cfs_remove_in.name
in
directory identified by VFid
.
Errors
NOTE The attributes of the directory should be returned since its mtime and size may change.
\newpage
Summary Remove a directory
Arguments
struct cfs_rmdir_in { ViceFid VFid; char *name; /* Place holder for data. */ } cfs_rmdir;
none
Description Remove the directory with name name
from the
directory identified by VFid
.
Errors
NOTE The attributes of the parent directory should be returned since its mtime and size may change.
\newpage
Summary Read the value of a symbolic link.
Arguments
struct cfs_readlink_in { ViceFid VFid; } cfs_readlink;
struct cfs_readlink_out { int count; caddr_t data; /* Place holder for data. */ } cfs_readlink;
Description This routine reads the contents of symbolic link
identified by VFid
into the buffer data
. The buffer
data
must be able to hold any name up to CFS_MAXNAMLEN
(PATH or
NAM??).
Errors No unusual errors.
\newpage
Summary Open a file.
Arguments
struct cfs_open_in { ViceFid VFid; int flags; } cfs_open;
struct cfs_open_out { dev_t dev; ino_t inode; } cfs_open;
Description This request asks Venus to place the file identified
by VFid
in its cache and to note that the calling process wishes
to open it with flags
as in open(2)
. The return value to
the kernel differs for Unix and Windows systems. For Unix systems the
Coda FS Driver is informed of the device and inode number of the
container file in the fields dev
and inode
. For Windows the
path of the container file is returned to the kernel.
Errors
NOTE Currently the cfs_open_out
structure is not properly
adapted to deal with the windows case. It might be best to implement
two upcalls, one to open aiming at a container file name, the other at
a container file inode.
\newpage
Summary Close a file, update it on the servers.
Arguments
struct cfs_close_in { ViceFid VFid; int flags; } cfs_close;
none
Description Close the file identified by VFid
.
Errors
NOTE The flags
argument is bogus and not used. However,
Venus' code has room to deal with an execp
input field, probably
this field should be used to inform Venus that the file was closed but
is still memory mapped for execution. There are comments about
fetching versus not fetching the data in Venus vproc_vfscalls
.
This seems silly. If a file is being closed, the data in the
container file is to be the new data. Here again the execp
flag
might be in play to create confusion: presently Venus might think a
file can be flushed from the cache when it is still memory mapped.
This needs to be understood.
\newpage
Summary Do an ioctl on a file. This includes the piocl interface.
Arguments
struct cfs_ioctl_in { ViceFid VFid; int cmd; int len; int rwflag; char *data; /* Place holder for data. */ } cfs_ioctl;
struct cfs_ioctl_out { int len; caddr_t data; /* Place holder for data. */ } cfs_ioctl;
Description Do an ioctl operation on a file. The command,
len
and data
arguments are filled as usual. flags
is not
used by Venus.
Errors
NOTE Another bogus parameter. flags
is not used. What is
the business about PREFETCHING in the Venus' code?
\newpage
Summary Rename a fid.
Arguments
struct cfs_rename_in { ViceFid sourceFid; char *srcname; ViceFid destFid; char *destname; } cfs_rename;
none
Description Rename the object with name srcname
in
directory sourceFid
to destname
in destFid
. It is
important that the names srcname
and destname
are 0
terminated strings. Strings in Unix kernels are not always null
terminated.
Errors
\newpage
Summary Read directory entries.
Arguments
struct cfs_readdir_in { ViceFid VFid; int count; int offset; } cfs_readdir;
struct cfs_readdir_out { int size; caddr_t data; /* Place holder for data. */ } cfs_readdir;
Description Read directory entries from VFid
starting at
offset
and read at most count
bytes. Returns the data
into data
and indicates the size returned size
.
Errors
NOTE This call is not used. Readdir operations exploit container files. We will re-evaluate this during the directory revamp which is about to take place.
\newpage
Summary instructs Venus to do an FSDB->Get
.
Arguments
struct cfs_vget_in { ViceFid VFid; } cfs_vget;
struct cfs_vget_out { ViceFid VFid; int vtype; } cfs_vget;
Description This upcall asks Venus to do a get
operation on
an fsobj
labelled by VFid
.
Errors
NOTE This operation is not used. However, it is extremely useful
since it can be used to deal with read/write memory mapped files.
These can be "pinned" in the Venus cache using vget
and release
with inactive
.
\newpage
Summary Tell Venus to update the RVM attributes of a file.
Arguments
struct cfs_fsync_in { ViceFid VFid; } cfs_fsync;
none
Description Ask Venus to update RVM attributes of object
VFid
. This should be called as part of kernel level fsync
type calls. The result
indicates if the synching was
successful.
Errors
NOTE Linux does not implement this call. It should.
\newpage
Summary Tell Venus a vnode is no longer in use.
Arguments
struct cfs_inactive_in { ViceFid VFid; } cfs_inactive;
none
Description This operation returns EOPNOTSUPP
.
Errors
NOTE This should perhaps be removed.
\newpage
Summary Read or write from a file
Arguments
struct cfs_rdwr_in { ViceFid VFid; int rwflag; int count; int offset; int ioflag; caddr_t data; /* Place holder for data. */ } cfs_rdwr;
struct cfs_rdwr_out { int rwflag; int count; caddr_t data; /* Place holder for data. */ } cfs_rdwr;
Description This upcall asks Venus to read or write from a file.
Errors
NOTE It should be removed since it is against the Coda philosophy that read/write operations never reach Venus. I have been told the operation does not work. It is not currently used.
\newpage
Summary Allows mounting multiple Coda "filesystems" on one Unix mount point.
Arguments
struct ody_mount_in { char *name; /* Place holder for data. */ } ody_mount;
struct ody_mount_out { ViceFid VFid; } ody_mount;
Description Asks Venus to return the rootfid of a Coda system
named name
. The fid is returned in VFid
.
Errors
NOTE This call was used by David for dynamic sets. It should be removed since it causes a jungle of pointers in the VFS mounting area. It is not used by Coda proper. Call is not implemented by Venus.
\newpage
Summary Looks up something.
Arguments
irrelevant
irrelevant
Description
Errors
NOTE Gut it. Call is not implemented by Venus.
\newpage
Summary expands something in a dynamic set.
Arguments
irrelevant
irrelevant
Description
Errors
NOTE Gut it. Call is not implemented by Venus.
\newpage
Summary Prefetch a dynamic set.
Arguments
Not documented.
Not documented.
Description Venus worker.cc has support for this call, although it is noted that it doesn't work. Not surprising, since the kernel does not have support for it. (ODY_PREFETCH is not a defined operation).
Errors
NOTE Gut it. It isn't working and isn't used by Coda.
\newpage
Summary Send Venus a signal about an upcall.
Arguments
none
not applicable.
Description This is an out-of-band upcall to Venus to inform Venus that the calling process received a signal after Venus read the message from the input queue. Venus is supposed to clean up the operation.
Errors No reply is given.
NOTE We need to better understand what Venus needs to clean up and if it is doing this correctly. Also we need to handle multiple upcall per system call situations correctly. It would be important to know what state changes in Venus take place after an upcall for which the kernel is responsible for notifying Venus to clean up (e.g. open definitely is such a state change, but many others are maybe not).
\newpage