1 .\" Copyright (c) 1983, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .\" @(#)6.t 8.1 (Berkeley) 6/8/93
35 .\".ds RH "Adding New Devices
38 ADDING NEW SYSTEM SOFTWARE
40 This section is not for the novice, it describes
41 some of the inner workings of the configuration process as
42 well as the pertinent parts of the system autoconfiguration process.
43 It is intended to give
44 those people who intend to install new device drivers and/or
45 other system facilities sufficient information to do so in the
46 manner which will allow others to easily share the changes.
48 This section is broken into four parts:
50 general guidelines to be followed in modifying system code,
52 how to add non-standard system facilities to 4.4BSD,
54 how to add a device driver to 4.4BSD, and
58 If you wish to make site-specific modifications to the system
59 it is best to bracket them with
65 to allow your source to be easily distributed to others, and
66 also to simplify \fIdiff\fP\|(1) listings. If you choose not
67 to use a source code control system (e.g. SCCS, RCS), and
68 perhaps even if you do, it is
69 recommended that you save the old code with something
76 We try to isolate our site-dependent code in individual files
77 which may be configured with pseudo-device specifications.
79 Indicate machine-specific code with ``#ifdef vax'' (or other machine,
81 4.4BSD underwent extensive work to make it extremely portable to
82 machines with similar architectures\- you may someday find
83 yourself trying to use a single copy of the source code on
86 Adding non-standard system facilities
88 This section considers the work needed to augment
90 data base files for non-standard system facilities.
92 uses a set of files that list the source modules that may be required
93 when building a system.
94 The data bases are taken from the directory in which
96 is run, normally /sys/conf.
97 Three such files may be used:
102 The first is common to all systems,
103 the second contains files unique to a single machine type,
104 and the third is an optional list of modules for use on a specific machine.
105 This last file may override specifications in the first two.
108 file has grown somewhat complex over time. Entries are normally of
113 \fIdir/source.c\fP \fItype\fP \fIoption-list\fP \fImodifiers\fP
119 \fIvaxuba/foo.c\fP \fBoptional\fP foo \fBdevice-driver\fP
127 Files marked as standard are included in all system configurations.
128 Optional file specifications include a list of one or more system
129 options that together require the inclusion of this module.
130 The options in the list may be either names of devices that may
131 be in the configuration file,
132 or the names of system options that may be defined.
133 An optional file may be listed multiple times with different options;
134 if all of the options for any of the entries are satisfied,
135 the module is included.
137 If a file is specified as a
139 any special compilation options for device drivers will be invoked.
140 On the VAX this results in the use of the
142 option for the C optimizer. This is required when pointer references
143 are made to memory locations in the VAX I/O address space.
145 Two other optional keywords modify the usage of the file.
147 understands that certain files are used especially for
148 kernel profiling. These files are indicated in the
152 keyword. For example, the current profiling subroutines
153 are sequestered off in a separate file with the following
158 \fIsys/subr_mcount.c\fP \fBoptional\fP \fBprofiling-routine\fP
165 not to compile the source file with the
169 The second keyword which can be of use is the
173 to compile the indicated module with the global configuration
174 parameters. This allows certain modules, such as
176 to size system data structures based on the maximum number
177 of users configured for the system.
179 Adding device drivers to 4.4BSD
183 have been designed to easily allow new device support to be added.
184 The system source directories are organized as follows:
188 /sys/h machine independent include files
189 /sys/sys machine-independent system source files
190 /sys/conf site configuration files and basic templates
191 /sys/net network-protocol-independent, but network-related code
192 /sys/netinet DARPA Internet code
193 /sys/netimp IMP support code
194 /sys/netns Xerox NS code
195 /sys/vax VAX-specific mainline code
196 /sys/vaxif VAX network interface code
197 /sys/vaxmba VAX MASSBUS device drivers and related code
198 /sys/vaxuba VAX UNIBUS device drivers and related code
202 Existing block and character device drivers for the VAX
203 reside in ``/sys/vax'', ``/sys/vaxmba'', and ``/sys/vaxuba''. Network
204 interface drivers reside in ``/sys/vaxif''. Any new device
205 drivers should be placed in the appropriate source code directory
206 and named so as not to conflict with existing devices.
207 Normally, definitions for things like device registers are placed in
208 a separate file in the same directory. For example, the ``dh''
209 device driver is named ``dh.c'' and its associated include file is
212 Once the source for the device driver has been placed in a directory,
213 the file ``/sys/conf/files.machine'', and possibly
214 ``/sys/conf/devices.machine'' should be modified. The
216 files in the conf directory contain a line for each C source or binary-only
217 file in the system. Those files which are machine independent are
218 located in ``/sys/conf/files,'' while machine specific files
219 are in ``/sys/conf/files.machine.'' The ``devices.machine'' file
220 is used to map device names to major block device numbers. If the device
221 driver being added provides support for a new disk
222 you will want to modify this file (the format is obvious).
224 In addition to including the driver in the
226 file, it must also be added to the device configuration tables. These
227 are located in ``/sys/vax/conf.c'', or similar for machines other than
228 the VAX. If you don't understand what to add to this file, you should
229 study an entry for an existing driver.
230 Remember that the position in the
231 device table specifies the major device number.
232 The block major number is needed in the ``devices.machine'' file
233 if the device is a disk.