src/man/dkload.1

   1 dkload                     AFS Commands                  dkload
   2
   3
   4 NAME
   5
   6    dkload -- incorporate   external   libraries   into  kernel
   7
   8                        without rebooting.
   9
  10
  11    dkload  [-readonly]  [-quiet]  [-verbose]  [-syscallResult
  12    <number>]
  13    [-path <object path>]  [-ld_cmd <loader path>]
  14    [-as_cmd <assembler path>]  [-nm_cmd <nm path>]
  15    [-libcommon <path>] [-kernel_alloc <path>]
  16                                                     +
  17    [-name <library name>]  [<library to incorporate> ]
  18
  19 ACCEPTABLE ABBREVIATIONS
  20
  21    This command does not use the syntax conventions of the  AFS
  22    command  suites.   Therefore, "dkload" must be typed in full
  23    and switches must always be included,  though  they  may  be
  24    shortened as indicated.
  25
  26    dkload  [-r]  [-q]  [-v]  [-s <number>] [-p <object path>]
  27    [-ld <loader path>]
  28    [-a <assembler path>]  [-nm <nm path>]  [-li <path>] [-k
  29    <path>]
  30                                                   +
  31    [-na <library name>]  [<library to incorporate> ]
  32
  33 DESCRIPTION
  34
  35    Loads  one  or more libraries into the memory version of the
  36    local machine's kernel.  It does not alter the disk  version
  37    of  the kernel (/vmunix or equivalent).  Its intended use is
  38    loading the AFS routine library, lib.afs, into the kernel on
  39    client machines.
  40
  41    The  dynamic  loader  begins by requesting (from a low-level
  42    kernel routine) allocation of a certain amount of memory  in
  43    which  to  load the libraries.  It resolves cross-references
  44    between  procedures  in  the  existing  kernel  and  in  the
  45    libraries (referred to as "linking" the two).  The result is
  46    a  list  of  memory  addresses  for   the   cross-referenced
  47    procedures,  which the dynamic loader stores in a table.  It
  48    generates  an  executable  version  of  the  libraries  with
  49    correct  addresses  inserted for all of the necessary kernel
  50    variables and procedures, and loads the executable into  the
  51    memory space allocated in the first phase.
  52
  53 REQUIREMENTS
  54
  55    The  dkload  binary  file should be available in the current
  56    working directory, or the issuer must specify a pathname  in
  57    the    command    name.      The   standard   directory   is
  58    /usr/vice/etc/dkload     on     client     machines      and
  59    /usr/afs/bin/dkload on file server machines.
  60
  61    The file kalloc.o should be available in the current working
  62    directory, or the issuer must specify a pathname with either
  63    the -kernel_alloc or -path argument.  This file helps in the
  64    first phase of dynamic loading:   allocating  kernel  memory
  65
  66
  67
  68    for the libraries.  It is generated automatically during the
  69    compilation of the dkload program.
  70
  71    The file libcommon.a should  be  available  in  the  current
  72    working  directory,  or  the  issuer must specify a pathname
  73    with either the -libcommon or -path  argument.    This  file
  74    helps  in  the  second  phase  of dynamic loading: resolving
  75    cross-references.  It is generated automatically during  the
  76    compilation of the dkload program.
  77
  78    The library file(s) to be loaded (such as lib.afs) should be
  79    available in the current working directory,  or  the  issuer
  80    must use the -path argument to specify the correct path.
  81
  82    The  binary  files for the standard UNIX commands ld, as and
  83    nm should be available in a local disk directory included in
  84    the  issuer's  $PATH  environment  variable.  Otherwise, the
  85    issuer needs to use  the  -ld_cmd,  -as_cmd  and/or  -nm_cmd
  86    arguments to specify the correct pathname.
  87
  88 ARGUMENTS
  89
  90    -readonly       directs  the  command  interpreter to report
  91                    the actions it would  perform  if  executing
  92                    the command, rather than actually performing
  93                    it.
  94
  95    -quiet          suppresses the  trace  of  actions  that  by
  96                    default appears on standard output (stdout).
  97
  98    -verbose        increases  the  amount of information in the
  99                    trace  that  appears  on   standard   output
 100                    (stdout).    Multiple instances of this flag
 101                    may be provided, resulting (up to a  certain
 102                    point)  in  a  increasing level of detail in
 103                    the trace.
 104
 105    -syscallResult  specifies  the  memory  address   at   which
 106                    allocation begins when the -readonly flag is
 107                    provided.  This is useful  when  the  issuer
 108                    wants  to  specify a memory address obtained
 109                    during a previous aborted run of dkload.
 110
 111                    Provide  this  argument  only   when   using
 112                    -readonly.   The value may be either a large
 113                    decimal or hexidecimal  number  (the  latter
 114                    beginning  with  0x).    If this flag is not
 115                    provided, the value defaults to  0xc1456780,
 116                    which  may  not be acceptable on all machine
 117                    types but has the advantage that  it  causes
 118                    allocation to begin well above the addresses
 119                    used by standard libraries.
 120
 121    -path           specifies the directory in which the command
 122                    interpreter  can  find kalloc.o, libcommon.a
 123                    and each library to be loaded, if  they  are
 124                    not  in  the current working directory.  The
 125                    value of  this  argument  is  overridden  by
 126                    -kernel_alloc   and   -libcommon,   or   the
 127                    pathnames  given   for   each   library   to
 128                    incorporate.
 129
 130
 131
 132    -ld_cmd         specifies the pathname to the binary for the
 133                    UNIX ld command, which  the  kernel  dynamic
 134                    loader uses during the linking phase.
 135
 136                    This  argument  is  necessary  only  if  the
 137                    issuer's $PATH environment variable will not
 138                    lead to the correct binary file.  The binary
 139                    file cannot be in AFS, for  instance,  since
 140                    the  dynamic  loader runs before the machine
 141                    can access AFS.
 142
 143    -as_cmd         specifies the pathname to the binary for the
 144                    UNIX  as  command,  which the kernel dynamic
 145                    loader uses during the linking phase.
 146
 147                    This  argument  is  necessary  only  in  the
 148                    conditions specified under -ld_cmd.
 149
 150    -nm_cmd         specifies the pathname to the binary for the
 151                    UNIX nm command, which  the  kernel  dynamic
 152                    loader uses during the linking phase.
 153
 154                    This  argument  is  necessary  only  in  the
 155                    conditions specified under -ld_cmd.
 156
 157    -libcommon      specifies the pathname  of  the  libcommon.a
 158                    file.
 159
 160                    This  argument is necessary only if the file
 161                    does  not  reside  in  the  current  working
 162                    directory  or if the -path argument does not
 163                    indicate the correct directory for it.
 164
 165    -kernel_alloc   specifies the pathname of the kalloc.o file.
 166
 167                    This  argument  is  necessary  only  in  the
 168                    conditions specified under -libcommon.
 169
 170    -name           specifies  the  variable part of the library
 171                    name to be loaded: the  command  interpreter
 172                    loads        the        library       called
 173                    "lib<library name>.a".    For  example,   if
 174                    <library  name>  is  afs, then libafs.a gets
 175                    loaded.
 176
 177                    Provide  this   argument   OR   library   to
 178                    incorporate.
 179
 180    library to incorporate names each library to be incorporated
 181                    into the kernel.
 182
 183                    Provide this argument OR -name.
 184
 185 EXAMPLE
 186
 187    The following loads in the AFS libraries.  It  assumes  that
 188    all  files  can  be  found in the current directory or other
 189    expected place.  The issuer desires extra trace information.
 190
 191    % dkload -verbose -name afs
 192
 193
 194
 195 PRIVILEGE REQUIRED
 196
 197    Issuer must be logged into the machine's UNIX file system as
 198    "root" or at least have w access to /dev/mem and /dev/kmem.