doc/porting.texi

   1 @c Copyright (c) 1998 - 2000 Kungliga Tekniska Högskolan
   2 @c (Royal Institute of Technology, Stockholm, Sweden).
   3 @c All rights reserved.
   4
   5 @c $Id$
   6
   7 @node Porting, Programming, Darwin/MacOS X, Top
   8 @comment  node-name,  next,  previous,  up
   9 @chapter Porting
  10
  11 The largest part of the work needed to port Arla to a new operating
  12 system is in porting nnpfs, as kernel programming always is harder, less
  13 portable and messier than user-space dito.  Arla in test mode
  14 (@kbd{arla-cli}) should work without any porting on any system that's
  15 not very far away from Unix and that provides berkeley sockets
  16 (including cygwin32).  The hard part is porting the NNPFS kernel module,
  17 and we will spent most of this text on how to do that.
  18
  19 @menu
  20 * Porting user-space::
  21 * Porting NNPFS::
  22 @end menu
  23
  24 @node Porting user-space, Porting NNPFS, Porting, Porting
  25 @section user-space
  26
  27 The user-space parts should work on basically any system that is
  28 reasonably Posix and has berkeley sockets.  The build uses autoconf and
  29 should adapt itself to most forseeable circumstances.  If it fails to
  30 consider something that is missing or not working on the particular OS
  31 you are porting to, hard-code it to make sure that is what is missing
  32 and then try to create an autoconf test for it.  If you fail to do so,
  33 or have no autoconf experience, send us the patches anyway and tell us
  34 where you are having the problem.
  35
  36 @subsection LWP
  37
  38 The only thing that might take a little bit more effort in porting is
  39 the context-switch in the LWP user-level threads package.  There are
  40 assembler versions for most of the common architectures in @file{lwp}.
  41 Part of the problem is getting this code assembled properly.  There is
  42 unfortunately no easy and portable way of preprocessing and assembling
  43 code.  There is a script @file{lwp/make-process.o.sh} that tries to do
  44 in some different ways, but it may fail for you.  Next problem is that
  45 assembler syntax can vary a lot even on the same CPU.  The source files
  46 are written in such a way that they should be acceptable to almost any
  47 syntax, but if it fails you have to find out what particular syntax has
  48 to be used and adapt the source file for that.
  49
  50 The more interesting problem is if there is no support for your CPU.
  51 The first thing to try then is the @kbd{--with-pthreads} option that
  52 uses the pthreads library.  If that fails or you want LWP working you
  53 have to figure out enough details on your CPU to write two functions in
  54 assembler, @samp{savecontext} and @samp{returnto} that save and
  55 restore the processor context.
  56
  57 @node Porting NNPFS, , Porting user-space, Porting
  58 @section NNPFS
  59
  60 @enumerate
  61
  62 @item
  63 It helps to have source code for your operating system.
  64
  65 In theory, if stuff was documented well enough, you wouldn't need it.
  66 In practice it never is, so you find out interfaces specs and how stuff
  67 works by reading the source code.  If you're unable to find source code
  68 for your OS, try finding source for the closest match.  If your OS is
  69 based on BSD, try the appropriate version of BSD, for example.
  70
  71 @item
  72 If you don't have source, try second best, include files.
  73
  74 You can usually gather quite a lot of information on the workings of the
  75 kernel by reading the includes files in @file{<sys/*.h>}.
  76
  77 @item
  78 Be lazy
  79
  80 Try to find out what other NNPFS port is most similar to your OS and start
  81 with that code.
  82
  83 @item
  84 Figure out how your kernel works.
  85
  86 You need to figure out how a few things work in your kernel:
  87
  88 @enumerate
  89
  90 @item
  91 Loading/unloading kernel modules
  92
  93 That varies quite a lot but it's probably easy to figure out if you
  94 have the source code for some other loadable module.  Sometimes you
  95 can get the kernel to add your cdev, system call and file system
  96 automatically but usually you have to write code in your `entry-point'
  97 to add these to the appropriate tables.
  98
  99 @item
 100 Adding a new character device driver
 101
 102 The kernel has a table of all known device drivers, ordered by major
 103 number.  Some kernels have one for block devices and one for character
 104 devices and some have a common one.  That entry usually consists of a
 105 number of function pointers that perform the operations (open, close,
 106 read, write, ...), and possible a name and some flags.  It could look
 107 something like the following:
 108
 109 @example
 110 struct cdevsw @{
 111         int (*d_open)();
 112         int (*d_close)();
 113         ...
 114 @};
 115
 116 struct cdevsw cdevsw[];
 117 @end example
 118
 119 These are then usually stored in a table `cdevsw' indexed by the major
 120 device number. If you're really lucky there's a new way to get the
 121 kernel to add your `struct cdevsw' to the global table when loading the
 122 module or a function that does the addition for you.  Otherwise there
 123 might be functions for adding/removing devices to the global table.
 124 If not, you'll have
 125 to fallback on looking for a free slot in the table and putting your
 126 struct cdevsw there. In some cases, this is not stored in a table but
 127 then there'll be a way of adding entries to the new data structure so
 128 you don't need to worry about it.
 129
 130 @item
 131 Adding a new system call
 132
 133 This is quite similar to adding a new cdev but the table is usually
 134 called @code{sysent} instead.
 135
 136 @item
 137 Adding a new file system
 138
 139 Once again, quite similar in principle. The names of the structures
 140 tend to vary quite a lot more.
 141
 142 @item
 143 Finding out how the VFS/Vnode switch works
 144
 145 The structure vfsops contains function pointers for all of the file
 146 system operations.  You need to figure out what operations you need to
 147 implement (usually at least mount, unmount, root, sync, and statfs).
 148
 149 The operations that are performed on files are vnode operations
 150 (usually stored in a struct vnodeops), and you need to figure which of
 151 these you need and how they should work.  Also, which is not as
 152 explicit, how vnodes are supposed to be allocated and freed and such.
 153
 154 @end enumerate
 155
 156 @item
 157 Suggested plan of action
 158
 159 @enumerate
 160
 161 @item
 162 Start by writing a minimal hello-world module and make sure you can load
 163 and unload it properly.
 164
 165 @item
 166 Then add a device driver to the module which dummy functions and
 167 verify that works.
 168
 169 @item
 170 Try to fit the device driver functions in @file{nnpfs_dev.c} into the
 171 device driver.
 172
 173 @item
 174 Do a dummy module with a system call and verify that you can call it.
 175
 176 @item
 177 Start trying to add enough of the vfs/vnode operations from
 178 @file{nnpfs_vfsops.c} and @file{nnpfs_vnodeops.c} so that you can build it.
 179
 180 @item
 181 Debug it.
 182
 183 @item
 184 Send us patches
 185
 186 @end enumerate
 187
 188 @end enumerate