diff options
author | dim <dim@FreeBSD.org> | 2010-12-09 22:01:15 +0000 |
---|---|---|
committer | dim <dim@FreeBSD.org> | 2010-12-09 22:01:15 +0000 |
commit | a3786f65f1e2fa3a4e925fdb4b2b5544b9021bf9 (patch) | |
tree | 5f0a24f71baa3176c75a20a51a9e20a22c75426c /share/doc/smm/02.config/6.t | |
parent | ad01c620333d05c430d583ee40647e396be1ab91 (diff) | |
parent | 12dd9eb8e940c48f9fc30dbc137071b4fe5caead (diff) | |
download | FreeBSD-src-a3786f65f1e2fa3a4e925fdb4b2b5544b9021bf9.zip FreeBSD-src-a3786f65f1e2fa3a4e925fdb4b2b5544b9021bf9.tar.gz |
Sync: merge r216133 through r216338 from ^/head.
Diffstat (limited to 'share/doc/smm/02.config/6.t')
-rw-r--r-- | share/doc/smm/02.config/6.t | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/share/doc/smm/02.config/6.t b/share/doc/smm/02.config/6.t new file mode 100644 index 0000000..49f6e91 --- /dev/null +++ b/share/doc/smm/02.config/6.t @@ -0,0 +1,233 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)6.t 8.1 (Berkeley) 6/8/93 +.\" $FreeBSD$ +.\" +.\".ds RH "Adding New Devices +.ne 2i +.NH +ADDING NEW SYSTEM SOFTWARE +.PP +This section is not for the novice, it describes +some of the inner workings of the configuration process as +well as the pertinent parts of the system autoconfiguration process. +It is intended to give +those people who intend to install new device drivers and/or +other system facilities sufficient information to do so in the +manner which will allow others to easily share the changes. +.PP +This section is broken into four parts: +.IP \(bu 3 +general guidelines to be followed in modifying system code, +.IP \(bu 3 +how to add non-standard system facilities to 4.4BSD, +.IP \(bu 3 +how to add a device driver to 4.4BSD, and +.NH 2 +Modifying system code +.PP +If you wish to make site-specific modifications to the system +it is best to bracket them with +.DS +#ifdef SITENAME +\&... +#endif +.DE +to allow your source to be easily distributed to others, and +also to simplify \fIdiff\fP\|(1) listings. If you choose not +to use a source code control system (e.g. SCCS, RCS), and +perhaps even if you do, it is +recommended that you save the old code with something +of the form: +.DS +#ifndef SITENAME +\&... +#endif +.DE +We try to isolate our site-dependent code in individual files +which may be configured with pseudo-device specifications. +.PP +Indicate machine-specific code with ``#ifdef vax'' (or other machine, +as appropriate). +4.4BSD underwent extensive work to make it extremely portable to +machines with similar architectures\- you may someday find +yourself trying to use a single copy of the source code on +multiple machines. +.NH 2 +Adding non-standard system facilities +.PP +This section considers the work needed to augment +.IR config 's +data base files for non-standard system facilities. +.I Config +uses a set of files that list the source modules that may be required +when building a system. +The data bases are taken from the directory in which +.I config +is run, normally /sys/conf. +Three such files may be used: +.IR files , +.IR files .machine, +and +.IR files .ident. +The first is common to all systems, +the second contains files unique to a single machine type, +and the third is an optional list of modules for use on a specific machine. +This last file may override specifications in the first two. +The format of the +.I files +file has grown somewhat complex over time. Entries are normally of +the form +.IP +.nf +.DT +\fIdir/source.c\fP \fItype\fP \fIoption-list\fP \fImodifiers\fP +.LP +for example, +.IP +.nf +.DT +\fIvaxuba/foo.c\fP \fBoptional\fP foo \fBdevice-driver\fP +.LP +The +.I type +is one of +.B standard +or +.BR optional . +Files marked as standard are included in all system configurations. +Optional file specifications include a list of one or more system +options that together require the inclusion of this module. +The options in the list may be either names of devices that may +be in the configuration file, +or the names of system options that may be defined. +An optional file may be listed multiple times with different options; +if all of the options for any of the entries are satisfied, +the module is included. +.PP +If a file is specified as a +.IR device-driver , +any special compilation options for device drivers will be invoked. +On the VAX this results in the use of the +.B \-i +option for the C optimizer. This is required when pointer references +are made to memory locations in the VAX I/O address space. +.PP +Two other optional keywords modify the usage of the file. +.I Config +understands that certain files are used especially for +kernel profiling. These files are indicated in the +.I files +files with a +.I profiling-routine +keyword. For example, the current profiling subroutines +are sequestered off in a separate file with the following +entry: +.IP +.nf +.DT +\fIsys/subr_mcount.c\fP \fBoptional\fP \fBprofiling-routine\fP +.fi +.LP +The +.I profiling-routine +keyword forces +.I config +not to compile the source file with the +.B \-pg +option. +.PP +The second keyword which can be of use is the +.I config-dependent +keyword. This causes +.I config +to compile the indicated module with the global configuration +parameters. This allows certain modules, such as +.I machdep.c +to size system data structures based on the maximum number +of users configured for the system. +.NH 2 +Adding device drivers to 4.4BSD +.PP +The I/O system and +.I config +have been designed to easily allow new device support to be added. +The system source directories are organized as follows: +.DS +.TS +lw(1.0i) l. +/sys/h machine independent include files +/sys/sys machine-independent system source files +/sys/conf site configuration files and basic templates +/sys/net network-protocol-independent, but network-related code +/sys/netinet DARPA Internet code +/sys/netimp IMP support code +/sys/netns Xerox NS code +/sys/vax VAX-specific mainline code +/sys/vaxif VAX network interface code +/sys/vaxmba VAX MASSBUS device drivers and related code +/sys/vaxuba VAX UNIBUS device drivers and related code +.TE +.DE +.PP +Existing block and character device drivers for the VAX +reside in ``/sys/vax'', ``/sys/vaxmba'', and ``/sys/vaxuba''. Network +interface drivers reside in ``/sys/vaxif''. Any new device +drivers should be placed in the appropriate source code directory +and named so as not to conflict with existing devices. +Normally, definitions for things like device registers are placed in +a separate file in the same directory. For example, the ``dh'' +device driver is named ``dh.c'' and its associated include file is +named ``dhreg.h''. +.PP +Once the source for the device driver has been placed in a directory, +the file ``/sys/conf/files.machine'', and possibly +``/sys/conf/devices.machine'' should be modified. The +.I files +files in the conf directory contain a line for each C source or binary-only +file in the system. Those files which are machine independent are +located in ``/sys/conf/files,'' while machine specific files +are in ``/sys/conf/files.machine.'' The ``devices.machine'' file +is used to map device names to major block device numbers. If the device +driver being added provides support for a new disk +you will want to modify this file (the format is obvious). +.PP +In addition to including the driver in the +.I files +file, it must also be added to the device configuration tables. These +are located in ``/sys/vax/conf.c'', or similar for machines other than +the VAX. If you don't understand what to add to this file, you should +study an entry for an existing driver. +Remember that the position in the +device table specifies the major device number. +The block major number is needed in the ``devices.machine'' file +if the device is a disk. |