7. Porting

The largest part of the work needed to port Arla to a new operating system is in porting xfs, as kernel programming always is harder, less portable and messier than user-space dito. Arla in test mode (arla-cli) should work without any porting on any system that's not very far away from Unix and that provides berkeley sockets (including cygwin32). The hard part is porting the XFS kernel module, and we will spent most of this text on how to do that.

7.1 user-space
7.2 XFS

7.1 user-space

The user-space parts should work on basically any system that is reasonably Posix and has berkeley sockets. The build uses autoconf and should adapt itself to most forseeable circumstances. If it fails to consider something that is missing or not working on the particular OS you are porting to, hard-code it to make sure that is what is missing and then try to create an autoconf test for it. If you fail to do so, or have no autoconf experience, send us the patches anyway and tell us where you are having the problem.

7.1.1 LWP

The only thing that might take a little bit more effort in porting is the context-switch in the LWP user-level threads package. There are assembler versions for most of the common architectures in `lwp'. Part of the problem is getting this code assembled properly. There is unfortunately no easy and portable way of preprocessing and assembling code. There is a script `lwp/make-process.o.sh' that tries to do in some different ways, but it may fail for you. Next problem is that assembler syntax can vary a lot even on the same CPU. The source files are written in such a way that they should be acceptable to almost any syntax, but if it fails you have to find out what particular syntax has to be used and adapt the source file for that.

The more interesting problem is if there is no support for your CPU. The first thing to try then is the --with-pthreads option that uses the pthreads library. If that fails or you want LWP working you have to figure out enough details on your CPU to write two functions in assembler, `savecontext' and `returnto' that save and restore the processor context.

7.2 XFS

1. It helps to have source code for your operating system.

   In theory, if stuff was documented well enough, you wouldn't need it. In practice it never is, so you find out interfaces specs and how stuff works by reading the source code. If you're unable to find source code for your OS, try finding source for the closest match. If your OS is based on BSD, try the appropriate version of BSD, for example.

2. If you don't have source, try second best, include files.

   You can usually gather quite a lot of information on the workings of the kernel by reading the includes files in `<sys/*.h>'.

3. Be lazy

   Try to find out what other XFS port is most similar to your OS and start with that code.

4. Figure out how your kernel works.

   You need to figure out how a few things work in your kernel:

   1. Loading/unloading kernel modules

      That varies quite a lot but it's probably easy to figure out if you have the source code for some other loadable module. Sometimes you can get the kernel to add your cdev, system call and file system automatically but usually you have to write code in your `entry-point' to add these to the appropriate tables.

   2. Adding a new character device driver

      The kernel has a table of all known device drivers, ordered by major number. Some kernels have one for block devices and one for character devices and some have a common one. That entry usually consists of a number of function pointers that perform the operations (open, close, read, write, ...), and possible a name and some flags. It could look something like the following:

      struct cdevsw { int (*d_open)(); int (*d_close)(); ... }; struct cdevsw cdevsw[];

      These are then usually stored in a table `cdevsw' indexed by the major device number. If you're really lucky there's a new way to get the kernel to add your `struct cdevsw' to the global table when loading the module or a function that does the addition for you. Otherwise there might be functions for adding/removing devices to the global table. If not, you'll have to fallback on looking for a free slot in the table and putting your struct cdevsw there. In some cases, this is not stored in a table but then there'll be a way of adding entries to the new data structure so you don't need to worry about it.

   3. Adding a new system call

      This is quite similar to adding a new cdev but the table is usually called sysent instead.

   4. Adding a new file system

      Once again, quite similar in principle. The names of the structures tend to vary quite a lot more.

   5. Finding out how the VFS/Vnode switch works

      The structure vfsops contains function pointers for all of the file system operations. You need to figure out what operations you need to implement (usually at least mount, unmount, root, sync, and statfs).

      The operations that are performed on files are vnode operations (usually stored in a struct vnodeops), and you need to figure which of these you need and how they should work. Also, which is not as explicit, how vnodes are supposed to be allocated and freed and such.

5. Suggested plan of action
   1. Start by writing a minimal hello-world module and make sure you can load and unload it properly.

   2. Then add a device driver to the module which dummy functions and verify that works.

   3. Try to fit the device driver functions in `xfs_dev.c' into the device driver.

   4. Do a dummy module with a system call and verify that you can call it.

   5. Start trying to add enough of the vfs/vnode operations from `xfs_vfsops.c' and `xfs_vnodeops.c' so that you can build it.

   6. Debug it.

   7. Send us patches