 |
 |
 |
 |
|
|
|
||||
LynxOS User's Guide |
|||||
Customizing the Default LynxOS Kernel Configuration
This chapter explains how to customize the default LynxOS kernel configuration after initial installation.
Reasons for Kernel Customization
As users develop applications in the LynxOS environment, they may need to customize the LynxOS kernel for the following reasons:
- To tune the performance of a LynxOS native development system
- To remove functionality - such as superfluous device drivers - to conserve system resources
- To add functionality - such as networking support or a custom device driver - to support a specific application
By default, the LynxOS kernel on the bootable installation media contains all supported disk and terminal drivers for a given hardware architecture. This allows a single bootable disk/CD-ROM to load LynxOS for initial installation on a wide range of hardware configurations.
To enable LynxOS kernel customization for optimal performance, functionality, and/or size on any given system, during its initial installation, users must make some basic configuration choices. These include the device from which distribution media are to be read, the disk/partition onto which data is loaded, adding networking support, and so on.
To facilitate user's customization decisions, all LynxOS kernel files are located in the /sys directory. This centralized location of kernel files allows users to build customized LynxOS kernels quickly and easily.
Customizing for Performance
If LynxOS is being used as a primary development system, it is advantageous to customize the kernel for improved performance.
The following are some of the common features that can be customized for enhanced performance:
- Total number of simultaneously-mountable file systems
- Size of the disk cache
- Maximum number of available processes
Customizing for Size
A user's application environment may have size and memory constraints that make it critical to customize the LynxOS kernel. A kernel's size can be reduced by performing either or both of these tasks:
For example, LynuxWorks creates a bootable LynxOS kernel image that fits onto a high-density floppy for installation onto certain x86 systems. LynuxWorks customizes the boot kernel so that the kernel image, certain installation utilities (LynuxWorks installit application), and the RAM disk file system all fit within 1.44 MB.
Customizing for Functionality
The third common scenario involves customizing the functionality of the LynxOS kernel. This includes adding or removing the following components:
Users may also need to add their own, custom device drivers for a particular application.
This chapter describes the structure of the LynxOS kernel directory and the process for adding custom drivers to the build environment. For detailed information on developing custom device drivers, see Writing Device Drivers for LynxOS.
Overview of the /sys Directory
The LynxOS /sys directory contains all the scripts, library archives, and platform-specific files that users need to customize and rebuild a LynxOS kernel. The /sys directory has the following file structure:
For information on the contents, functionality, and building a debug version of a kernel library file, see "Creating a Kernel for Debugging".
Of all the directories in the /sys directory, users are most likely to modify files in the /bsp.xxx directory, as accessed through the /sys/lynx.os symbolic link. Users can, however, also modify files in the following /sys directories:
However, these files should only be modified when adding new drivers or when the functionality of a specific driver needs to be changed.
Accessing and Modifying the Main Kernel Directory
The main directory for customizing and rebuilding a LynxOS kernel is accessed through /sys/lynx.os. It is a symbolic link to the directory bsp.xxx, where xxx represents the Board Support Package (BSP) that supports the targeted hardware (that is, the configuration on which the custom application is to be deployed).
The symbolic link from lynx.os to bsp.xxx provides the flexibility to add support for target hardware variants, while maintaining a consistent build environment and access to supporting scripts via the /sys/lynx.os path.
Overview of /sys/lynx.os
The /sys/lynx.os directory contains the following files and subdirectories:
Rebuilding a Kernel with the make Utility
To rebuild a kernel, change directory to the /sys/lynx.os directory, and run the make utility with a specified Makefile rule (see Table 74 "/sys/lynx.os Makefile Rules"), using the following syntax:
The following Makefile rules are defined in /sys/lynx.os/Makefile:
Incorporating Changes Made in /sys/devices into the Kernel
To incorporate changes made in /sys/devices into the kernel, perform the following steps:
- Add or update the appropriate device file to the /sys/devices directory.
- Rebuild the kernel. For example:
Functionality Scripts
Users can also use the scripts in /usr/bin to install or remove the following major functional modules:
For example, to add support for NFS, enter the following command:
To remove SKDB support from the kernel, enter the following command:
To add support for TCPIP (IPv4 and extras), enter the following command:
Please note that if Install.tcpip6 is entered in place of Install.tcpip, you will add support for IPv6 and IPSec to the kernel.
Adding/Removing Device Drivers with CONFIG.TBL
The CONFIG.TBL file controls the device drivers that are inserted into the kernel at build time. Each driver has a one line entry in this file. Inserting the comment character (#) in front of the line deactivates the given device driver. For example, the code fragment below shows two lines from /sys/lynx.os/CONFIG.TBL on a LynxOS x86 system:
This fragment indicates that the LynxOS kernel built with this CONFIG.TBL contains a device driver for the secondary IDE controller. To remove this device driver, modify the lines in CONFIG.TBL as shown below:
Similarly to enable support for TCPIP6, the following lines from CONFIG.TBL must be uncommented, as follows:
To reflect this change, the kernel must be rebuilt.
Whenever CONFIG.TBL is changed to build a new kernel, the device nodes for the new kernel must also be rebuilt. Since the major and minor device numbers may change when editing CONFIG.TBL, users may also have to modify the root device settings to boot LynxOS.
Here are some guidelines for managing changes to CONFIG.TBL:
- When adding or removing a disk driver (usually specified at the beginning of CONFIG.TBL), the user must determine the new major and minor number of the root device to boot the new kernel; See "Removing Unused Device Drivers"
- Because functionality modules (similar to TCP/IP drivers) are specified after the disk drivers, the major and minor number of the root device does not need to be changed to boot the new kernel.
- When creating a custom device driver, users should add it to the bottom of CONFIG.TBL so that the device node information for the preceding devices stays the same.
Making a Personal Kernel Build Directory
When working on team projects, developers may need to maintain individual kernel build environments. The /sys/lynx.os directory was designed with this scenario in mind.
The lynx.os directory (bsp.xxx) is position-independent. That is, it can be copied to any location on the file system and then used to build a local kernel (a.out) from the copy.
The Makefile in the lynx.os directory uses the environment variable $ENV_PREFIX to find the library archives and object rules, but it is otherwise ignorant of its location on the disk. $ENV_PREFIX defaults to the root directory (/) on native development systems. On cross development systems, the shell script SETUP.shell defines $ENV_PREFIX when executed: (See "Setting the Cross Development Environment" for more information).
In this way, multiple developers can have multiple kernel build directories on a given system, each with its own unique CONFIG.TBL, nodetab, and uparam.h files.
Customizing from a Cross Development Host
The LynxOS distribution for cross development environments provides users with two shell scripts, which define several key environment variables such as PATH and ENV_PREFIX. These shell scripts, SETUP.bash and SETUP.csh, are located in /usr/lynx/xx/platform, where platform is x86 or ppc. One or the other of these scripts, depending on the shell requirements of the developer, must always be executed before developing applications with LynxOS tools.
The scripts are invoked using the following syntax (in the examples below, for LynxOS Release xxx, loaded onto an x86 development host):
Where <install_dir> is the LynxOS installation directory.
With the exception of having to first invoke a SETUP script on cross development systems, there is no discernible difference in the development process of LynxOS kernels from cross or native machines. LynxOS uses the same Makefiles and directory structure on cross development systems as on native systems.
The design of the /sys directory and Makefile system provides this functionality. The following example demonstrates the similarities in developing kernels on cross development and native LynxOS systems.
Adding TCP/IP to a LynxOS Kernel
In the following commands, TCP/IP IPv4 is added to an x86 cross development system:
The following commands then set up the PATH variable that points to the cross development tools, and sets $ENV_PREFIX to point to the installed LynxOS directory tree:
In this example, the LynxOS kernel (a.out) and the devices nodetab are copied to ENV_PREFIX.
Additionally, the /usr/bin/Install.tcpip script can be used to install TCP/IP onto a system.
In the following commands, TCP/IP is added to a native development system:
In this example, the LynxOS kernel (a.out) and the devices nodetab are copied to $ENV_PREFIX on a native LynxOS system.
Additionally, the /usr/bin/Install.tcpip script can be used to install IPv4 onto a system.
install.tcpip6 will install IPv6, IPSec onto a system. Consult your LynuxWorks sales representative if you would like IPv6/IPSec features.
Customizing a Kernel for Performance
The parameters defined in /sys/lynx.os/uparam.h tell the kernel how much space (dynamic memory) to set aside for various data structures at run-time. Users can modify this file to increase (or decrease) the default values.
Configurable Parameters in /sys/lynx.os/uparam.h
The table entitled "Default Values for /sys/lynx.os/uparam.h" lists some of the more important configurable parameters in the binary code written for a standard development LynxOS system installation in the /sys/lynx.os/uparam.h file. Other configurable parameters are also contained in this file, and can be found by searching for the character string #define.
The /sys/lynx.os/uparam.h file can be viewed using the more command or in a text editor such as vi.
Modification to the values of these parameters not only influences system performance, but also increases or decreases the dynamic size of the kernel.
Parameter Default Values in /sys/lynx.os/uparam.h
The configurable parameters and their default values in the /sys/lynx.os/uparam.h file are listed in the table below:
Additional Configurable Parameters for Detecting Fatal Errors on an MCP750 Board
Users can enable fatal error detection for LynxOS systems installed in processors mounted on an MCP750 board by adding the following line to the uparam.h file, where xxx is the special device file for a flash memory driver:
Increasing Maximum Processes
This example illustrates how to customize a LynxOS kernel to handle a greater number of processes. It assumes that the default bootable kernel, /lynx.os, is being modified in order to:
- Make a backup copy of uparam.h (to revert to the kernel's original settings) using the following command:
- Use a text editor, such as vi, to edit uparam.h.
- Find the parameter NPROC, and increase its number, as follows:
Creating a Kernel for Debugging
Users can create debug versions of the LynxOS kernel for use with SKDB and GDB. The debug version of the LynxOS kernel includes support for:
For more information on these functions, see the Total/db User's Guide.
To create a debug version of the LynxOS kernel, use the following when invoking make:
Changing Kernel Size
Usually, users change the size of a kernel to decrease the amount of storage space it needs and/or the amount of memory it needs for execution. This section shows the components of the kernel that affect its size, both in terms of memory and storage.
There are four basic components that users can modify to change the size of the LynxOS kernel:
- System parameters in /sys/lynx.os/uparam.h
- Functionality modules (TCP/IP, NFS, and so on)
- Device drivers
- Symbol table information
Of these, uparam.h is the only component that is dynamic - changes to uparam.h affect the kernel size in memory. The other components mainly affect the static size of the kernel - the amount of space it takes to store on a device. However, if users reduce the static size of the kernel, they usually reduce some of its dynamic size as well. The only exception is the symbol table information - removing this only affects the static size of the kernel.
After determining the components to modify, users must make a new kernel to see the size changes in effect. This process is similar to tuning a kernel for performance.
Determining the Kernel Size
The following subsections detail how to experiment with changing a kernel and determine its size.
Determining Kernel Disk Space Usage
An easy way to determine the how much total disk space the kernel is using, is using the ls -l command, as shown below:
The kernel in this example uses 877060 bytes, or about 877 KB of space.
The size command allows users to look more closely at the sizes of the text, data, and bss segments of the kernel, as illustrated by the command and output below:
This utility reports the size (in bytes) of each segment and the sum of the segments. The total size of the file a.out, in this example, is 875452 bytes (or 0xd5bbc).
In addition to the text and data segments, the kernel contains header and symbol table information that take up the additional 1608 bytes, as shown in the command output above.
Determining Kernel Memory Usage
Figuring out the memory usage of the kernel is more difficult than determining its static size. Users can use the ps command to look at a currently running LynxOS kernel.
The following example shows how to use ps to look at a currently running LynxOS kernel. On a LynxOS system, enter the following command:
This command displays all currently executing processes, including threads and unattached processes, and reports the total free memory (both physical and virtual) in kilobytes (KB) at the end of the listing:
To calculate the size of the kernel:
- Add the amount of free physical memory (8352 KB) to the amount used (2872 KB): 8352 + 2872 = 11224 KB.
- Subtract this number from the total amount of memory (RAM) on the LynxOS system.
The machine in this example has 16 MB of memory, which translates to 16384 KB: 16384 - 11224 = 5160 KB.
Removing Unused Device Drivers
One way to change to the size of a kernel is to remove unused device drivers, as described in the example below:
This example is based on a LynxOS x86 system that has only one Adaptec 2940 SCSI adapter to control its disk and CDROM drives. It does not need device entries (space used by the kernel) for other LynxOS supported SCSI device drivers.
Before Beginning
- Record the following information about the kernel:
- The /lynx.os file's current size (to be used later in validating that changes have taken effect)
- The root file system's device name
- The root file system device's major and minor numbers
- Use the df command to determine the root file system's device name. In this example, the root file system device name is /dev/sd2940.0a.
- Use the ls l command to determine the root file system device's major and minor numbers. In this example, the major number is 4 and the minor number is 16.
Modifying CONFIG.TBL
Use a text editor (such as vi) to modify /tmp/test/CONFIG.TBL as shown below to comment out unnecessary drivers by adding a pound character (#) to the beginning of the line:
# Supported LynxOS Adaptec Scsi drivers
# for SCSI Manager-based Adaptec 154x driver
#I:sim1542.cfg
# NCR 810 SIM (SCSI Interface Module) driver.
#This SCSI driver uses SCSI Manager.
#I: simncr.cfg
# for SCSI Manager-based Adaptec 294x driver
I:sim2940.cfg
#I:scsi810.cfg
# for high-level-low-level based ncr 810 driver
Building the Newly Customized Kernel
Use the following procedure to build a new kernel:
After building the new kernel, the installation script generates the file /tmp/test/a.out and copies it to /lynx.os. Additionally, the install script first creates, then copies a new nodetab file from /tmp/test/nodetab to /etc/nodetab, and then generates the file /etc/nodetab.old.
In this example, the size of the new kernel is smaller than the previous kernel by about 36 KB, verifying that the new kernel has accepted the configuration changes made earlier.
Making New Device Nodes
Use the following procedure to create new device nodes.
- Build new device nodes that correspond with the new /etc/nodetab file by entering the following commands:
Loading the New Kernel
Users must know the major and minor number of the new kernel's root file system before rebooting the machine (notice that the major number has changed to 2 in the output below).
- At the preboot command prompt (the bootstrap kernel loader program), specify the new major and minor number of the root device:
See the preboot man page for a description of the commands available on the given hardware platform.
Updating the Default Root Device
Now that the new kernel is up and running, users can update the default root device with the makeboot command:
This command allows users to directly boot LynxOS without using the R command in preboot.
Adding Functionality to a Kernel
Many LynxOS users need to develop device drivers that are specific to their target hardware. LynxOS supports this development with the /sys/lynx.os/Makefile file. In this Makefile, users can see several Makefile environment variables that they can modify to explicitly specify custom device drivers, patches, or other objects to include in the kernel.
Adding a Custom Device Driver
LynuxWorks recommends the following approach for adding a custom driver to a LynxOS kernel. Substitute actual file and directory names where appropriate in the example below.
These lines instruct the Makefile to compile file*.c files, and to insert the compiled .o files in /sys/lib/my_driver.a. Users can look at the OBJ_RULES file in the /sys/ directory to determine the substitutions that are appropriate for their compilation of the .c files. For example, .x compiles an optimized ANSI .c file, while .u.x does not optimize the .c file.
- Modify the Makefile in /sys/lynx.os so that the archive for the device driver is linked to the kernel.
- Add the configuration file my_driver.cfg for the driver in /sys/cfg; see Writing Device Drivers for LynxOS for more information about device configuration files.
- Edit the /sys/lynx.os/CONFIG.TBL so that the new driver is represented:
Configurable Tick Timer
Users can configure the number of ticks per second for real-time clocks. The define TICKSPERSEC in the /usr/include/conf.h file defaults to 100 ticks per second.
LynuxWorks recommends the following minimum and maximum ticks per second:
Configuring Core Files
LynxOS provides the ability to configure the information saved in core files. This allows users to control the size of the core file. This feature can be useful in systems with limited memory or disk resources by storing only the data essential for debugging the application at hand.
Configurable Options
The following options can be set when installing the configurable core file support:
- Data section (global and static initialized data)
- BSS section (global and static uninitialized data)
- Program heap section (memory allocated by the program using the malloc() or sbrk() interfaces)
- Shared memory (the memory segments inherited from the shared libraries used by the program and the memory obtained using the shmget(2) interface). The data and BSS sections of the shared libraries are considered a part of shared memory.
Additionally, users can define the name and location of the core file.
- The POSIX standard defines the name of the core file as "core". Users can select an non-POSIX alternative file name. The core file name appends the current seconds value of the core dump event, as well as the PID of the dumping application. For example:
- The LynxOS kernel can be configured to save the core file in a specific location, rather than in the application's current directory. Both relative and absolute paths are supported.
Installing Configurable Core File Capability
Install the configurable core file capability by running either of the following commands:
Either option starts the same configuration script, allowing the user to update the user defines in uparam.h.
The following figure details a sample configuration dialog session:
Sample Configuration Dialog
Restoring the Defaults Settings
To restore the default core file settings, the user must run one of the following commands:
User Definitions in uparam.h
The configurable core file includes a number of user defines in the LynxOS uparam.h header file. The following table includes the user definitions and default values:
Default Configuration of the Core File
The default settings of the configurable core file in uparam.h are as follows:
- Program data section dump is on
- Program BSS section dump is on
- Program heap section dump is on
- Program shared memory dump is on
- Non-POSIX core file name is off
- Core file location is the current working directory
These default settings create a conventional core file, effectively disabling any configuration options defined by the configurable core file. Core files created when the default settings are defined in uparam.h are backward compatible with non-configurable core files.
|
LynuxWorks, Inc. 855 Branham Lane East San Jose, CA 95138 http://www.lynuxworks.com 1.800.255.5969 |
| |
|
|
|
