The Venus kernel interface: The interface at the call level

Next Previous Contents

## 4. The interface at the call level

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.

## 4.1 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 */
    };

## 4.2 The pioctl interface

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

## 4.3 root

Arguments

in

  empty

out

              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

## 4.4 lookup

Summary Find the ViceFid and type of an object in a directory if it exists.

Arguments

in

              struct  cfs_lookup_in {
                  ViceFid     VFid;
                  char        *name;          /* Place holder for data. */
              } cfs_lookup;

out

              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

## 4.5 getattr

Summary Get the attributes of a file.

Arguments

in

              struct cfs_getattr_in {
                  ViceFid VFid;
                  struct coda_vattr attr; /* XXXXX */
              } cfs_getattr;

out

              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

## 4.6 setattr

Summary Set the attributes of a file.

Arguments

in

              struct cfs_setattr_in {
                  ViceFid VFid;
                  struct coda_vattr attr;
              } cfs_setattr;

out

  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

## 4.7 access

Summary

Arguments

in

              struct cfs_access_in {
                  ViceFid     VFid;
                  int flags;
              } cfs_access;

out

  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

## 4.8 create

Summary Invoked to create a file

Arguments

in

              struct cfs_create_in {
                  ViceFid VFid;
                  struct coda_vattr attr;
                  int excl;
                  int mode;
                  char        *name;          /* Place holder for data. */
              } cfs_create;

out

              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

## 4.9 mkdir

Summary Create a new directory.

Arguments

in

              struct cfs_mkdir_in {
                  ViceFid     VFid;
                  struct coda_vattr attr;
                  char        *name;          /* Place holder for data. */
              } cfs_mkdir;

out

              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

## 4.10 link

Summary Create a link to an existing file.

Arguments

in

              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;

out

  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

## 4.11 symlink

Summary create a symbolic link

Arguments

in

              struct cfs_symlink_in {
                  ViceFid     VFid;          /* Directory to put symlink in */
                  char        *srcname;
                  struct coda_vattr attr;
                  char        *tname;
              } cfs_symlink;

out

  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

## 4.12 remove

Summary Remove a file

Arguments

in

              struct cfs_remove_in {
                  ViceFid     VFid;
                  char        *name;          /* Place holder for data. */
              } cfs_remove;

out

  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

## 4.13 rmdir

Summary Remove a directory

Arguments

in

              struct cfs_rmdir_in {
                  ViceFid     VFid;
                  char        *name;          /* Place holder for data. */
              } cfs_rmdir;

out

  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

## 4.14 readlink

Summary Read the value of a symbolic link.

Arguments

in

              struct cfs_readlink_in {
                  ViceFid VFid;
              } cfs_readlink;

out

              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

## 4.15 open

Summary Open a file.

Arguments

in

              struct cfs_open_in {
                  ViceFid     VFid;
                  int flags;
              } cfs_open;

out

              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

## 4.16 close

Summary Close a file, update it on the servers.

Arguments

in

              struct cfs_close_in {
                  ViceFid     VFid;
                  int flags;
              } cfs_close;

out

  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

## 4.17 ioctl

Summary Do an ioctl on a file. This includes the piocl interface.

Arguments

in

              struct cfs_ioctl_in {
                  ViceFid VFid;
                  int cmd;
                  int len;
                  int rwflag;
                  char *data;                 /* Place holder for data. */
              } cfs_ioctl;

out

              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

## 4.18 rename

Summary Rename a fid.

Arguments

in

              struct cfs_rename_in {
                  ViceFid     sourceFid;
                  char        *srcname;
                  ViceFid destFid;
                  char        *destname;
              } cfs_rename;

out

  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

## 4.19 readdir

Summary Read directory entries.

Arguments

in

              struct cfs_readdir_in {
                  ViceFid     VFid;
                  int count;
                  int offset;
              } cfs_readdir;

out

              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

## 4.20 vget

Summary instructs Venus to do an `FSDB->Get`.

Arguments

in

              struct cfs_vget_in {
                  ViceFid VFid;
              } cfs_vget;

out

              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

## 4.21 fsync

Summary Tell Venus to update the RVM attributes of a file.

Arguments

in

              struct cfs_fsync_in {
                  ViceFid VFid;
              } cfs_fsync;

out

  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

## 4.22 inactive

Summary Tell Venus a vnode is no longer in use.

Arguments

in

              struct cfs_inactive_in {
                  ViceFid VFid;
              } cfs_inactive;

out

  none

Description This operation returns `EOPNOTSUPP`.

Errors

NOTE This should perhaps be removed.

\newpage

## 4.23 rdwr

Summary Read or write from a file

Arguments

in

              struct cfs_rdwr_in {
                  ViceFid     VFid;
                  int rwflag;
                  int count;
                  int offset;
                  int ioflag;
                  caddr_t     data;           /* Place holder for data. */
              } cfs_rdwr;

out

              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

## 4.24 odymount

Summary Allows mounting multiple Coda "filesystems" on one Unix mount point.

Arguments

in

              struct ody_mount_in {
                  char        *name;          /* Place holder for data. */
              } ody_mount;

out

              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

## 4.25 ody_lookup

Summary Looks up something.

Arguments

in

  irrelevant

out

  irrelevant

Description

Errors

NOTE Gut it. Call is not implemented by Venus.

\newpage

## 4.26 ody_expand

Summary expands something in a dynamic set.

Arguments

in

  irrelevant

out

  irrelevant

Description

Errors

NOTE Gut it. Call is not implemented by Venus.

\newpage

## 4.27 prefetch

Summary Prefetch a dynamic set.

Arguments

in

  Not documented.

out

  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

## 4.28 signal

Summary Send Venus a signal about an upcall.

Arguments

in

  none

out

  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

Next Previous Contents