Parts of Arla
*************

     Caution: This text just tries to give a general picture. For real info read the code. If you have any questions, mail arla-drinkers@stacken.kth.se.

How does arla work
==================

Arla consists of two parts, a userland process (arlad) and the kernel-module (xfs).

Arlad is written in user-space for simpler debugging (and less rebooting). And there is not the same limitations as if it would be written in the kernel. To avoid the performance loss xfs does caching.

xfs and arlad communicate with each other via a char-device-driver. There is a rpc-protocol currenly used specially written for this (arlad/message.c)

xfs is written to be as simple as possible. Theoretically, xfs could be used by other user-space daemons to implement a file system. Some parts, such as syscalls, are arla-specific. These parts are designed to be as general as possible.

For example, xfs does not recognize which pioctl the user-level program calls, it just passes this information on to arlad.

Arlad and XFS relation
======================

     Userland

                                  ---------
                 Edit file        | Arlad |  ------> Network
                                  ---------
                ----------------------|[1]----
                 -------           -------
     Kernel      | VFS | <--[2]--> | XFS |
                 -------           -------

[1] A char device (/dev/xfs0)

[2] Xfs provides a filesystem for the vfs-layer in
     the operating system.

The life of a file
==================

This a rough description of the life of a file. The names are inspired of BSD-style VFS-layer but the idea is the same in most operating systems.

  * The user decides to open a file.

  * The vfslayer sends a VOP_LOOKUP to xfs that is forwarded to arlad with a getnode() (seq-num 1).

  * arlad tries to find the requested file and then, if found, sends an install_node to xfs by writing to the xfs character device.

  * xfs inserts the node into the cache and returns from the device write.

  * arla sends a wakeup rpc message (seq-num 1). If the return value is zero xfs tries to find the node in the cache, if not found it might have been flushed out of the cache and the whole thing is repeated.

  * If a none-zero return value is returned, this value is sent as reply to the user. This way arla can decide what error message is returned, without xfs having support for each error.

  * xfs now checks if it has the valid attributes. If the attributes are invalid, xfs will send a rpc message to arlad to refresh it.

  * Since the user wanted to open the file, a getdata rpc message is sent from xfs to arlad. Now arlad fetches the files from the afs file server.

  * Arlad stores the file in the file cache. All vnode operations will be done on this file. Now arlad sends a installdata to xfs.

  * When xfs recives the installdata it looks up the node in the cache, and then it does a VOP_LOOKUP to find a vnode to the cachefile (and store it to keep it for future use).

  * The same thing is done when the file is a directory, except that the directory is converted from the afs directory format to an operating system dependent format and stored in a file. xfs reads this file instead.

  * If the directory is modified locally, write operations are done on the file obtained from the afs-server, and when done the newly changed file is converted and reinstalled.

  * Now the user wants to read a file.

  * A VOP_READ is sent to the from the vfs-layer to xfs.

  * xfs checks if it has valid attributes/and data (and updates if needed). Now VOP_READ is simply performed on the stored vnode of the cachefile.

Tools and libs
==============

What other tools does the arla suite consists of

libutil - a library for most used modules like hashtable,
     double-linked list, logging functions, date-parsing, etc

rx - the library for the rx protocol (see Rx protocol).

lwp - the library for the lwp thread-package
     (see LWP).

ydr - A stub generator that replaces rxgen.

rxkad - The rx Kerberos authentication package.

lib/roken/ - The library that will unbreak things that
     is missing or broken.

lib/ko - A library of functions that is arlad-core related
     but is also useful for programs like vos, pts, fs, etc.

appl/libarlalib.a - A broken library that does all the hard
     work with connections etc.

appl/fs - The fs util, extra feature: getfid

appl/vos - The vos util

appl/pts - The pts util, extra feature: dump

appl/udebug - Debug your ubik server

     [file tools.texi not included]

The files in arlad/
===================

This is a short describtion of the files to bring new deveplopers up to speed.

The core of arlad
-----------------

adir.c - contain all functions needed to to operations
     on afs-directory file.

afsdir_check.c - check if a afs-directory looks sane.

arla.c - The startup and the standalone (-t) code.

arladeb.c - The logging code specific to arla, like aliases
     for debugging masks.

cmcb.c - The callback-server that is contacted by the
     server when a callback expire or a server want to send a InitCallBackState.

conn.c - The connection cache, responsible for caching connection
     based on pag and security index. It will also create new connection when needed.

cred.c - Keep track of all credentails that all users have
     inserted. Indexed on pag.

fbuf.c - An interface between rx and filedescriptors. It also
     mmap files. adir.c uses it.

fcache.c - Responsible for keeping track of files in the cache.
     Also fetches files from the afs-server.

fprio.c - Tries to give files priority and therefore not
     garbarge-collected that fast they would be otherwise. Think disconnected mode.

inter.c - A interface to hide all junk in fcache, just give it
     a VenusFid and you have it.

kernel.c - The interface between arlad and the char-device.

messages.c - The rpc interface between arlad and xfs.

volcache.c - Cache for all volumes.

Operatingsystem specific files
------------------------------

These are the files that contain operating specific functions. Today it's just conv_dir().

aix-subr.c - AIX

bsd-subr.c - FreeBSD 2.2.6, OpenBSD 2.2, 2.3, NetBSD 1.3.x

hpux-subr.c - HPUX

irix-subr.c - Irix

linux-subr.c - Linux 2.0.x, 2.1.x, 2.2

solaris-subr.c - Solaris 2.5.x, 2.6, 7

sunos-subr.c - SunOS

unknown-subr.c - Stub used when compiled on a unknown OS.

pioctl and kafs
===============

pioctl is a ioctl but with a path instead of a filedescriptor. When you probe if there is a live afsclient you first run k_hasafs() that probe if there is a afsclient around. It also setup some static variables in the library. So if you start to do pioctl() w/o running k_hasafs(), you're up to funny errors.

What k_hasafs() does is AFSCALL_PIOCTL with opcode VIOCSETTOK and insize == 0, ie you try to set a token (ticket) that is 0 bytes long. This is cleary invalid and kafs expects to find a EINVAL returned from syscall(2).

The pioctl is used more then just for AFSCALL_PIOCTL, other uses are AFSCALL_SETPAG (setting pag). It has also been in use for setting xfs debugginglevels.

When xfs discovers that a path is given in the pioctl() it does a VOP_LOOKUP on the path and if the returned a vnode that resides in afs then it extracts the xfs-handle for that node (that just happens to be the VenusFid) and passes that on to arlad.

The only ugly thing about the current implentation is that the syscall code assumes that the arlad on "xfs-fd" is the arlad that should get this syscall.

An example of using pioctl():

     int
     fs_getfilecellname(char *path, char *cell, size_t len)
     {
         struct ViceIoctl a_params;

         a_params.in_size=0;
         a_params.out_size=len;
         a_params.in=NULL;
         a_params.out=cell;

         if (k_pioctl(path,VIOC_FILE_CELL_NAME,&a_params,1) == -1)
             return errno;

         return 0;
     }