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