@node Parts of Arla, Debugging, Introduction, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Parts of Arla

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


@menu
* How arla works::
* Arlad and XFS relation::
* The life of a file::
* Tools and libs::
* The files in arlad/::
* pioctl and kafs::
@end menu

@comment -----------------------------------------------------
@node How arla works, Arlad and XFS relation, Parts of Arla, Parts of Arla 
@heading 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.

@c XXX ptr to coda and arla-usenix paper

xfs and arlad communicate with each other via a char-device-driver.
There is a rpc-protocol currenly used specially written for this
(@file{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.

@comment -----------------------------------------------------
@node Arlad and XFS relation, The life of a file, How arla works, Parts of Arla
@heading Arlad and XFS relation

@example
Userland

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

@end example

@table @asis
@item [1] A char device (/dev/xfs0)
@item [2] Xfs provides a filesystem for the vfs-layer in
the operating system.
@end table

@comment -----------------------------------------------------
@node The life of a file, Tools and libs, Arlad and XFS relation, Parts of Arla
@section 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.

@itemize @bullet

@item The user decides to open a file.

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

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

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

@item 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.

@item 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.

@item 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.

@item 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.

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

@item 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). 

@item 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.

@item 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.

@item Now the user wants to read a file. 

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

@item 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.

@end itemize

@comment -----------------------------------------------------
@node Tools and libs, The files in arlad/, The life of a file, Parts of Arla
@heading Tools and libs

What other tools does the arla suite consists of

@table @asis

@item @code{libutil} - a library for most used modules like hashtable,
double-linked list, logging functions, date-parsing, etc

@item @code{rx} - the library for the rx protocol (@xref{Rx protocol}).

@item @code{lwp} - the library for the lwp thread-package
 (@xref{LWP}).

@item @code{ydr} - A stub generator that replaces rxgen.

@item @code{rxkad} - The rx Kerberos authentication package.

@item @code{lib/roken/} - The library that will unbreak things that
is missing or broken.

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

@item @code{appl/libarlalib.a} - A broken library that does all the hard
work with connections etc.

@item @code{appl/fs} - The fs util, extra feature: getfid
@item @code{appl/vos} - The vos util
@item @code{appl/pts} - The pts util, extra feature: dump
@item @code{appl/udebug} - Debug your ubik server

@end table

@include tools.texi

@comment -----------------------------------------------------
@node The files in arlad/, pioctl and kafs, Tools and libs, Parts of Arla
@heading The files in arlad/

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

@subsection The core of arlad

@table @asis

@item @file{adir.c} - contain all functions needed to to operations
on afs-directory file.

@item @file{afsdir_check.c} - check if a afs-directory looks sane.

@item @file{arla.c} - The startup and the standalone (-t) code.

@item @file{arladeb.c} - The logging code specific to arla, like aliases
for debugging masks.

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

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

@item @file{cred.c} - Keep track of all credentails that all users have 
inserted. Indexed on pag.

@item @file{fbuf.c} - An interface between rx and filedescriptors. It also 
mmap files. @file{adir.c} uses it.

@item @file{fcache.c} - Responsible for keeping track of files in the cache.
Also fetches files from the afs-server.

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

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

@item @file{kernel.c} - The interface between arlad and the char-device.

@item @file{messages.c} - The rpc interface between arlad and xfs.

@item @file{volcache.c} - Cache for all volumes.

@end table

@subsection Operatingsystem specific files

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

@table @asis

@item @file{aix-subr.c} - AIX
@item @file{bsd-subr.c} - FreeBSD 2.2.6, OpenBSD 2.2, 2.3, NetBSD 1.3.x
@item @file{hpux-subr.c} - HPUX
@item @file{irix-subr.c} - Irix
@item @file{linux-subr.c} - Linux 2.0.x, 2.1.x, 2.2
@item @file{solaris-subr.c} - Solaris 2.5.x, 2.6, 7
@item @file{sunos-subr.c} - SunOS
@item @file{unknown-subr.c} - Stub used when compiled on a unknown OS.

@end table
@comment -----------------------------------------------------

@node pioctl and kafs, ,The files in arlad/, Parts of Arla
@heading 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
@code{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 @code{pioctl()} w/o running @code{k_hasafs()}, you're 
up to funny errors.

What @code{k_hasafs()} does is @code{AFSCALL_PIOCTL} with opcode 
@code{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 @code{EINVAL} returned from @code{syscall(2)}.

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

When xfs discovers that a path is given in the @code{pioctl()}
it does a @code{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 @code{pioctl()}

@code{
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;
@}
}

@comment -----------------------------------------------------

@c -----------------------------------------------------------
@c  Storybook
@c -----------------------------------------------------------
@c
@c Assar Westerlund tells a story to the rest of the world:
@c 
@c  John Hawkinson <jhawk@MIT.EDU> writes:
@c  > What does sl stand for?
@c  
@c  The short answer is that you should ask Mark.
@c  
@c  The long answer is that it used to be this old library part of MIT
@c  krb4 that was called `ss' (that I believe is short for subsystem, and
@c  that was part of some unknown operating system a long time ago.
@c  (Again, ask Mark.)), for reading and handling command line loops and
@c  parsing.  That wasn't IMHO optimal so we wrote a new library which we
@c  called `sl'.  The reason for SL is that the local transport authority
@c  in Stockholm used tobe called SS (Stockholms Sparvagar) but due to
@c  the bad PR this abbreviation got under the second world war, they
@c  renamed themselves to SL (Stor-stockholms Lokaltrafik).
@c
@c 
@c [ lha: Mark is only known to assar ]
@c [ assar: Mark == Mark Eichin ]
@c -----------------------------------------------------------
