(Illustration by Gaich Muramatsu)
(Illustration by Gaich Muramatsu)
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