diff options
author | uqs <uqs@FreeBSD.org> | 2010-12-04 10:11:20 +0000 |
---|---|---|
committer | uqs <uqs@FreeBSD.org> | 2010-12-04 10:11:20 +0000 |
commit | 9242c645f81d22058934688725f1fff0bc88cb64 (patch) | |
tree | a39140e4d881fbba4f04ac77974bfbb05df9d360 /usr.sbin/config/SMM.doc/3.t | |
parent | 06cd6f2bc1f94f941b57ef92ed6445529822669b (diff) | |
download | FreeBSD-src-9242c645f81d22058934688725f1fff0bc88cb64.zip FreeBSD-src-9242c645f81d22058934688725f1fff0bc88cb64.tar.gz |
Move most of the remaining USD/PSD/SMM papers into share/doc
Diffstat (limited to 'usr.sbin/config/SMM.doc/3.t')
-rw-r--r-- | usr.sbin/config/SMM.doc/3.t | 299 |
1 files changed, 0 insertions, 299 deletions
diff --git a/usr.sbin/config/SMM.doc/3.t b/usr.sbin/config/SMM.doc/3.t deleted file mode 100644 index e0b6234..0000000 --- a/usr.sbin/config/SMM.doc/3.t +++ /dev/null @@ -1,299 +0,0 @@ -.\" 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. -.\" -.\" @(#)3.t 8.1 (Berkeley) 6/8/93 -.\" -.\".ds RH "System Building Process -.ne 2i -.NH -SYSTEM BUILDING PROCESS -.PP -In this section we consider the steps necessary to build a bootable system -image. We assume the system source is located in the ``/sys'' directory -and that, initially, the system is being configured from source code. -.PP -Under normal circumstances there are 5 steps in building a system. -.IP 1) 3 -Create a configuration file for the system. -.IP 2) 3 -Make a directory for the system to be constructed in. -.IP 3) 3 -Run -.I config -on the configuration file to generate the files required -to compile and load the system image. -.IP 4) -Construct the source code interdependency rules for the -configured system with -.I make depend -using -.IR make (1). -.IP 5) -Compile and load the system with -.IR make . -.PP -Steps 1 and 2 are usually done only once. When a system configuration -changes it usually suffices to just run -.I config -on the modified configuration file, rebuild the source code dependencies, -and remake the system. Sometimes, -however, configuration dependencies may not be noticed in which case -it is necessary to clean out the relocatable object files saved -in the system's directory; this will be discussed later. -.NH 2 -Creating a configuration file -.PP -Configuration files normally reside in the directory ``/sys/conf''. -A configuration file is most easily constructed by copying an -existing configuration file and modifying it. The 4.4BSD distribution -contains a number of configuration files for machines at Berkeley; -one may be suitable or, in worst case, a copy -of the generic configuration file may be edited. -.PP -The configuration file must have the same name as the directory in -which the configured system is to be built. -Further, -.I config -assumes this directory is located in the parent directory of -the directory in which it -is run. For example, the generic -system has a configuration file ``/sys/conf/GENERIC'' and an accompanying -directory named ``/sys/GENERIC''. -Although it is not required that the system sources and configuration -files reside in ``/sys,'' the configuration and compilation procedure -depends on the relative locations of directories within that hierarchy, -as most of the system code and the files created by -.I config -use pathnames of the form ``../''. -If the system files are not located in ``/sys,'' -it is desirable to make a symbolic link there for use in installation -of other parts of the system that share files with the kernel. -.PP -When building the configuration file, be sure to include the items -described in section 2. In particular, the machine type, -cpu type, timezone, system identifier, maximum users, and root device -must be specified. The specification of the hardware present may take -a bit of work; particularly if your hardware is configured at non-standard -places (e.g. device registers located at funny places or devices not -supported by the system). Section 4 of this document -gives a detailed description of the configuration file syntax, -section 5 explains some sample configuration files, and -section 6 discusses how to add new devices to -the system. If the devices to be configured are not already -described in one of the existing configuration files you should check -the manual pages in section 4 of the UNIX Programmers Manual. For each -supported device, the manual page synopsis entry gives a -sample configuration line. -.PP -Once the configuration file is complete, run it through -.I config -and look for any errors. Never try and use a system which -.I config -has complained about; the results are unpredictable. -For the most part, -.IR config 's -error diagnostics are self explanatory. It may be the case that -the line numbers given with the error messages are off by one. -.PP -A successful run of -.I config -on your configuration file will generate a number of files in -the configuration directory. These files are: -.IP \(bu 3 -A file to be used by \fImake\fP\|(1) -in compiling and loading the system, -.IR Makefile . -.IP \(bu 3 -One file for each possible system image for this machine, -.IR swapxxx.c , -where -.I xxx -is the name of the system image, -which describes where swapping, the root file system, and other -miscellaneous system devices are located. -.IP \(bu 3 -A collection of header files, one per possible device the -system supports, which define the hardware configured. -.IP \(bu 3 -A file containing the I/O configuration tables used by the system -during its -.I autoconfiguration -phase, -.IR ioconf.c . -.IP \(bu 3 -An assembly language file of interrupt vectors which -connect interrupts from the machine's external buses to the main -system path for handling interrupts, -and a file that contains counters and names for the interrupt vectors. -.PP -Unless you have reason to doubt -.IR config , -or are curious how the system's autoconfiguration scheme -works, you should never have to look at any of these files. -.NH 2 -Constructing source code dependencies -.PP -When -.I config -is done generating the files needed to compile and link your system it -will terminate with a message of the form ``Don't forget to run make depend''. -This is a reminder that you should change over to the configuration -directory for the system just configured and type ``make depend'' -to build the rules used by -.I make -to recognize interdependencies in the system source code. -This will insure that any changes to a piece of the system -source code will result in the proper modules being recompiled -the next time -.I make -is run. -.PP -This step is particularly important if your site makes changes -to the system include files. The rules generated specify which source code -files are dependent on which include files. Without these rules, -.I make -will not recognize when it must rebuild modules -due to the modification of a system header file. -The dependency rules are generated by a pass of the C preprocessor -and reflect the global system options. -This step must be repeated when the configuration file is changed -and -.I config -is used to regenerate the system makefile. -.NH 2 -Building the system -.PP -The makefile constructed by -.I config -should allow a new system to be rebuilt by simply typing ``make image-name''. -For example, if you have named your bootable system image ``kernel'', -then ``make kernel'' -will generate a bootable image named ``kernel''. Alternate system image names -are used when the root file system location and/or swapping configuration -is done in more than one way. The makefile which -.I config -creates has entry points for each system image defined in -the configuration file. -Thus, if you have configured ``kernel'' to be a system with the root file -system on an ``hp'' device and ``hkkernel'' to be a system with the root -file system on an ``hk'' device, then ``make kernel hkkernel'' will generate -binary images for each. -As the system will generally use the disk from which it is loaded -as the root filesystem, separate system images are only required -to support different swap configurations. -.PP -Note that the name of a bootable image is different from the system -identifier. All bootable images are configured for the same system; -only the information about the root file system and paging devices differ. -(This is described in more detail in section 4.) -.PP -The last step in the system building process is to rearrange certain commonly -used symbols in the symbol table of the system image; the makefile -generated by -.I config -does this automatically for you. -This is advantageous for programs such as -\fInetstat\fP\|(1) and \fIvmstat\fP\|(1), -which run much faster when the symbols they need are located at -the front of the symbol table. -Remember also that many programs expect -the currently executing system to be named ``/kernel''. If you install -a new system and name it something other than ``/kernel'', many programs -are likely to give strange results. -.NH 2 -Sharing object modules -.PP -If you have many systems which are all built on a single machine -there are at least two approaches to saving time in building system -images. The best way is to have a single system image which is run on -all machines. This is attractive since it minimizes disk space used -and time required to rebuild systems after making changes. However, -it is often the case that one or more systems will require a separately -configured system image. This may be due to limited memory (building -a system with many unused device drivers can be expensive), or to -configuration requirements (one machine may be a development machine -where disk quotas are not needed, while another is a production machine -where they are), etc. In these cases it is possible -for common systems to share relocatable object modules which are not -configuration dependent; most of the modules in the directory ``/sys/sys'' -are of this sort. -.PP -To share object modules, a generic system should be built. Then, for -each system configure the system as before, but before recompiling and -linking the system, type ``make links'' in the system compilation directory. -This will cause the system -to be searched for source modules which are safe to share between systems -and generate symbolic links in the current directory to the appropriate -object modules in the directory ``../GENERIC''. A shell script, -``makelinks'' is generated with this request and may be checked for -correctness. The file ``/sys/conf/defines'' contains a list of symbols -which we believe are safe to ignore when checking the source code -for modules which may be shared. Note that this list includes the definitions -used to conditionally compile in the virtual memory tracing facilities, and -the trace point support used only rarely (even at Berkeley). -It may be necessary -to modify this file to reflect local needs. Note further that -interdependencies which are not directly visible -in the source code are not caught. This means that if you place -per-system dependencies in an include file, they will not be recognized -and the shared code may be selected in an unexpected fashion. -.NH 2 -Building profiled systems -.PP -It is simple to configure a system which will automatically -collect profiling information as it operates. The profiling data -may be collected with \fIkgmon\fP\|(8) and processed with -\fIgprof\fP\|(1) -to obtain information regarding the system's operation. Profiled -systems maintain histograms of the program counter as well as the -number of invocations of each routine. The \fIgprof\fP -command will also generate a dynamic call graph of the executing -system and propagate time spent in each routine along the arcs -of the call graph (consult the \fIgprof\fP documentation for elaboration). -The program counter sampling can be driven by the system clock, or -if you have an alternate real time clock, this can be used. The -latter is highly recommended, as use of the system clock will result -in statistical anomalies, and time spent in the clock routine will -not be accurately attributed. -.PP -To configure a profiled system, the -.B \-p -option should be supplied to \fIconfig\fP. -A profiled system is about 5-10% larger in its text space due to -the calls to count the subroutine invocations. When the system -executes, the profiling data is stored in a buffer which is 1.2 -times the size of the text space. The overhead for running a -profiled system varies; under normal load we see anywhere from 5-25% -of the system time spent in the profiling code. -.PP -Note that systems configured for profiling should not be shared as -described above unless all the other shared systems are also to be -profiled. |