share/doc/smm/02.config/3.t

   1 .\" Copyright (c) 1983, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)3.t 8.1 (Berkeley) 6/8/93
  29 .\"
  30 .\".ds RH "System Building Process
  31 .ne 2i
  32 .NH
  33 SYSTEM BUILDING PROCESS
  34 .PP
  35 In this section we consider the steps necessary to build a bootable system
  36 image.  We assume the system source is located in the ``/sys'' directory
  37 and that, initially, the system is being configured from source code.
  38 .PP
  39 Under normal circumstances there are 5 steps in building a system.
  40 .IP 1) 3
  41 Create a configuration file for the system.
  42 .IP 2) 3
  43 Make a directory for the system to be constructed in.
  44 .IP 3) 3
  45 Run
  46 .I config
  47 on the configuration file to generate the files required
  48 to compile and load the system image.
  49 .IP 4)
  50 Construct the source code interdependency rules for the
  51 configured system with
  52 .I make depend
  53 using
  54 .IR make (1).
  55 .IP 5)
  56 Compile and load the system with
  57 .IR make .
  58 .PP
  59 Steps 1 and 2 are usually done only once.  When a system configuration
  60 changes it usually suffices to just run
  61 .I config
  62 on the modified configuration file, rebuild the source code dependencies,
  63 and remake the system.  Sometimes,
  64 however, configuration dependencies may not be noticed in which case
  65 it is necessary to clean out the relocatable object files saved
  66 in the system's directory; this will be discussed later.
  67 .NH 2
  68 Creating a configuration file
  69 .PP
  70 Configuration files normally reside in the directory ``/sys/conf''.
  71 A configuration file is most easily constructed by copying an
  72 existing configuration file and modifying it.  The 4.4BSD distribution
  73 contains a number of configuration files for machines at Berkeley;
  74 one may be suitable or, in worst case, a copy
  75 of the generic configuration file may be edited.
  76 .PP
  77 The configuration file must have the same name as the directory in
  78 which the configured system is to be built.
  79 Further,
  80 .I config
  81 assumes this directory is located in the parent directory of
  82 the directory in which it
  83 is run.  For example, the generic
  84 system has a configuration file ``/sys/conf/GENERIC'' and an accompanying
  85 directory named ``/sys/GENERIC''.
  86 Although it is not required that the system sources and configuration
  87 files reside in ``/sys,'' the configuration and compilation procedure
  88 depends on the relative locations of directories within that hierarchy,
  89 as most of the system code and the files created by
  90 .I config
  91 use pathnames of the form ``../''.
  92 If the system files are not located in ``/sys,''
  93 it is desirable to make a symbolic link there for use in installation
  94 of other parts of the system that share files with the kernel.
  95 .PP
  96 When building the configuration file, be sure to include the items
  97 described in section 2.  In particular, the machine type,
  98 cpu type, timezone, system identifier, maximum users, and root device
  99 must be specified.  The specification of the hardware present may take
 100 a bit of work; particularly if your hardware is configured at non-standard
 101 places (e.g. device registers located at funny places or devices not
 102 supported by the system).  Section 4 of this document
 103 gives a detailed description of the configuration file syntax,
 104 section 5 explains some sample configuration files, and
 105 section 6 discusses how to add new devices to
 106 the system.  If the devices to be configured are not already
 107 described in one of the existing configuration files you should check
 108 the manual pages in section 4 of the UNIX Programmers Manual.  For each
 109 supported device, the manual page synopsis entry gives a
 110 sample configuration line.
 111 .PP
 112 Once the configuration file is complete, run it through
 113 .I config
 114 and look for any errors.  Never try and use a system which
 115 .I config
 116 has complained about; the results are unpredictable.
 117 For the most part,
 118 .IR config 's
 119 error diagnostics are self explanatory.  It may be the case that
 120 the line numbers given with the error messages are off by one.
 121 .PP
 122 A successful run of
 123 .I config
 124 on your configuration file will generate a number of files in
 125 the configuration directory.  These files are:
 126 .IP \(bu 3
 127 A file to be used by \fImake\fP\|(1)
 128 in compiling and loading the system,
 129 .IR Makefile .
 130 .IP \(bu 3
 131 One file for each possible system image for this machine,
 132 .IR swapxxx.c ,
 133 where
 134 .I xxx
 135 is the name of the system image,
 136 which describes where swapping, the root file system, and other
 137 miscellaneous system devices are located.
 138 .IP \(bu 3
 139 A collection of header files, one per possible device the
 140 system supports, which define the hardware configured.
 141 .IP \(bu 3
 142 A file containing the I/O configuration tables used by the system
 143 during its
 144 .I autoconfiguration
 145 phase,
 146 .IR ioconf.c .
 147 .IP \(bu 3
 148 An assembly language file of interrupt vectors which
 149 connect interrupts from the machine's external buses to the main
 150 system path for handling interrupts,
 151 and a file that contains counters and names for the interrupt vectors.
 152 .PP
 153 Unless you have reason to doubt
 154 .IR config ,
 155 or are curious how the system's autoconfiguration scheme
 156 works, you should never have to look at any of these files.
 157 .NH 2
 158 Constructing source code dependencies
 159 .PP
 160 When
 161 .I config
 162 is done generating the files needed to compile and link your system it
 163 will terminate with a message of the form ``Don't forget to run make depend''.
 164 This is a reminder that you should change over to the configuration
 165 directory for the system just configured and type ``make depend''
 166 to build the rules used by
 167 .I make
 168 to recognize interdependencies in the system source code.
 169 This will insure that any changes to a piece of the system
 170 source code will result in the proper modules being recompiled
 171 the next time
 172 .I make
 173 is run.
 174 .PP
 175 This step is particularly important if your site makes changes
 176 to the system include files.  The rules generated specify which source code
 177 files are dependent on which include files.  Without these rules,
 178 .I make
 179 will not recognize when it must rebuild modules
 180 due to the modification of a system header file.
 181 The dependency rules are generated by a pass of the C preprocessor
 182 and reflect the global system options.
 183 This step must be repeated when the configuration file is changed
 184 and
 185 .I config
 186 is used to regenerate the system makefile.
 187 .NH 2
 188 Building the system
 189 .PP
 190 The makefile constructed by
 191 .I config
 192 should allow a new system to be rebuilt by simply typing ``make image-name''.
 193 For example, if you have named your bootable system image ``kernel'',
 194 then ``make kernel''
 195 will generate a bootable image named ``kernel''.  Alternate system image names
 196 are used when the root file system location and/or swapping configuration
 197 is done in more than one way.  The makefile which
 198 .I config
 199 creates has entry points for each system image defined in
 200 the configuration file.
 201 Thus, if you have configured ``kernel'' to be a system with the root file
 202 system on an ``hp'' device and ``hkkernel'' to be a system with the root
 203 file system on an ``hk'' device, then ``make kernel hkkernel'' will generate
 204 binary images for each.
 205 As the system will generally use the disk from which it is loaded
 206 as the root filesystem, separate system images are only required
 207 to support different swap configurations.
 208 .PP
 209 Note that the name of a bootable image is different from the system
 210 identifier.  All bootable images are configured for the same system;
 211 only the information about the root file system and paging devices differ.
 212 (This is described in more detail in section 4.)
 213 .PP
 214 The last step in the system building process is to rearrange certain commonly
 215 used symbols in the symbol table of the system image;  the makefile
 216 generated by
 217 .I config
 218 does this automatically for you.
 219 This is advantageous for programs such as
 220 \fInetstat\fP\|(1) and \fIvmstat\fP\|(1),
 221 which run much faster when the symbols they need are located at
 222 the front of the symbol table.
 223 Remember also that many programs expect
 224 the currently executing system to be named ``/kernel''.  If you install
 225 a new system and name it something other than ``/kernel'', many programs
 226 are likely to give strange results.
 227 .NH 2
 228 Sharing object modules
 229 .PP
 230 If you have many systems which are all built on a single machine
 231 there are at least two approaches to saving time in building system
 232 images.  The best way is to have a single system image which is run on
 233 all machines.  This is attractive since it minimizes disk space used
 234 and time required to rebuild systems after making changes.  However,
 235 it is often the case that one or more systems will require a separately
 236 configured system image.  This may be due to limited memory (building
 237 a system with many unused device drivers can be expensive), or to
 238 configuration requirements (one machine may be a development machine
 239 where disk quotas are not needed, while another is a production machine
 240 where they are), etc.  In these cases it is possible
 241 for common systems to share relocatable object modules which are not
 242 configuration dependent; most of the modules in the directory ``/sys/sys''
 243 are of this sort.
 244 .PP
 245 To share object modules, a generic system should be built.  Then, for
 246 each system configure the system as before, but before recompiling and
 247 linking the system, type ``make links'' in the system compilation directory.
 248 This will cause the system
 249 to be searched for source modules which are safe to share between systems
 250 and generate symbolic links in the current directory to the appropriate
 251 object modules in the directory ``../GENERIC''.  A shell script,
 252 ``makelinks'' is generated with this request and may be checked for
 253 correctness.  The file ``/sys/conf/defines'' contains a list of symbols
 254 which we believe are safe to ignore when checking the source code
 255 for modules which may be shared.  Note that this list includes the definitions
 256 used to conditionally compile in the virtual memory tracing facilities, and
 257 the trace point support used only rarely (even at Berkeley).
 258 It may be necessary
 259 to modify this file to reflect local needs.  Note further that
 260 interdependencies which are not directly visible
 261 in the source code are not caught.  This means that if you place
 262 per-system dependencies in an include file, they will not be recognized
 263 and the shared code may be selected in an unexpected fashion.
 264 .NH 2
 265 Building profiled systems
 266 .PP
 267 It is simple to configure a system which will automatically
 268 collect profiling information as it operates.  The profiling data
 269 may be collected with \fIkgmon\fP\|(8) and processed with
 270 \fIgprof\fP\|(1)
 271 to obtain information regarding the system's operation.  Profiled
 272 systems maintain histograms of the program counter as well as the
 273 number of invocations of each routine.  The \fIgprof\fP
 274 command will also generate a dynamic call graph of the executing
 275 system and propagate time spent in each routine along the arcs
 276 of the call graph (consult the \fIgprof\fP documentation for elaboration).
 277 The program counter sampling can be driven by the system clock, or
 278 if you have an alternate real time clock, this can be used.  The
 279 latter is highly recommended, as use of the system clock will result
 280 in statistical anomalies, and time spent in the clock routine will
 281 not be accurately attributed.
 282 .PP
 283 To configure a profiled system, the
 284 .B \-p
 285 option should be supplied to \fIconfig\fP.
 286 A profiled system is about 5-10% larger in its text space due to
 287 the calls to count the subroutine invocations.  When the system
 288 executes, the profiling data is stored in a buffer which is 1.2
 289 times the size of the text space.  The overhead for running a
 290 profiled system varies; under normal load we see anywhere from 5-25%
 291 of the system time spent in the profiling code.
 292 .PP
 293 Note that systems configured for profiling should not be shared as
 294 described above unless all the other shared systems are also to be
 295 profiled.