kconfig(1M) kconfig(1M)NAME kconfig - tunes kernel parameters for work-load optimization SYNOPSIS kconfig [-a [-v] [-V]] [-nkernelfile] ARGUMENTS -a Lists the current values of the parameters in the kernel object file kernelfile. If the -a option is used, kconfig displays the parameters and exits. If the -a option is not used, kconfig reads standard input for a list of changes. -nkernelfile Specifies which kernel object file is being modified (the default is /unix). -v Produces verbose (commented) output. This option is used with the -a option. -V Prints the current version of the kernel object file kernelfile. This option is used with the -a option. DESCRIPTION kconfig manipulates an A/UX kernel file to read and set critical system parameters. This process is sometimes called kernel tuning, since obtaining optimal values is often an iterative process. Note: The easiest and safest way to adjust the A/UX kernel parameter NBUF (the size of the disk buffer cache) is through the Memory control panel selectable from the Control Panels item in the Apple menu, and then restarting the system. Only use the kconfig command if you need to set other system parameters and if you know the implications of any changes you make. Inadequate values for kernel parameters can cause system errors. The kconfig program can be used to either list or change several system parameters. For more information, see ``System Parameters'' later in the ``Description'' section. Note that kconfig does not change parameters of the running kernel, just those in the file specified (kernelfile). When the kernel is started up (as part of the startup process) these parameters are honored immediately, or are copied into main memory for subsequent use. For the changes to become effective, you must shut the system down and then restart the system. March 1993 1
kconfig(1M) kconfig(1M)You can specify one change per input line. The change must be in one of these forms: PARAM = value PARAM += value PARAM -= value In these forms, PARAM is one of the parameter names (listed later in the section ``System Parameters'') and value is either a decimal constant or a hexadecimal constant preceded by 0x. If you use the ``equals'' form, the parameter is given the value specified. If you use the ``minus-equals'' form, the parameter is decreased by the value given. If you use the ``plus-equals'' form, the parameter is increased by the value. If the value is not within a system-defined maximum and minimum range for the parameter, an error occurs and the kernel is not changed. Viewing the Supplied Kernel Parameters To obtain the kernel parameters that were established for a particular A/UX release available on CD-ROM, you can use the following steps. 1. Locate a running A/UX system that has a CD-ROM drive attached to it. If you need to, shut off your system, connect SCSI and power cables to a CD-ROM drive set to a free SCSI ID, turn the drive on and restart A/UX. 2 Locate the system software installer CD-ROM that contains the A/UX release and kernel you wish to query. Insert the CD-ROM in the drive. 3. From a CommandShell window enter the following commands as the root user, replacing scsi-id with the SCSI ID for the CD-ROM drive: mount -r -o nocats /dev/dsk/cscsi-idd0s0 /mnt kconfig -an /mnt/unix When finished, you should unmount the UNIX file system using umount: umount /mnt If the Finder is running, you should also drag the CD-ROM icon to the trash icon before ejecting the CD-ROM. By redirecting the output of the kconfig command to a file, you can capture the originally-supplied values for future 2 March 1993
kconfig(1M) kconfig(1M)reference. For example, you can use it as the basis for comparisons with similar data obtained from other kernel files using a file-comparing command such as sdiff. System Parameters The following system parameters are recognized by kconfig: Note: Not all of these parameters will necessarily be supported in future releases of the operating system. CDLIMIT Sets a limit upon the size of files that processes can create. Only this number of 512-byte blocks may be written to any file by any process owned by any user. See ulimit(2) for more information. CMASK Determines the systemwide default file-creation mask. In general, the value of CMASK is overridden by use of the umask command built into various shell programs. See csh(1), ksh(1), or sh(1) for more information. DUMPDEV Currently unused by the system. FLCKFIL Specifies the number of flock inode structures. When this threshold is exceeded, the error EMFILE is returned to the requesting program. FLCKREC Specifies the number of flock lock structures. When this threshold is exceeded, the error ENOSPC is returned to the requesting program. See flock(2) for more information. GETPGSHI Specifies the get-pages high limit, which is the free- memory high-water mark for the vhand daemon. When this threshold is exceeded, the system stops stealing pages from active processes. GETPGSHI should be greater than GETPGSLOW and less than about one-fourth of the total available memory. GETPGSLOW Specifies the get-pages low limit, which is the free- memory low-water mark for the vhand daemon. When this threshold is reached, vhand becomes active and starts stealing pages from active processes. If you increase the value, the daemon becomes more active. The value must be greater than 0 and less than GETPGSHI. March 1993 3
kconfig(1M) kconfig(1M)GETPGSMSK Specifies, when used by vhand, which pages to steal. It may be modified, but most changes are more educational than useful. Values in this parameter correspond to bits in the page-table entries. Each masked bit in the page-table entry must be set to 0 in order for the page to be taken by vhand. The current setting is as follows: PG_NDREF | PG_REF This setting is established in /usr/include/sys/page.h. By including the modified bit (PG_M), you could prevent vhand from stealing any pages with the modified bit on. MAXCORE Sets the space available from the kernel's internal heap for its own use. Most of the pool of data structures used for access to files served from a remote host (through NFS) is allocated from this space. Also allocated from this space are data structures used by used by generic disk devices and by the system's name-lookup code. If the message ``panic: kmem_alloc'' appears and the system halts, you should increase the value of MAXCORE. MAXFC Specifies the maximum number of pages that may be placed on the free list at one time. Increasing the number may allow for faster handling of page faults when a process needs more memory, but it may also reduce the working set of applications so that page faults occur more frequently. MAXHEADER Limits the number of allocations possible from the kernel's internal heap. If the console error message ``panic: getfreehdr'' appears, this value should be increased. MAXPMEM Specifies the maximum physical memory to use. If this parameter is set to be 0, the system uses all available physical memory. This value should remain zero unless you are testing alternate memory configurations. MAXSC Specifies the maximum number of pages that can be written to the swap device in a single operation. Increasing this number increases the I/O overhead spent in swapping, but decreasing the value may reduce the amount of free memory available when a page fault 4 March 1993
kconfig(1M) kconfig(1M)occurs. MAXUMEM Determines the maximum pages allowed for the virtual address space of user processes. This number may range from about 30 to 0x20000. Small values of MAXUMEM may render unusable software that is normally taken for granted. MAXUP Determines the maximum number of concurrent processes for each user ID. The root account is exempt from this restriction. This limit is based on the user ID, not on the login terminal. If ten people are logged in using a single user ID, the limit could be reached quickly. Normally the value of MAXUP is at least 10 percent smaller than that of NPROC. MINARMEM Sets the minimum number of pages of physical (``resident'') memory reserved for user text and data segments in order to avoid deadlock. Values might range from 10 to 40. MINASMEM Defines the minimum number of pages of system (swap + resident) memory reserved for system purposes and therefore unavailable for the text and data segments of user processes. Normally the value of MINASMEM is greater than that of MINARMEM. NBUF Specifies the number of disk I/O buffers to allocate. These buffers form a data cache for information read or written to file systems. Another way you can set the size of the disk buffer cache is through the Memory control panel while A/UX is running, which still takes effect only after you restart the system. The higher the value, the higher the ``cache hit ratio,'' but increasing the number of buffers also reduces the memory available for applications, making paging more likely to occur in the first place. The number of system buffers normally ranges from 100 to 1500. When the value of NBUF is greater than 0, the size of the cache in bytes is the product of the value of NBUF and the value of SBUFSIZE. However, upon startup the kernel will verify that this value is a reasonable one. If you set it unreasonably, either from the Memory control panel or from the kconfig command line, the kernel will size the buffer according to its own algorithm. In such a case, kconfig continues to report the value of NBUF according to how it was March 1993 5
kconfig(1M) kconfig(1M)set, despite the fact that it may be an ignored value. Systems with a single user might conceivably use more buffers than systems that typically have numerous memory-intensive applications running. When 0 is the established value, the system dynamically calculates the number of buffers as 10 percent of free memory at boot time. When -1 is the established value, the system dynamically calculates the number of buffers on a sliding basis, up to 50 percent of the free memory at boot time, depending on the amount of RAM memory installed. NCALL Specifies the size of the timeout table. Device drivers may need to use slots from this table to arrange for functions to be called at a later time. If many add-on drives, such as for NuBus(TM) peripherals, are added to the system, this value might require an increase. If the timeout table is exhausted, the message ``timeout table overflow'' is printed, and the system halts execution. NCLIST Specifies the maximum number of system command lists (CLIST areas). A CLIST is a memory area used by driver software for terminals, built-in modems, or serial printer connections. Five to ten CLISTs are required by each active terminal. When no CLISTs are available, incoming characters are lost. Each CLIST requires 64 bytes of data and a 12-byte header. The console and some optional serial cards use the STREAM interface and do not require CLISTs. NFILE Determines the size of the system file-table pool. Each entry represents an open file in use by some process. When no space is available in the file table, the message ``file: table is full'' is printed on the system console. The values of NFILE and NINODE are typically set the same. NFLOCK Specifies the number of system-wide file locks (see locking(2)). Each area of a locked file requires one of these table entries. If the table is exhausted, the error EDEADLOCK is returned to the application that made the lock request. NINODE Sets the size of the system inode table. Each table 6 March 1993
kconfig(1M) kconfig(1M)entry represents an in-core inode being used for an open file, an open working directory, or a mount point. The opening of a file served from a remote host (through NFS) does not require allocation of a local inode, so it should not be considered when adjusting the value of NINODE. Normally the value of NINODE is greater than or equal to the value of NFILE. When all inodes in the system inode table are used, the message ``inode: table is full'' is printed. NMBUFS Allocates a number of buffers for networking. Each buffer requires 256 bytes, of which 240 are available for data. As few as 100 buffers (mbufs) may be used for basic networking. When you connect the computer to a large network (resulting in large routing tables), when you run X11 with multiple windows, or when you run NFS, you should increase this value. As a guide, each NFS daemon may transfer 8 KB of data. Allocating (8192*n_daemons)/240 provides a starting point in the calculation. The command netstat -m can be used to determine the number of mbufs in use. If the console error message ``m_expand returning 0'' appears, or if the system halts after displaying the message ``panic: out of mbufs,'' this value should be increased. NMOUNT Specifies the size of the file system mount table. The parameter does not affect the number of remotely mounted network file systems allowed. If numerous disk devices containing many file-system partitions are present, the mount table may need to be increased. NPBUF Specifies how many physical I/O buffer headers to allocate. One header is needed for each simultaneous read or write of a ``character-special'' disk or tape device, or for each concurrent swap I/O operation. NPROC Specifies the total number of processes in the system. In general, each executing command, application, or system daemon is a process. Each user of the system, or each active layer or window, generally uses between two and eight simultaneous processes. When no processes are available, the message ``proc: table is full'' is printed on the system console. NPTY Determines the total number of possible pseudoterminal devices (that is, /dev/pty*). Special files must still be created in the /dev directory for pseudoterminals to be used. If more than the allocated number of March 1993 7
kconfig(1M) kconfig(1M)pseudoterminals are created, the error code ``No such device or address'' is returned by an open operation (see open(2)) for any of the unallocated device files. NQUEUE Defines the maximum number of Stream queues. Each stream head, driver, and module pushed onto a stream creates two queues. Typically this parameter is set to eight times the number of stream heads. The allocation of stream blocks determines the availability of buffer space used by STREAMS devices. The optimal allocation depends on the types of devices present in the system. It is expected that the installation scripts for devices using STREAMS will include the necessary commands to increase the number of blocks allocated. If too few blocks of the size required by a driver are present, the system may lose input characters. NBLK4096 Allocates a number of 4 KB stream blocks. NBLK2048 Allocates a number of 2 KB stream blocks. NBLK1024 Allocates a number of 1 KB stream blocks. NBLK512 Allocates a number of 512-byte stream blocks. NBLK256 Allocates a number of 256-byte stream blocks. NBLK128 Allocates a number of 128-byte stream blocks. NBLK64 Allocates a number of 64-byte stream blocks. NBLK16 Allocates a number of 16-byte stream blocks. NBLK4 Allocates a number of 4-byte stream blocks. The keyboard and terminal devices connected through a serial port require this type of data resource. NREGION Defines the number of memory regions available to all processes in the system. A typical process has a 8 March 1993
kconfig(1M) kconfig(1M)memory region for its data, a memory region for its stack, and a memory region for its program text. The text region is shared by all processes executing the same instructions. If the region table is exhausted, the message ``Region table overflow'' is printed on the system console. NSPTMAP Allocates table entries that are used to map the system page-table entries. If the message ``sptreserve: No kernel virtual space'' is printed, the system has exhausted the map. NSTREAM Determines the maximum number of stream heads possible in the system. The console, AppleTalk, and the shell layering by the console are examples of streams. The number of streams required might range from 8 to 48. PIPEDEV Determines the logical disk device for temporary pipe- file space. The specification is the same format as that of ROOTDEV. If it is set to 0xffff, the value passed from the A/UX Startup application is used (see StartupShell(8)). ROOTDEV Determines the logical disk device containing the root file system. This must be a device number as used internally by the kernel. The major number is in the upper byte, and the minor number is in the lower byte. If the value is 0xffff, then the value passed from the A/UX Startup application is used (see StartupShell(8)). SBUFSIZE Determines the size of system I/O logical block size on disk devices. The size is configurable. The SBUFSIZE parameter determines the size of in-core buffers allocated for the buffer cache. The number must be an even multiple of 512 bytes and should be large enough to accept the largest block size of all active file systems. When the system buffer size is increased, the total number of buffers should be decreased, assuming the same amount of memory is used for the buffer cache. SLICE Specifies the maximum time slice (in ticks) available to a process before it is considered for rescheduling. At the end of the time slice, the active process is suspended, and the system searches for a process with a higher CPU priority. If no higher-priority process exists, the previous process is given another slice. March 1993 9
kconfig(1M) kconfig(1M)(There are 60 ticks in a second.) SWAPCNT Specifies the size of the swap area, in terms of 512- byte blocks within the swap partition, if nonzero. The first partition the system can identify as a swap partition at startup is used for swapping purposes; additional swap partitions can be added through the swap command (which you can place inside of a startup file such as sysinitrc so that the swap space is increased upon entry into multi-user mode). If the value of SWAPCNT is set to 0, all of the space in the swap partition is used for swap space. The system warns you if it is running short of swap space. For A/UX systems, the swap space normally corresponds to a Swap Partition created with Apple HD SC Setup. Accordingly, SWAPCNT should always be set to 0. SWAPDEV Specifies the logical disk device used for swap space. The specification is the same format as that of ROOTDEV. If it is set to 0xffff, the value passed from the A/UX Startup application is used (see StartupShell(8)). SWAPLO Specifies the starting disk address where the swap area begins in terms of the number of 512-byte blocks to skip at the beginning of the swap partition. A nonzero value would be required if these blocks were to be used for some other purpose. Another way to similarly reserve a region of the disk area for special use is to create a discrete partition for it. VHANDR Specifies in seconds the maximum rate at which vhand may run if the free memory is less than VHANDL, as explained for VHNDFRAC following. If you increase the value, the daemon becomes less active. The value should be between 1 and 10. VHNDFRAC Allows a degree of control over the virtual memory system. The virtual memory system depends on the activity of the paging daemon vhand to free memory by paging unused memory to the swap-disk device. The algorithm writes out to disk pages that have not been used for some time. If the system is not active, there is plenty of free memory and no work for vhand. The value of VHNDFRAC and other tuning parameters allow an adventurous system administrator to fine-tune performance. 10 March 1993
kconfig(1M) kconfig(1M)The vhand fraction is used to determine the initial value of the system variable VHANDL. If free memory falls below the VHANDL value, the vhand paging daemon is awakened to begin aging and monitoring the resident set of virtual memory pages. At system startup time, VHANDL is set as follows: vhandl=MAX(maxmem/VHANDFRAC,GETPGSHI) In this calculation, maxmem is the available free memory at startup time and GETPGSHI is the free-memory high-water mark, described earlier. Normally VHANDFRAC is set to 16. FILES /etc/kconfig Executable file /unix File expected to contain a kernel SEE ALSO dp(1M), reboot(1M), shutdown(1M), swap(1M), StartupShell(8) flock(2), locking(2), open(2), pty(7) in A/UX Programmer's Reference A/UX Local System Administration March 1993 11