diff --git a/share/doc/smm/config/0.t b/share/doc/smm/config/0.t index 304e259d5a64..0a227ed33db2 100644 --- a/share/doc/smm/config/0.t +++ b/share/doc/smm/config/0.t @@ -1,4 +1,4 @@ -.\" $NetBSD: 0.t,v 1.2 2014/07/06 05:16:18 dholland Exp $ +.\" $NetBSD: 0.t,v 1.3 2014/07/06 05:32:30 dholland Exp $ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -76,7 +76,8 @@ configuration files and how to configure systems with non-standard hardware configurations. Sections describing the preferred way to add new code to the system and how the system's autoconfiguration -process operates are included. An appendix +process operates are included. +An appendix contains a summary of the rules used by the system in calculating the size of system data structures, and also indicates some of the standard system size diff --git a/share/doc/smm/config/1.t b/share/doc/smm/config/1.t index b2ca5f94272d..019748844dac 100644 --- a/share/doc/smm/config/1.t +++ b/share/doc/smm/config/1.t @@ -1,4 +1,4 @@ -.\" $NetBSD: 1.t,v 1.2 2014/07/06 05:16:18 dholland Exp $ +.\" $NetBSD: 1.t,v 1.3 2014/07/06 05:32:30 dholland Exp $ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -51,12 +51,14 @@ in a single, easy to understand, file. This document describes the content and format of system configuration files and the rules which must be followed when creating -these files. Example configuration files are constructed +these files. +Example configuration files are constructed and discussed. .PP Later sections suggest guidelines to be used in modifying system source and explain some of the inner workings of the -autoconfiguration process. Appendix D summarizes the rules +autoconfiguration process. +Appendix D summarizes the rules used in calculating the most important system data structures and indicates some inherent system data structure size limitations (and how to go about modifying them). diff --git a/share/doc/smm/config/2.t b/share/doc/smm/config/2.t index 72dfab4972b0..2fb01f929197 100644 --- a/share/doc/smm/config/2.t +++ b/share/doc/smm/config/2.t @@ -1,4 +1,4 @@ -.\" $NetBSD: 2.t,v 1.2 2014/07/06 05:16:18 dholland Exp $ +.\" $NetBSD: 2.t,v 1.3 2014/07/06 05:32:30 dholland Exp $ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -56,7 +56,8 @@ available hardware .PP .I Config allows multiple system images to be generated from a single -configuration description. Each system image is configured +configuration description. +Each system image is configured for identical hardware, but may have different locations for the root file system and, possibly, other system devices. .NH 2 @@ -69,7 +70,8 @@ indicates if the system is going to operate on a DEC VAX-11\(dg computer, \(dg DEC, VAX, UNIBUS, MASSBUS and MicroVAX are trademarks of Digital Equipment Corporation. .FE -or some other machine on which NetBSD operates. The machine type +or some other machine on which NetBSD operates. +The machine type is used to locate certain data files which are machine specific, and also to select rules used in constructing the resultant configuration files. @@ -85,7 +87,8 @@ be running on a VAX 8600, VAX-11/780, VAX-11/750, VAX-11/730 or MicroVAX II. the cpu designation for compatible machines introduced earlier.) Specifying more than one cpu type implies that the system should be configured to run -on any of the cpu's specified. For some types of machines this is not +on any of the cpu's specified. +For some types of machines this is not possible and .I config will print a diagnostic indicating such. @@ -95,11 +98,15 @@ System identification The .I "system identification" is a moniker attached to the system, and often the machine on which the -system is to run. For example, at Berkeley we have machines named Ernie -(Co-VAX), Kim (No-VAX), and so on. The system identifier selected is used to +system is to run. +For example, at Berkeley we have machines named Ernie +(Co-VAX), Kim (No-VAX), and so on. +The system identifier selected is used to create a global C ``#define'' which may be used to isolate system dependent -pieces of code in the kernel. For example, Ernie's Varian driver used -to be special cased because its interrupt vectors were wired together. The +pieces of code in the kernel. +For example, Ernie's Varian driver used +to be special cased because its interrupt vectors were wired together. +The code in the driver which understood how to handle this non-standard hardware configuration was conditionally compiled in only if the system was for Ernie. @@ -112,8 +119,10 @@ Timezone .PP The timezone in which the system is to run is used to define the information returned by the \fIgettimeofday\fP\|(2) -system call. This value is specified as the number of hours east -or west of GMT. Negative numbers indicate a value east of GMT. +system call. +This value is specified as the number of hours east +or west of GMT. +Negative numbers indicate a value east of GMT. The timezone specification may also indicate the type of daylight savings time rules to be applied. .NH 2 @@ -122,7 +131,8 @@ Maximum number of users The system allocates many system data structures at boot time based on the maximum number of users the system will support. This number is normally between 8 and 40, depending -on the hardware and expected job mix. The rules +on the hardware and expected job mix. +The rules used to calculate system data structures are discussed in Appendix D. .NH 2 @@ -130,7 +140,8 @@ Root file system location .PP When the system boots it must know the location of the root of the file system -tree. This location and the part(s) of the disk(s) to be used +tree. +This location and the part(s) of the disk(s) to be used for paging and swapping must be specified in order to create a complete configuration description. .I Config @@ -138,20 +149,25 @@ uses many rules to calculate default locations for these items; these are described in Appendix B. .PP When a generic system is configured, the root file system is left -undefined until the system is booted. In this case, the root file +undefined until the system is booted. +In this case, the root file system need not be specified, only that the system is a generic system. .NH 2 Hardware devices .PP When the system boots it goes through an .I autoconfiguration -phase. During this period, the system searches for all +phase. +During this period, the system searches for all those hardware devices -which the system builder has indicated might be present. This probing +which the system builder has indicated might be present. +This probing sequence requires certain pieces of information such as register -addresses, bus interconnects, etc. A system's hardware may be configured +addresses, bus interconnects, etc. +A system's hardware may be configured in a very flexible manner or be specified without any flexibility -whatsoever. Most people do not configure hardware devices into the +whatsoever. +Most people do not configure hardware devices into the system unless they are currently present on the machine, expect them to be present in the near future, or are simply guarding against a hardware @@ -160,8 +176,10 @@ extra disks in case an emergency requires moving one off a machine which has hardware problems). .PP The specification of hardware devices usually occupies the majority of -the configuration file. As such, a large portion of this document will -be spent understanding it. Section 6.3 contains a description of +the configuration file. +As such, a large portion of this document will +be spent understanding it. +Section 6.3 contains a description of the autoconfiguration process, as it applies to those planning to write, or modify existing, device drivers. .NH 2 @@ -180,10 +198,13 @@ Other than the mandatory pieces of information described above, it is also possible to include various optional system facilities or to modify system behavior and/or limits. For example, NetBSD can be configured to support binary compatibility for -programs built under Linux and FreeBSD. Also, optional support is provided +programs built under Linux and FreeBSD. +Also, optional support is provided for disk quotas and tracing the performance of the virtual memory -subsystem. Any optional facilities to be configured into -the system are specified in the configuration file. The resultant +subsystem. +Any optional facilities to be configured into +the system are specified in the configuration file. +The resultant files generated by .I config will automatically include the necessary pieces of the system. diff --git a/share/doc/smm/config/3.t b/share/doc/smm/config/3.t index 4b053cc73802..cd99b6acc992 100644 --- a/share/doc/smm/config/3.t +++ b/share/doc/smm/config/3.t @@ -1,4 +1,4 @@ -.\" $NetBSD: 3.t,v 1.2 2014/07/06 05:16:18 dholland Exp $ +.\" $NetBSD: 3.t,v 1.3 2014/07/06 05:32:30 dholland Exp $ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -38,7 +38,8 @@ 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 ``/usr/src'' directory +image. +We assume the system source is located in the ``/usr/src'' directory and that, initially, the system is being configured from source code. .PP Under normal circumstances there are 5 steps in building a system. @@ -61,11 +62,13 @@ using Compile and link the system with .IR make . .PP -Steps 1 and 2 are usually done only once. When a system configuration +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, +and remake the system. +Sometimes, however, configuration dependencies may not be noticed in which case it is necessary to clean out the object files saved in the system's directory; this will be discussed later. @@ -78,9 +81,11 @@ use. (For example, configuration files for 64-bit x86 machines live in ``/usr/src/sys/arch/amd64/conf''.) A configuration file is most easily constructed by copying an -existing configuration file and modifying it. The NetBSD distribution +existing configuration file and modifying it. +The NetBSD distribution contains assorted standard configuration files for different machine -types and varieties. Start with ``GENERIC'' if no other is more +types and varieties. +Start with ``GENERIC'' if no other is more appropriate. .PP The configuration file must have the same name as the directory in @@ -89,7 +94,8 @@ Further, .I config assumes this directory is located under the ``compile'' directory at the same level as the ``conf'' directory in which it -is run. For example, the generic 64-bit x86 +is run. +For example, the generic 64-bit x86 system has a configuration file ``/usr/src/sys/arch/amd64/conf/GENERIC'' and an accompanying directory named ``/usr/src/sys/arch/amd64/compile/GENERIC''. @@ -101,35 +107,43 @@ as most of the system code and the files created by use pathnames of the form ``../''. .PP When building the configuration file, be sure to include the items -described in section 2. In particular, the machine type, +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 +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 +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 +the system. +If the devices to be configured are not already described in one of the existing configuration files you should check -the section 4 manual pages. For each +the section 4 manual pages. +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 +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 +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: +the configuration directory. +These files are: .IP \(bu 3 A file to be used by \fImake\fP\|(1) in compiling and loading the system, @@ -180,8 +194,10 @@ the next time 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, +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. @@ -200,7 +216,8 @@ should allow a new system to be rebuilt by simply typing ``make''. .\" XXX is this still supported? 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 +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. @@ -213,7 +230,8 @@ 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; +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 @@ -227,7 +245,8 @@ This is advantageous for programs such as 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 ``/netbsd''. If you install +the currently executing system to be named ``/netbsd''. +If you install a new system and name it something other than ``/netbsd'', many programs are likely to give strange results. .NH 2 @@ -235,52 +254,67 @@ 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, +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 +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 +where they are), etc. +In these cases it is possible for common systems to share relocatable object modules which are not configuration dependent. .PP -To share object modules, a generic system should be built. Then, for +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, +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 +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 +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 +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 +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 +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 +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 +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 +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. @@ -289,9 +323,11 @@ 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 +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 +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 diff --git a/share/doc/smm/config/4.t b/share/doc/smm/config/4.t index 62ce2fc70e35..6c3c5c3efb21 100644 --- a/share/doc/smm/config/4.t +++ b/share/doc/smm/config/4.t @@ -1,4 +1,4 @@ -.\" $NetBSD: 4.t,v 1.2 2014/07/06 05:16:18 dholland Exp $ +.\" $NetBSD: 4.t,v 1.3 2014/07/06 05:32:30 dholland Exp $ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -38,7 +38,8 @@ CONFIGURATION FILE SYNTAX .PP In this section we consider the specific rules used in writing -a configuration file. A complete grammar for the input language +a configuration file. +A complete grammar for the input language can be found in Appendix A and may be of use if you should have problems with syntax errors. .PP @@ -59,8 +60,10 @@ cpu types, options, timezone, system identifier, and maximum users. Each is specified with a separate line in the configuration file. .IP "\fBmachine\fP \fItype\fP" .br -The system is to run on the machine type specified. No more than -one machine type can appear in the configuration file. Legal values +The system is to run on the machine type specified. +No more than +one machine type can appear in the configuration file. +Legal values are .B vax and @@ -112,16 +115,20 @@ The values must be enclosed in double quotes if they include numerals or begin with a dash. .IP "\fBtimezone\fP \fInumber\fP [ \fBdst\fP [ \fInumber\fP ] ]" .br -Specifies the timezone used by the system. This is measured in the +Specifies the timezone used by the system. +This is measured in the number of hours your timezone is west of GMT. -EST is 5 hours west of GMT, PST is 8. Negative numbers -indicate hours east of GMT. If you specify +EST is 5 hours west of GMT, PST is 8. +Negative numbers +indicate hours east of GMT. +If you specify \fBdst\fP, the system will operate under daylight savings time. An optional integer or floating point number may be included to specify a particular daylight saving time correction algorithm; the default value is 1, indicating the United States. Other values are: 2 (Australian style), 3 (Western European), -4 (Middle European), and 5 (Eastern European). See +4 (Middle European), and 5 (Eastern European). +See \fIgettimeofday\fP\|(2) and \fIctime\fP\|(3) for more information. .IP "\fBident\fP \fIname\fP" .br @@ -141,9 +148,11 @@ This number is used to size several system data structures. System image parameters .PP Multiple bootable images may be specified in a single configuration -file. The systems will have the same global configuration parameters +file. +The systems will have the same global configuration parameters and devices, but the location of the root file system and other -system specific devices may be different. A system image is specified +system specific devices may be different. +A system image is specified with a ``config'' line: .IP \fBconfig\fP\ \fIsysname\fP\ \fIconfig-clauses\fP @@ -151,7 +160,8 @@ with a ``config'' line: The .I sysname field is the name given to the loaded system image; almost everyone -names their standard system image ``netbsd''. The configuration clauses +names their standard system image ``netbsd''. +The configuration clauses are one or more specifications indicating where the root file system is located and the number and location of paging devices. The device used by the system to process argument lists during @@ -170,7 +180,8 @@ A configuration clause is one of the following \fBdumps\fP [ \fBon\fP ] \fIdump-device\fP \fBargs\fP [ \fBon\fP ] \fIarg-device\fP .LP -(the ``on'' is optional.) Multiple configuration clauses +(the ``on'' is optional.) +Multiple configuration clauses are separated by white space; .I config allows specifications to be continued across multiple lines @@ -188,18 +199,21 @@ as a device, unit, and file system partition; or underspecified in which case .I config will use builtin rules to select default unit numbers and file -system partitions. The defaulting rules are a bit complicated +system partitions. +The defaulting rules are a bit complicated as they are dependent on the overall system configuration. For example, the swap area need not be specified at all if the root device is specified; in this case the swap area is placed in the ``b'' partition of the same disk where the root -file system is located. Appendix B contains a complete list +file system is located. +Appendix B contains a complete list of the defaulting rules used in selecting system configuration devices. .PP The device names are translated to the appropriate major and minor device -numbers on a per-machine basis. A file, +numbers on a per-machine basis. +A file, ``/sys/conf/devices.machine'' (where ``machine'' is the machine type specified in the configuration file), is used to map a device name to its major block device number. @@ -216,25 +230,30 @@ This is done by substituting .IP \fBmajor\fP \fIx\fP \fBminor\fP \fIy\fP .LP -where the device name would normally be found. For example, +where the device name would normally be found. +For example, .IP .nf \fBconfig\fP kernel \fBroot\fP \fBon\fP \fBmajor\fP 99 \fBminor\fP 1 .fi .PP Normally, the areas configured for swap space are sized by the system -at boot time. If a non-standard size is to be used for one +at boot time. +If a non-standard size is to be used for one or more swap areas (less than the full partition), -this can also be specified. To do this, the +this can also be specified. +To do this, the device name specified for a swap area should have a ``size'' -specification appended. For example, +specification appended. +For example, .IP .nf \fBconfig\fP kernel \fBroot\fP \fBon\fP hp0 \fBswap\fP \fBon\fP hp0b \fBsize\fP 1200 .fi .LP would force swapping to be done in partition ``b'' of ``hp0'' and -the swap partition size would be set to 1200 sectors. A swap area +the swap partition size would be set to 1200 sectors. +A swap area sized larger than the associated disk partition is trimmed to the partition size. .PP @@ -247,14 +266,17 @@ Each device attached to a machine must be specified to .I config so that the system generated will know to probe for it during -the autoconfiguration process carried out at boot time. Hardware +the autoconfiguration process carried out at boot time. +Hardware specified in the configuration need not actually be present on -the machine where the generated system is to be run. Only the +the machine where the generated system is to be run. +Only the hardware actually found at boot time will be used by the system. .PP The specification of hardware devices in the configuration file parallels the interconnection hierarchy of the machine to be -configured. On the VAX, this means that a configuration file must +configured. +On the VAX, this means that a configuration file must indicate what MASSBUS and UNIBUS adapters are present, and to which \fInexi\fP they might be connected.* .FS @@ -265,14 +287,18 @@ to simplify device configuration. .FE Similarly, devices and controllers must be indicated as possibly being connected -to one or more adapters. A device description may provide a +to one or more adapters. +A device description may provide a complete definition of the possible configuration parameters or it may leave certain parameters undefined and make the system -probe for all the possible values. The latter allows a single +probe for all the possible values. +The latter allows a single device configuration list to match many possible physical -configurations. For example, a disk may be indicated as present +configurations. +For example, a disk may be indicated as present at UNIBUS adapter 0, or at any UNIBUS adapter which the system -locates at boot time. The latter scheme, termed +locates at boot time. +The latter scheme, termed .IR wildcarding , allows more flexibility in the physical configuration of a system; if a disk must be moved around for some reason, the system will @@ -290,9 +316,11 @@ A device specification takes one of the following forms: .LP A ``master'' is a MASSBUS tape controller; a ``controller'' is a disk controller, a UNIBUS tape controller, a MASSBUS adapter, or -a UNIBUS adapter. A ``device'' is an autonomous device which +a UNIBUS adapter. +A ``device'' is an autonomous device which connects directly to a UNIBUS adapter (as opposed to something -like a disk which connects through a disk controller). ``Disk'' +like a disk which connects through a disk controller). +``Disk'' and ``tape'' identify disk drives and tape drives connected to a ``controller'' or ``master.'' .PP @@ -310,14 +338,16 @@ unit number indicated on the front of something like a disk; the .I logical unit number is used to refer to the UNIX device, not -the physical unit number). For example, ``hp0'' is logical +the physical unit number). +For example, ``hp0'' is logical unit 0 of a MASSBUS storage device, even though it might be physical unit 3 on MASSBUS adapter 1. .PP The .I device-info clause specifies how the hardware is -connected in the interconnection hierarchy. On the VAX, +connected in the interconnection hierarchy. +On the VAX, UNIBUS and MASSBUS adapters are connected to the internal system bus through a \fInexus\fP. @@ -394,22 +424,27 @@ Certain device drivers require extra information passed to them at boot time to tailor their operation to the actual hardware present. The line printer driver, for example, needs to know how many columns are present on each non-standard line printer (i.e. a line printer -with other than 80 columns). The drivers for the terminal multiplexors +with other than 80 columns). +The drivers for the terminal multiplexors need to know which lines are attached to modem lines so that no one will -be allowed to use them unless a connection is present. For this reason, +be allowed to use them unless a connection is present. +For this reason, one last parameter may be specified to a .IR device , a .I flags -field. It has the syntax +field. +It has the syntax .IP \fBflags\fP \fInumber\fP .LP and is usually placed after the .I csr -specification. The +specification. +The .I number -is passed directly to the associated driver. The manual pages +is passed directly to the associated driver. +The manual pages in section 4 should be consulted to determine how each driver uses this value (if at all). Communications interface drivers commonly use the flags @@ -423,7 +458,8 @@ Pseudo-devices A number of drivers and software subsystems are treated like device drivers without any associated hardware. To include any of these pieces, a ``pseudo-device'' specification -must be used. A specification for a pseudo device takes the form +must be used. +A specification for a pseudo device takes the form .IP .DT .nf diff --git a/share/doc/smm/config/5.t b/share/doc/smm/config/5.t index 25858b9f9610..7615f7fea7be 100644 --- a/share/doc/smm/config/5.t +++ b/share/doc/smm/config/5.t @@ -1,4 +1,4 @@ -.\" $NetBSD: 5.t,v 1.1 2007/12/18 03:35:53 garbled Exp $ +.\" $NetBSD: 5.t,v 1.2 2014/07/06 05:32:30 dholland Exp $ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -81,13 +81,17 @@ file one step at a time. The first step is to fill in the global configuration parameters. The machine is a VAX, so the .I "machine type" -is ``vax''. We will assume this system will +is ``vax''. +We will assume this system will run only on this one processor, so the .I "cpu type" -is ``VAX780''. The options are empty since this is going to -be a ``vanilla'' VAX. The system identifier, as mentioned before, +is ``VAX780''. +The options are empty since this is going to +be a ``vanilla'' VAX. +The system identifier, as mentioned before, is ``ANSEL,'' and the maximum number of users we plan to support is -about 40. Thus the beginning of the configuration file looks like +about 40. +Thus the beginning of the configuration file looks like this: .DS .ta 1.5i 2.5i 4.0i @@ -102,7 +106,8 @@ maxusers 40 .DE .PP To this we must then add the specifications for three -system images. The first will be our standard system with the +system images. +The first will be our standard system with the root on ``hp0'' and swapping on the same drive as the root. The second will have the root file system in the same location, but swap space interleaved among drives on each controller. @@ -115,7 +120,8 @@ config hpkernel root on hp0 swap on hp0 and hp2 config genkernel swap generic .DE .PP -Finally, the hardware must be specified. Let us first just try +Finally, the hardware must be specified. +Let us first just try transcribing the information from Table 1. .DS .ta 1.5i 2.5i 4.0i @@ -138,14 +144,19 @@ device dh2 at uba0 csr 0160060 vector dhrint dhxint (Oh, I forgot to mention one panel of the terminal multiplexor has modem control, thus the ``dm0'' device.) .PP -This will suffice, but leaves us with little flexibility. Suppose -our first disk controller were to break. We would like to recable the +This will suffice, but leaves us with little flexibility. +Suppose +our first disk controller were to break. +We would like to recable the drives normally on the second controller so that all our disks could -still be used without reconfiguring the system. To do this we wildcard -the MASSBUS adapter connections and also the slave numbers. Further, +still be used without reconfiguring the system. +To do this we wildcard +the MASSBUS adapter connections and also the slave numbers. +Further, we wildcard the UNIBUS adapter connections in case we decide some time in the future to purchase another adapter to offload the single UNIBUS -we currently have. The revised device specifications would then be: +we currently have. +The revised device specifications would then be: .DS .ta 1.5i 2.5i 4.0i controller mba0 at nexus ? @@ -169,13 +180,17 @@ The completed configuration file for ANSEL is shown in Appendix C. VAX-11/750 with network support .PP Our VAX-11/750 system will be located on two 10Mb/s Ethernet -local area networks and also the DARPA Internet. The system +local area networks and also the DARPA Internet. +The system will have a MASSBUS drive for the root file system and two -UNIBUS drives. Paging is interleaved among all three drives. +UNIBUS drives. +Paging is interleaved among all three drives. We have sold our standard DEC terminal multiplexors since this -machine will be accessed solely through the network. This +machine will be accessed solely through the network. +This machine is not intended to have a large user community, it -does not have a great deal of memory. First the global parameters: +does not have a great deal of memory. +First the global parameters: .DS .ta 1.5i 2.5i 4.0i # @@ -192,9 +207,11 @@ options NS .DE .PP The multiple cpu types allow us to replace UCBVAX with a -more powerful cpu without reconfiguring the system. The +more powerful cpu without reconfiguring the system. +The value of 32 given for the maximum number of users is done to -force the system data structures to be over-allocated. That +force the system data structures to be over-allocated. +That is desirable on this machine because, while it is not expected to support many users, it is expected to perform a great deal of work. @@ -224,9 +241,11 @@ disk rk1 at hk0 drive 1 .DE .PP UCBVAX requires heavy interleaving of its paging area to keep up -with all the mail traffic it handles. The limiting factor on this +with all the mail traffic it handles. +The limiting factor on this system's performance is usually the number of disk arms, as opposed -to memory or cpu cycles. The extra UNIBUS controller, ``sc0'', +to memory or cpu cycles. +The extra UNIBUS controller, ``sc0'', is in case the MASSBUS controller breaks and a spare controller must be installed (most of our old UNIBUS controllers have been replaced with the newer MASSBUS controllers, so we have a number @@ -241,11 +260,14 @@ The connection to the Internet is through an IMP, this requires yet another .I pseudo-device (in addition to the actual hardware device used by the -IMP software). And, finally, there are the two Ethernet devices. +IMP software). +And, finally, there are the two Ethernet devices. These use a special protocol, the Address Resolution Protocol (ARP), -to map between Internet and Ethernet addresses. Thus, yet another +to map between Internet and Ethernet addresses. +Thus, yet another .I pseudo-device -is needed. The additional device specifications are show below. +is needed. +The additional device specifications are show below. .DS .ta 1.5i 2.5i 4.0i pseudo-device pty @@ -265,8 +287,10 @@ It should be noted in these examples that neither system was configured to use disk quotas or the 4.1BSD compatibility mode. To use these optional facilities, and others, we would probably clean out our current configuration, reconfigure the system, then -recompile and relink the system image(s). This could, of course, +recompile and relink the system image(s). +This could, of course, be avoided by figuring out which relocatable object files are affected by the reconfiguration, then reconfiguring and recompiling -only those files affected by the configuration change. This technique +only those files affected by the configuration change. +This technique should be used carefully. diff --git a/share/doc/smm/config/6.t b/share/doc/smm/config/6.t index 44bcd32713fd..93e39dac355e 100644 --- a/share/doc/smm/config/6.t +++ b/share/doc/smm/config/6.t @@ -1,4 +1,4 @@ -.\" $NetBSD: 6.t,v 1.2 2014/07/06 05:16:18 dholland Exp $ +.\" $NetBSD: 6.t,v 1.3 2014/07/06 05:32:30 dholland Exp $ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -63,7 +63,8 @@ it is best to bracket them with #endif .DE to allow your source to be easily distributed to others, and -also to simplify \fIdiff\fP\|(1) listings. It is +also to simplify \fIdiff\fP\|(1) listings. +It is recommended that you save the old code with something of the form: .DS @@ -98,7 +99,8 @@ 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 +file has grown somewhat complex over time. +Entries are normally of the form .IP .nf @@ -132,17 +134,20 @@ If a file is specified as a 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 +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 +kernel profiling. +These files are indicated in the .I files files with a .I profiling-routine -keyword. For example, the current profiling subroutines +keyword. +For example, the current profiling subroutines are sequestered off in a separate file with the following entry: .IP @@ -161,10 +166,12 @@ option. .PP The second keyword which can be of use is the .I config-dependent -keyword. This causes +keyword. +This causes .I config to compile the indicated module with the global configuration -parameters. This allows certain modules, such as +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. @@ -194,32 +201,40 @@ lw(1.0i) l. .DE .PP Existing block and character device drivers for the VAX -reside in ``/usr/src/sys/dev''. Any new device +reside in ``/usr/src/sys/dev''. +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 ``auixp'' +a separate file in the same directory. +For example, the ``auixp'' device driver is named ``auixp.c'' and its associated include file is named ``auixpreg.h''. There is also an ``auixpvar.h'' which contains data structures and other external declarations that the driver needs to expose. .PP Once the source for the device driver has been placed in a directory, -the file ``/usr/src/sys/conf/files'' should be modified. The +the file ``/usr/src/sys/conf/files'' 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 +file in the system. +Those files which are machine independent are located in ``/usr/src/sys/conf/files,'' while machine specific files for -the ``foo'' port are in ``/usr/src/sys/arch/foo/conf/files.foo.'' The ``devices.foo'' file -is used to map device names to major block device numbers. If the device +the ``foo'' port are in ``/usr/src/sys/arch/foo/conf/files.foo''. +The ``devices.foo'' 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 +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 +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. @@ -230,5 +245,6 @@ With the configuration information in place, your configuration file appropriately modified, and a system reconfigured and rebooted you should incorporate the shell commands needed to install the special files in the file system to the file ``/dev/MAKEDEV'' or -``/dev/MAKEDEV.local''. This is discussed in the document ``Installing +``/dev/MAKEDEV.local''. +This is discussed in the document ``Installing and Operating 4.4BSD''. diff --git a/share/doc/smm/config/a.t b/share/doc/smm/config/a.t index c62a42dc2b25..71c6cf8f7408 100644 --- a/share/doc/smm/config/a.t +++ b/share/doc/smm/config/a.t @@ -1,4 +1,4 @@ -.\" $NetBSD: a.t,v 1.1 2007/12/18 03:35:54 garbled Exp $ +.\" $NetBSD: a.t,v 1.2 2014/07/06 05:32:30 dholland Exp $ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -144,15 +144,18 @@ One or more alphabetics, either upper or lower case, and underscore, Approximately the C language specification for an integer number. That is, a leading ``0x'' indicates a hexadecimal value, a leading ``0'' indicates an octal value, otherwise the number is -expected to be a decimal value. Hexadecimal numbers may use either +expected to be a decimal value. +Hexadecimal numbers may use either upper or lower case alphabetics. .IP FPNUMBER .br -A floating point number without exponent. That is a number of the +A floating point number without exponent. +That is a number of the form ``nnn.ddd'', where the fractional component is optional. .LP In special instances a question mark, ``?'', can be substituted for -a ``NUMBER'' token. This is used to effect wildcarding in device +a ``NUMBER'' token. +This is used to effect wildcarding in device interconnection specifications. .LP Comments in configuration files are indicated by a ``#'' character diff --git a/share/doc/smm/config/b.t b/share/doc/smm/config/b.t index 9d7ae6b70756..55fdbec6b626 100644 --- a/share/doc/smm/config/b.t +++ b/share/doc/smm/config/b.t @@ -1,4 +1,4 @@ -.\" $NetBSD: b.t,v 1.1 2007/12/18 03:35:54 garbled Exp $ +.\" $NetBSD: b.t,v 1.2 2014/07/06 05:32:30 dholland Exp $ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -46,7 +46,8 @@ When \fIconfig\fP processes a ``config'' rule which does not fully specify the location of the root file system, paging area(s), device for system dumps, and device for argument list processing it applies a set of rules to -define those values left unspecified. The following list +define those values left unspecified. +The following list of rules are used in defaulting system devices. .IP 1) 3 If a root device is not specified, the swap @@ -89,7 +90,8 @@ first specified as a ``primary'' swap area which is always used. The remaining partitions are then interleaved into the paging system at the time a .IR swapon (2) -system call is made. This is normally done at boot time with +system call is made. +This is normally done at boot time with a call to .IR swapon (8) from the /etc/rc file. @@ -98,22 +100,29 @@ System dumps .PP System dumps are automatically taken after a system crash, provided the device driver for the ``dumps'' device supports -this. The dump contains the contents of memory, but not -the swap areas. Normally the dump device is a disk in +this. +The dump contains the contents of memory, but not +the swap areas. +Normally the dump device is a disk in which case the information is copied to a location at the -back of the partition. The dump is placed in the back of the +back of the partition. +The dump is placed in the back of the partition because the primary swap and dump device are commonly the same device and this allows the system to be rebooted without -immediately overwriting the saved information. When a dump has +immediately overwriting the saved information. +When a dump has occurred, the system variable \fIdumpsize\fP is set to a non-zero value indicating the size (in bytes) of -the dump. The \fIsavecore\fP\|(8) +the dump. +The \fIsavecore\fP\|(8) program then copies the information from the dump partition to a file in a ``crash'' directory and also makes a copy of the system which was running at the time of the crash (usually -``/kernel''). The offset to the system dump is defined in the +``/kernel''). +The offset to the system dump is defined in the system variable \fIdumplo\fP (a sector offset from -the front of the dump partition). The +the front of the dump partition). +The .I savecore program operates by reading the contents of \fIdumplo\fP, \fIdumpdev\fP, and \fIdumpmagic\fP from /dev/kmem, then comparing the value @@ -122,8 +131,10 @@ corresponding location in the dump area of the dump partition. If a match is found, .I savecore assumes a crash occurred and reads \fIdumpsize\fP from the dump area -of the dump partition. This value is then used in copying the -system dump. Refer to +of the dump partition. +This value is then used in copying the +system dump. +Refer to \fIsavecore\fP\|(8) for more information about its operation. .PP diff --git a/share/doc/smm/config/d.t b/share/doc/smm/config/d.t index 8b778594b9f3..befb0ee91a66 100644 --- a/share/doc/smm/config/d.t +++ b/share/doc/smm/config/d.t @@ -1,4 +1,4 @@ -.\" $NetBSD: d.t,v 1.1 2007/12/18 03:35:54 garbled Exp $ +.\" $NetBSD: d.t,v 1.2 2014/07/06 05:32:30 dholland Exp $ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -45,14 +45,16 @@ APPENDIX D. VAX KERNEL DATA STRUCTURE SIZING RULES Certain system data structures are sized at compile time according to the maximum number of simultaneous users expected, while others are calculated at boot time based on the -physical resources present, e.g. memory. This appendix lists +physical resources present, e.g. memory. +This appendix lists both sets of rules and also includes some hints on changing built-in limitations on certain data structures. .SH Compile time rules .PP The file \fI/sys/conf\|/param.c\fP contains the definitions of -almost all data structures sized at compile time. This file +almost all data structures sized at compile time. +This file is copied into the directory of each configured system to allow configuration-dependent rules and values to be maintained. (Each copy normally depends on the copy in /sys/conf, @@ -83,7 +85,8 @@ It is defined as .IP \fBninode\fP .br The maximum number of files in the file system which may be -active at any time. This includes files in use by users, as +active at any time. +This includes files in use by users, as well as directory files being read or written by the system and files associated with bound sockets in the UNIX IPC domain. It is defined as @@ -92,17 +95,20 @@ It is defined as .DE .IP \fBnfile\fP .br -The number of ``file table'' structures. One file +The number of ``file table'' structures. +One file table structure is used for each open, unshared, file descriptor. Multiple file descriptors may reference a single file table entry when they are created through a \fIdup\fP call, or as the -result of a \fIfork\fP. This is defined to be +result of a \fIfork\fP. +This is defined to be .DS 16 * (NPROC + 16 + MAXUSERS) / 10 + 32 .DE .IP \fBncallout\fP .br -The number of ``callout'' structures. One callout +The number of ``callout'' structures. +One callout structure is used per internal system event handled with a timeout. Timeouts are used for terminal delays, watchdog routines in device drivers, protocol timeout processing, etc. @@ -112,7 +118,8 @@ This is defined as .DE .IP \fBnclist\fP .br -The number of ``c-list'' structures. C-list structures are +The number of ``c-list'' structures. +C-list structures are used in terminal I/O, and currently each holds 60 characters. Their number is defined as .DS @@ -122,25 +129,32 @@ Their number is defined as .br The maximum number of pages which may be allocated by the network. This is defined as 256 (a quarter megabyte of memory) in /sys/h/mbuf.h. -In practice, the network rarely uses this much memory. It starts off +In practice, the network rarely uses this much memory. +It starts off by allocating 8 kilobytes of memory, then requesting more as -required. This value represents an upper bound. +required. +This value represents an upper bound. .IP \fBnquota\fP .br -The number of ``quota'' structures allocated. Quota structures -are present only when disc quotas are configured in the system. One -quota structure is kept per user. This is defined to be +The number of ``quota'' structures allocated. +Quota structures +are present only when disc quotas are configured in the system. +One +quota structure is kept per user. +This is defined to be .DS (MAXUSERS * 9) / 7 + 3 .DE .IP \fBndquot\fP .br -The number of ``dquot'' structures allocated. Dquot structures +The number of ``dquot'' structures allocated. +Dquot structures are present only when disc quotas are configured in the system. One dquot structure is required per user, per active file system quota. That is, when a user manipulates a file on a file system on which quotas are enabled, the information regarding the user's quotas on -that file system must be in-core. This information is cached, so +that file system must be in-core. +This information is cached, so that not all information must be present in-core all the time. This is defined as .DS @@ -159,19 +173,22 @@ pages of page tables. Its definition affects the size of many data structures allocated at boot time because it constrains the amount of virtual memory which may be addressed -by the running system. This is often the limiting factor +by the running system. +This is often the limiting factor in the size of the buffer cache, in which case a message is printed when the system configures at boot time. .SH Run-time calculations .PP The most important data structures sized at run-time are those used in -the buffer cache. Allocation is done by allocating physical memory +the buffer cache. +Allocation is done by allocating physical memory (and system virtual memory) immediately after the system has been started up; look in the file /sys/vax/machdep.c. The amount of physical memory which may be allocated to the buffer cache is constrained by the size of the system page tables, among -other things. While the system may calculate +other things. +While the system may calculate a large amount of memory to be allocated to the buffer cache, if the system page table is too small to map this physical @@ -179,13 +196,16 @@ memory into the virtual address space of the system, only as much as can be mapped will be used. .PP The buffer cache is comprised of a number of ``buffer headers'' -and a pool of pages attached to these headers. Buffer headers +and a pool of pages attached to these headers. +Buffer headers are divided into two categories: those used for swapping and -paging, and those used for normal file I/O. The system tries +paging, and those used for normal file I/O. +The system tries to allocate 10% of the first two megabytes and 5% of the remaining available physical memory for the buffer cache (where \fIavailable\fP does not count that space occupied by -the system's text and data segments). If this results in fewer +the system's text and data segments). +If this results in fewer than 16 pages of memory allocated, then 16 pages are allocated. This value is kept in the initialized variable \fIbufpages\fP so that it may be patched in the binary image (to allow tuning @@ -210,7 +230,8 @@ but no more than 256. System size limitations .PP As distributed, the sum of the virtual sizes of the core-resident -processes is limited to 256M bytes. The size of the text +processes is limited to 256M bytes. +The size of the text segment of a single process is currently limited to 6M bytes. It may be increased to no greater than the data segment size limit (see below) by redefining MAXTSIZ. @@ -252,7 +273,8 @@ Each page of system page tables allows 8 megabytes of user virtual memory. Because the file system block numbers are stored in page table \fIpg_blkno\fP entries, the maximum size of a file system is limited to -2^24 1024 byte blocks. Thus no file system can be larger than 8 gigabytes. +2^24 1024 byte blocks. +Thus no file system can be larger than 8 gigabytes. .PP The number of mountable file systems is set at 20 by the definition of NMOUNT in /sys/h/param.h.