share/doc/smm/02.config/6.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 .\"     @(#)6.t 8.1 (Berkeley) 6/8/93
  29 .\" $FreeBSD$
  30 .\"
  31 .\".ds RH "Adding New Devices
  32 .ne 2i
  33 .NH
  34 ADDING NEW SYSTEM SOFTWARE
  35 .PP
  36 This section is not for the novice, it describes
  37 some of the inner workings of the configuration process as
  38 well as the pertinent parts of the system autoconfiguration process.
  39 It is intended to give
  40 those people who intend to install new device drivers and/or
  41 other system facilities sufficient information to do so in the
  42 manner which will allow others to easily share the changes.
  43 .PP
  44 This section is broken into four parts:
  45 .IP \(bu 3
  46 general guidelines to be followed in modifying system code,
  47 .IP \(bu 3
  48 how to add non-standard system facilities to 4.4BSD,
  49 .IP \(bu 3
  50 how to add a device driver to 4.4BSD, and
  51 .NH 2
  52 Modifying system code
  53 .PP
  54 If you wish to make site-specific modifications to the system
  55 it is best to bracket them with
  56 .DS
  57 #ifdef SITENAME
  58 \&...
  59 #endif
  60 .DE
  61 to allow your source to be easily distributed to others, and
  62 also to simplify \fIdiff\fP\|(1) listings.  If you choose not
  63 to use a source code control system (e.g. SCCS, RCS), and
  64 perhaps even if you do, it is
  65 recommended that you save the old code with something
  66 of the form:
  67 .DS
  68 #ifndef SITENAME
  69 \&...
  70 #endif
  71 .DE
  72 We try to isolate our site-dependent code in individual files
  73 which may be configured with pseudo-device specifications.
  74 .PP
  75 Indicate machine-specific code with ``#ifdef vax'' (or other machine,
  76 as appropriate).
  77 4.4BSD underwent extensive work to make it extremely portable to
  78 machines with similar architectures\- you may someday find
  79 yourself trying to use a single copy of the source code on
  80 multiple machines.
  81 .NH 2
  82 Adding non-standard system facilities
  83 .PP
  84 This section considers the work needed to augment
  85 .IR config 's
  86 data base files for non-standard system facilities.
  87 .I Config
  88 uses a set of files that list the source modules that may be required
  89 when building a system.
  90 The data bases are taken from the directory in which
  91 .I config
  92 is run, normally /sys/conf.
  93 Three such files may be used:
  94 .IR files ,
  95 .IR files .machine,
  96 and
  97 .IR files .ident.
  98 The first is common to all systems,
  99 the second contains files unique to a single machine type,
 100 and the third is an optional list of modules for use on a specific machine.
 101 This last file may override specifications in the first two.
 102 The format of the
 103 .I files
 104 file has grown somewhat complex over time.  Entries are normally of
 105 the form
 106 .IP
 107 .nf
 108 .DT
 109 \fIdir/source.c\fP      \fItype\fP       \fIoption-list\fP \fImodifiers\fP
 110 .LP
 111 for example,
 112 .IP
 113 .nf
 114 .DT
 115 \fIvaxuba/foo.c\fP      \fBoptional\fP  foo     \fBdevice-driver\fP
 116 .LP
 117 The
 118 .I type
 119 is one of
 120 .B standard
 121 or
 122 .BR optional .
 123 Files marked as standard are included in all system configurations.
 124 Optional file specifications include a list of one or more system
 125 options that together require the inclusion of this module.
 126 The options in the list may be either names of devices that may
 127 be in the configuration file,
 128 or the names of system options that may be defined.
 129 An optional file may be listed multiple times with different options;
 130 if all of the options for any of the entries are satisfied,
 131 the module is included.
 132 .PP
 133 If a file is specified as a
 134 .IR device-driver ,
 135 any special compilation options for device drivers will be invoked.
 136 On the VAX this results in the use of the
 137 .B \-i
 138 option for the C optimizer.  This is required when pointer references
 139 are made to memory locations in the VAX I/O address space.
 140 .PP
 141 Two other optional keywords modify the usage of the file.
 142 .I Config
 143 understands that certain files are used especially for
 144 kernel profiling.  These files are indicated in the
 145 .I files
 146 files with a
 147 .I profiling-routine
 148 keyword.  For example, the current profiling subroutines
 149 are sequestered off in a separate file with the following
 150 entry:
 151 .IP
 152 .nf
 153 .DT
 154 \fIsys/subr_mcount.c\fP \fBoptional\fP  \fBprofiling-routine\fP
 155 .fi
 156 .LP
 157 The
 158 .I profiling-routine
 159 keyword forces
 160 .I config
 161 not to compile the source file with the
 162 .B \-pg
 163 option.
 164 .PP
 165 The second keyword which can be of use is the
 166 .I config-dependent
 167 keyword.  This causes
 168 .I config
 169 to compile the indicated module with the global configuration
 170 parameters.  This allows certain modules, such as
 171 .I machdep.c
 172 to size system data structures based on the maximum number
 173 of users configured for the system.
 174 .NH 2
 175 Adding device drivers to 4.4BSD
 176 .PP
 177 The I/O system and
 178 .I config
 179 have been designed to easily allow new device support to be added.
 180 The system source directories are organized as follows:
 181 .DS
 182 .TS
 183 lw(1.0i) l.
 184 /sys/h  machine independent include files
 185 /sys/sys        machine-independent system source files
 186 /sys/conf       site configuration files and basic templates
 187 /sys/net        network-protocol-independent, but network-related code
 188 /sys/netinet    DARPA Internet code
 189 /sys/netimp     IMP support code
 190 /sys/netns      Xerox NS code
 191 /sys/vax        VAX-specific mainline code
 192 /sys/vaxif      VAX network interface code
 193 /sys/vaxmba     VAX MASSBUS device drivers and related code
 194 /sys/vaxuba     VAX UNIBUS device drivers and related code
 195 .TE
 196 .DE
 197 .PP
 198 Existing block and character device drivers for the VAX
 199 reside in ``/sys/vax'', ``/sys/vaxmba'', and ``/sys/vaxuba''.  Network
 200 interface drivers reside in ``/sys/vaxif''.  Any new device
 201 drivers should be placed in the appropriate source code directory
 202 and named so as not to conflict with existing devices.
 203 Normally, definitions for things like device registers are placed in
 204 a separate file in the same directory.  For example, the ``dh''
 205 device driver is named ``dh.c'' and its associated include file is
 206 named ``dhreg.h''.
 207 .PP
 208 Once the source for the device driver has been placed in a directory,
 209 the file ``/sys/conf/files.machine'', and possibly
 210 ``/sys/conf/devices.machine'' should be modified.  The
 211 .I files
 212 files in the conf directory contain a line for each C source or binary-only
 213 file in the system.  Those files which are machine independent are
 214 located in ``/sys/conf/files,'' while machine specific files
 215 are in ``/sys/conf/files.machine.''  The ``devices.machine'' file
 216 is used to map device names to major block device numbers.  If the device
 217 driver being added provides support for a new disk
 218 you will want to modify this file (the format is obvious).
 219 .PP
 220 In addition to including the driver in the
 221 .I files
 222 file, it must also be added to the device configuration tables.  These
 223 are located in ``/sys/vax/conf.c'', or similar for machines other than
 224 the VAX.  If you don't understand what to add to this file, you should
 225 study an entry for an existing driver.
 226 Remember that the position in the
 227 device table specifies the major device number.
 228 The block major number is needed in the ``devices.machine'' file
 229 if the device is a disk.