src/export/README

   1 Copyright 2000, International Business Machines Corporation and others.
   2 All Rights Reserved.
   3
   4 This software has been released under the terms of the IBM Public
   5 License.  For details, see the LICENSE file in the top-level source
   6 directory or online at http://www.openafs.org/dl/license10.html
   7
   8         EXPORT is an aix3.1 kernel extension whose sole purpose in
   9         life is to provide access to kernel symbols that were mistakenly
  10         (or purposefully) omitted from the kernel exports list.
  11
  12         The way EXPORT works is as follows:
  13
  14                 /etc/cfgexport -a /etc/export.ext
  15
  16         loads in the EXPORT kernel extension, and passes all relevant info
  17         from the /unix symbol table.  THIS HAD BETTER BE THE SAME KERNEL
  18         THAT WAS BOOTED FROM!
  19
  20         /etc/export.ext is the load module for the EXPORT kernel extension.
  21         When it is loaded, is slurps in the symbol table information, and
  22         makes available the following:
  23
  24                 import_kfunc(struct k_func *kfp)
  25                 import_kvar(struct k_var *kvp, ulong *toc)
  26
  27         The relevant data structures are defined in "export.h":
  28
  29 /*
  30  * kernel function import
  31  */
  32 struct k_func {
  33         void    *(**fpp)();     /* ^ to ^ to function we import */
  34         char    *name;          /* ^ to symbol name             */
  35         ulong   fdesc[3];       /* function descriptor storage  */
  36 };
  37
  38 /*
  39  * kernel variable import
  40  */
  41 struct k_var {
  42         void    *varp;          /* ^ to surrogate variable      */
  43         char    *name;          /* ^ to symbol name             */
  44 };
  45
  46
  47         import_kfunc() can be used to acquire a function pointer to
  48         most kernel functions.
  49         import_kvar() can be used to redirect references to a local
  50         surrogate variable to the kernel variable.
  51
  52         An example of usage would be:
  53
  54 #include "export.h"
  55
  56 static void (*kluge_iput)();    /* ^ to kernel's `iput()'       */
  57 void *u;                        /* surrogate `u.' variable      */
  58 void *vnodefops;                /* surrogate `vnodefops' var    */
  59
  60 struct k_func kfuncs[] = {
  61         {       &kluge_iput,    ".iput"         },
  62         {       0                               }
  63 };
  64
  65 struct k_var kvars[] = {
  66         {       (void *) &u,            "u"             },
  67         {       (void *) &vnodefops,    "vnodefops"     },
  68         {       0                                       },
  69 };
  70
  71 kluge_init() {
  72         register struct k_func *kfp;
  73         register struct k_var  *kvp;
  74         register ulong *toc;
  75
  76         toc = (ulong *) get_toc();
  77
  78         for (kfp = kfuncs; kfp->name; ++kfp)
  79                 import_kfunc(kfp);
  80
  81         for (kvp = kvars; kvp->name; ++kvp)
  82                 import_kvar(kvp, toc);
  83 }
  84
  85 iput(ip)
  86 struct inode *ip; {
  87
  88         return (*kluge_iput)(ip);
  89 }
  90
  91
  92         Note the call to `get_toc()'.  This returns the value that will be
  93         in the TOC register (a dedicated general purpose register, R2, that
  94         is used as the base register to the `table-of-contents' area that
  95         is where references to all global variables is placed).  The TOC
  96         is distinct for each kernel extension.  There is code for
  97         `get_toc' in afs/misc.s.
  98
  99         It is not possible to import functions the same as variables.  If
 100         one were to replace a TOC entry for a function, one would most
 101         likely panic very soon after calling that function, if one were
 102         lucky!  The calling sequence for inter-module (inter-extension)
 103         differs from that of intra-module (intra-extension), in order to
 104         save/restore the TOC register, and load the correct TOC
 105         register value for the called code.  Calls through pointers to
 106         functions must already handle this, so importing functions is done
 107         by constructing function pointers, and calling into the kernel
 108         with them.
 109
 110         Note also that is is not possible (currently) to import functions
 111         (in the above manner) that are provided by other kernel extensions.
 112         This is due to the fact that import_kfunc() uses the kernel's TOC
 113         register value when constructing the function descriptors, rather
 114         than the correct one for the kernel extension in which the target
 115         function resides.  Since the set of functions that is available
 116         is restricted (normally) to those described in /unix's symbol table,
 117         this is not usually a problem.  When the /unix symbol table explicitly
 118         refers to a function that it knows to be provided by subsequently
 119         loaded extension, there may or may not be a problem, depending on
 120         how the glue code generated in the kernel to make the external
 121         call interacts/conflicts with the `call thru pointer' code.  I can't
 122         remember this off the top of my head just now...
 123
 124 Enjoy!