test

ChorusOS 4.0 Production Guide

Chapter 2 System Generation

Install the binary components of the ChorusOS 4.0 product before you work with the source delivery. You will use the same method to build the source files. Your installation must include the TOOLS and the EXAMPLES components.

Before you read this Chapter, read

Steps to Create a System Image

In this Chapter, the following steps are described.

The files and directories that you have created during the above steps are discussed in this Chapter.

Installation

Ask your system administrator to supply you with ChorusOS binary and source files. Once you have read the instructions in the ChorusOS 4.0 installation guides, install the source files and the AnswerBook documentation.

Your Source PATH

Depending on your target family, you will use different source code products. Each product has different installation directories. See ChorusOS 4.0 Target Family Documentation Collection for further details. The default PATH for a source package is: 

/opt/SUNWconn/SEW/4.0/chorus-<family>/src
where each family is a group of processors, such as PowerPC. This will be your source directory, referred to in this document as <src_dir>.

Note -

For your convenience, create an environment variable to shorten your source PATH.

Source File Organization

You receive source packages in read-only mode. The fact that the source files are kept in the source directory, separate from your work directory, has the following advantages

If you need to modify the source code, use your own copy of the initial source package that you received.

Which Family, Target and Profile

Table 2-1 gives the profile and board dependent components (such as BSP, boot and family specific driver code) to be used with the configure command. The PATHs are given relative to <src_dir>.

Table 2-1 List of board dependent components
 Paths Component
 PowerPC Board 
 nucleus/ppc60x/ppc60x profile
 nucleus/bsp/powerpc/genesis2 bsp
 nucleus/bsp/powerpc driver family
 MCP750 board 
 nucleus/ppc60x/ppc60x profile
 nucleus/bsp/powerpc/mcp750 bsp
 nucleus/bsp/powerpc driver family
 SBC8260 board 
 nucleus/mpc8260/mpc8260 profile
 nucleus/bsp/powerpc/sbc8260 bsp
 nucleus/bsp/powerpc driver family
 MPC860 board 
 nucleus/mpc860/mpc860 profile
 nucleus/bsp/powerpc/mpc8xxADS bsp
 nucleus/bsp/powerpc driver family
 CP1500 board 
 nucleus/usparc/usparc  profile
 nucleus/bsp/usparc/cp1500 bsp
 nucleus/bsp/usparc driver family
 i386AT board 
 nucleus/x86/x86 profile
 nucleus/bsp/x86/i386at bsp
 nucleus/bsp/x86 driver family

All examples given in this document are for the PowerPC family and the genesis2 board. For further information on the family and board that you are using, refer to the ChorusOS 4.0 Target Family Documentation Collection.

Which Components

Table 2-2 lists the main source components in a ChorusOS source delivery and the associated directories which are created in your source directory during the installation process.

Table 2-2 Source components in a ChorusOS 4.0 delivery and the associated files.
 Component Directory Description
 NUCLEUS

<src_dir>/nucleus 

generic kernel code + family profiles 
 DRV

<src_dir>/nucleus/bsp/drv  

generic kernel drivers 
 DRV_F

<src_dir>/nucleus/bsp/<family>  

family specific drivers 
 BSP <src_dir>/nucleus/bsp/<family>/<target> board specific boot code (BSP)
 OS

<src_dir>/os  

Operating System (network, POSIX) 
 IOM

<src_dir>/iom  

I/O Manager, (drivers, file systems, IP protocol stacks) 

System Generation

This section describes the operations necessary to generate a standard system image of the ChorusOS operating system. Standard system generation builds a non-customized version of the operating system.

During the build you use two commands:

configure Command Parameters

You will use three parameters with the configure command:

  1. Use the -f option to choose the predefined profile for the PowerPC, ppc60x family (Table 2-1), such as; 

    -f <src_dir>/nucleus/sys/ppc60x/ppc60x
    It selects the NUCLEUS source component which contains a definition of variables for the build.

  2. Use the -s option to select the ChorusOS source components to be included in the build of your system image (Table 2-2), such as; 

    -s <src_dir>/nucleus/bsp/powerpc/genesis2 \
   <src_dir>/nucleus/bsp/powerpc \
   <src_dir>/nucleus/bsp/drv
    The components included determine the identity of the image. In this case, you have included the BSP, DRV and DRV_F components.

  3. Use the -b option to include binary components in your system image.

The configure command searches the directories specified by the -s and -b options for the Makefile.src and Makefile.bin files and any file corresponding to Makefile.*.src or Makefile.*.bin. The command displays each component as it adds it to the configuration. The configure command creates two files, Makefile and Paths in <work_dir>. These files are discussed later in this Chapter.

The make Command

A system image is created from components which you have configured using the configure command. Even though you type a single command, make, the system image is created over four steps, to produce the binary files corresponding to the source components.

  1. Selection of the System Image: Choose which of the configured components you will include in your sytem. By changing the components included, you alter the resultant system. The system images are defined in:

    • The Makefile.bin file of the NUCLEUS component: 

      <src_dir>/nucleus/sys/Makefile.bin

    • The conf directory: 

      <work_dir>/conf/mkimage/mkimage.xml
      The conf directory is discussed in the next section of this Chapter. Once you have selected your system image, you can use the make command in two ways to build your system image:

    • Referencing the system image name: 

      make <system image_name>

    • Building all configured components in your work directory: 

      make build

    The make command automatically performs the next three steps as shown here.

  2. Compilation: The default action of make is to compile everything in your work directory, but not to produce a bootable system image. This is because configure may be used to build components which are not directly related to ChorusOS systems.

    Compilation can last from 5 minutes to more than an hour, depending on the host you are using. For the chorus system image, the make build output includes:

         sh <work_dir>/build-NUCLEUS/mkbuild chorus

  3. Rebuilding the Configurable Components: If the configuration of the system has been changed since the last time the make command was run, using the ews GUI tool or the configurator command, then some actors may need to be relinked. The make command checks if any configurable actors need to be relinked.

    Running obj/act/pmm/Makefile
    <bin_dir>/tools/host/bin/configurator 
    -c /<work_dir>/conf/ChorusOS.xml -action configure
    Running obj/dbg/Makefile
    Running obj/kern/Makefile
    Running obj/os/admin/sys/Makefile
    Running obj/os/am/sys/Makefile
    Running obj/os/cinit/ftpd/Makefile
    Running obj/os/cinit/hrCtrl/Makefile
    Running obj/os/cinit/rshd/Makefile
    Running obj/os/cinit/teld/Makefile
    Running obj/os/iom/sys/Makefile

  4. Building of the System Image: Once the necessary actors have been relinked, the make command calls mkimage. This produces the system image. 

    Start mkimage
    Brief log file: /<work_dir>/image/RAM/chorus/log.brief
    Verbose log file: /<work_dir>/image/RAM/chorus/log.verbose
    Layout file: /<work_dir>/image/RAM/chorus/layout.xml
    Image file: /<work-dir>/chorus.RAM 
    Finish mkimage

    Once you have built your system image, the work directory contains a build directory for each source component you have included in the build.

Examples of Building a System Image

Here are two examples of how a system image is created using the steps outlined above. It is presumed that you have already installed the binary and source components for your chosen family, as outlined at the beginning of this Chapter.

Example 1: Standard System Generation

Example 1 illustrates standard system generation. The image which you create includes the generic kernel code, PowerPC drivers targeted for the genesis 2 board, generic kernel drivers, and the OS and the IOM components. This is termed a chorus system image.

  1. Create a work directory:

    host% mkdir work_dir

  2. Change to the work directory:

    host% cd work_dir

  3. Use the configure command with a build profile and a selection of components:

    host% configure -f <src_dir>/nucleus/sys/ppc60x/ppc60x \ 
-s <src_dir>/nucleus/bsp/powerpc/genesis2 \
<src_dir>/nucleus/bsp/powerpc \
<src_dir>/nucleus/bsp/drv \
<src_dir>/os \
<src_dir>/iom

  4. Create a bootable system image named chorus: 

    host% make chorus

    You could also type make build, and get the same result, as this system image is already defined in the Makefile.bin file of the NUCLEUS component.

Example 2: Kernonly Generation

The system image you create in this Example is the kernonly system and contains the generic kernel code, PowerPC drivers, and kernel generic driver component targeted for the genesis 2 board. You create this image in the first steps of porting a system to a new board. See ChorusOS 4.0 Porting Guide for more details.

  1. Create and change to a work directory as in Example 1.

  2. Use the configure command:

    host% configure -f <src_dir>/nucleus/sys/ppc60x/ppc60x \  
-s <src_dir>/nucleus/bsp/powerpc/genesis2\   
<src_dir>/nucleus/bsp/powerpc \
<src_dir>/nucleus/bsp/drv

  3. Create a bootable system image named kernonly, using the make command: 

    host% make kernonly

Files and Directories Created by configure and make commands

The configure command creates two files, Makefile and Paths. The make command creates a directory for each component included in the system image, as well as a conf, obj and image directory. These files and directories are discussed in this section.

Work Directory Organization

Table 2-3 lists the files and directories generated in your work directory by the configure and make commands.

Table 2-3 Files and Directories generated by the configure and make commands
 Files/Directories Description
Makefiletop level Makefile
Paths paths to the source or binary components
conf/ system configuration files
obj/ object files used by configurable actors
image/ image generation files
build-NUCLEUS/ build directory for nucleus
build-DRV/ build directory for generic drivers
build-BSP/ build directory for the board specific boot code
build-DRV_F/ build directory for the family specific drivers
build-OS/ build directory for the POSIX system
build-IOM/ build directory for the I/O manager

Build Directories

The make command creates a build directory, in your work directory, for each component included in the system image created. In Table 2-3, there is a build directory for the NUCLEUS (build-NUCLEUS), generic drivers (build-DRV), board specific code (build-BSP), family specific drivers (DRV_F), operating system (build-OS) and I/O manager (build-IOM). Each build directory contains the binary code for the corresponding component.

Paths file

The Paths file is created in your work directory by the configure command. For each source component, the Paths file defines two subdirectories, one located in <src_dir> and one in <work_dir>. For example, for the BSP component there is a BSP directory, which is the component source directory, and BSP_DIR, which is the directory where the component will be generated. For binary components, only one directory, that is the BSP_DIR directory, is defined. 

...
BSP= <src_dir>/nucleus/bsp/powerpc/genesis2
BSP_DIR= <work_dir>/build-BSP
...

The ChorusOS production environment will not modify any file outside of your work directory. This means that regardless of where the source directories of the BSP component are, they will be compiled in the build-BSP subdirectory of your work directory.

Makefile

The Makefile produced by the configure command includes all the Makefiles for each component. View the Makefile.

all::DEVTOOLS.all
    
    PROFILE =  -f <src_dir>/nucleus/sys/ppc60x/ppc60x
    
    include Paths
    include <src_dir>/nucleus/bsp/drv/src/Makefile.bin
    include <src_dir>/nucleus/bsp/drv/src/Makefile.src
    include <src_dir>/nucleus/bsp/powerpc/Makefile.bin
    include <src_dir>nucleus/bsp/powerpc/Makefile.src
    include <src_dir>/nucleus/bsp/powerpc/genesis2/Makefile.bin
    include <src_dir>/nucleus/bsp/powerpc/genesis2/Makefile.src
    include <src_dir>/os/Makefile.bin
    include <src_dir>/os/Makefile.src
    include <src_dir>/iom/Makefile.bin
    include <src_dir>/iom/Makefile.src
    include <bin_dir>/tools/Makefile.bin
    include <bin_dir>/tools/Makefile.CDS.bin
    include <src_dir>/nucleus/sys/common/Makefile.bin
    include <src_dir>/nucleus/sys/common/Makefile.src
    include <bin_dir>/tools/Makefile.CHSERVER.bin
    include <bin_dir>/tools/Makefile.CHTOOLS.bin
    
    COMPONENTS =  DRV DRV_F BSP OS IOM DEVTOOLS NUCLEUS  CDS CHSERVER CHTOOLS
    
    CLEAN =  $(DRV_DIR) $(DRV_F_DIR) $(BSP_DIR) $(OS_DIR) $(IOM_DIR) $(NUCLEUS_DIR)
    clean:; rm -rf $(CLEAN)
    dist: DRV.dist DRV_F.dist BSP.dist OS.dist IOM.dist NUCLEUS.dist
    
    reconfigure: ; cd /<work_dir>; \
    sh <bin_dir>/tools/host/bin/configure \
    -f /<src_dir>/nucleus/ppc60x/ppc60x \
    -s /<src_dir>/nucleus/bsp/drv /<src_dir>/nucleus/bsp/powerpc \
    /<src_dir>/nucleus/bsp/powerpc/genesis2 /<src_dir>/os /<src_dir>/iom $(NEWCONF)

The clean, dist, reconfigure, all and root make targets may be present in Makefiles. They are discussed at the end of this Chapter in relation to the generation of the ChorusOS system image.

In the Makefile shown above, the all target is followed by :: which means you can have multiple update rules. You must use :: if the make command is to work. Note, also, the clean, dist and reconfigure targets in the Makefile shown here.

The top level Makefile of the work directory includes a Makefile.bin and a Makefile.src for each source component. You receive these files with your source delivery. This ensures the compatibility of components even if they are built using different development tools.

Makefile.bin

View the IOM Makefile.bin file for the IOM component, found in the <src_dir>/iom directory.

The output states that the component is the IOM component and gives a list of the components that must be present in the operating system if the IOM component is to work. In this case the OS and NUCLEUS components must be present.

Makefile.src

The Makefile.src file is more complex than the Makefile.bin file, as it describes how the IOM component is compiled. The IOM component is compiled using the mkmk tool.

View the contents of the Makefile.src file for the IOM component, found in the <src_dir>/iom directory.

You are given the information:

This DONE file will be discussed in further detail in the section "Specific Build Options".

conf Directory

The conf directory contains files which describe the ChorusOS current configuration. These files are expressed in XML. The details of XML files are provided in Chapter 7, XML Syntax.

ChorusOS.xml is the top level configuration file. It contains references to all other configuration files located in the conf directory, as explained in ChorusOS 4.0 Introduction. When building the ChorusOS operating system from the source code, XML configuration files are copied from the various component source files to the conf directory.

obj Directory

The obj directory contains all necessary configurable actors. For instance, the IOM component is compiled in the build-IOM directory. Its object files are copied to the build-IOM/obj directory and then linked in the obj directory.

image Directory

The image directory is used during the creation of a system image. The information contained within this directory includes temporary files, log files, symbol tables, and relocated binary files.

Note -

If you have created your system image and do not need to manipulate your source delivery further, you will not need to continue reading this document.

Specific Build Options

This section provides further information on directories and files already discussed in this Chapter.

Rebuilding a Component

You can delete any of the directories that were created in your work directory during the generation process. If the directory is necessary, the make command will rebuild it. For example, you can remove the BSP component, which in the examples above provides support for the PowerPC board. Then use the make command, which will regenerate the component, if it is necessary.

host% rm -rf build-BSP/ 
host% make build

The DONE File

When a component is compiled correctly, its Makefile.src file creates a file called DONE, in the build directory. The DONE file exists to prevent make from entering a component's build directory when there is nothing else to compile. If you run the make command, and the Makefile.src file has already created the DONE file, nothing will happen. These DONE files must be removed if a component has been modified, and the dependent components need to be relinked.

Remove the DONE file for the NUCLEUS component: 

host% rm -f build-NUCLEUS/DONE

Run make now and it will enter the NUCLEUS component. Run the make command a second time and you will get no output, as the DONE file has again been created.

Rebuild of the conf Directory

To return to a previous configuration, remove the conf directory, or some files from the conf directory. This returns the system to the default configuration or to the configuration that you updated in the source configuration files. Even if you have not altered the configuration you can rebuild the conf files as follows:

host% rm -rf conf/
host% make xml

Makefile make Targets

This section details Makefile make targets discussed in the Makefile section above.

The all Target and Component Dependency

Each component implements the <component>.all rule, which is defined in the component's Makefile.bin file. This rule tells you what other components this component is dependent upon. The <component>.all rule in the Makefile.src implements the rule, building the component in its own build directory. If this first component depends on a second component, the dependency rule 

<component1>.all :: <component2>.all
is expressed in the Makefile.bin file of the first component.

Note -

If the dependency is valid only for the build process, the dependency rule is expressed in the Makefile.src file.

Update the Source Configuration

Verify that you have installed the EXAMPLES component. This source component, which contains a number of small applications, is built on top of the os and nucleus levels (See Table 1-1 for further details of component hierarchy).

The reconfigure target adds components to the initial configuration. Add the EXAMPLES component to your initial work directory, and build it as follows:

host% make  reconfigure NEWCONF='-s <src_dir>/opt/examples'
host% make

Build the Target NFS root

The root target lets you copy files from components into the root directory.

As the EXAMPLES component contains binary files that the target must see, use the make root command to copy the binary files of the EXAMPLES component into the root directory as follows: 

host% make root

The root directory now contains the binary files of the EXAMPLES component. You can run this component on a target system where this root directory can be NFS mounted.

Build a Binary Distribution

To build a binary distribution of the EXAMPLES component, run the following command:

host% make EXAMPLES.dist

This command creates a new directory in your work directory, called dist-EXAMPLES, containing the binary files of the EXAMPLES component.

You can move the component's binary files to any directory as follows: 

host% mv dist-EXAMPLES ../
Use these binary files instead of the source files by using the binary option of the configure command.

Use Binary Files Instead of Source Files

To use the EXAMPLES component's binary files, you must remove the current configuration of the component. There is no specific command to achieve this. Follow these four steps:

  1. Edit the reconfigure rule at the end of the top-level Makefile by removing the following line in the source file 

    -s <src_dir>/opt/examples

  2. Remove the component's build directory and run make reconfigure as shown here: 

    host% rm -rf build-EXAMPLES/ 
host% make reconfigure

  3. Add the application's binary files: 

    host% make reconfigure NEWCONF='-b dist-EXAMPLES'

  4. Run the make command and notice the output as make rebuilds files in the conf directory.

Build in Verbose Mode

Usually, compilations of an mkmk or imake component are not verbose. If you want to get the whole trace of the build, just add 'SILENT=' to the Paths file:

host% echo 'SILENT=' >> Paths

To test this modification, compile the EXAMPLES component by configuring the source files:

host% make reconfigure NEWCONF='-s /<src_dir>/opt/examples/'

The previous command has produced another Paths files, so if you add "SILENT=" again and run the make command, you will see a more verbose output.

host% echo 'SILENT=' >> Paths
host% make
Note -

As the application binary files are already configured, the configure command will skip the binary files and choose to use the source files.

Build in Debug Mode

To debug a component, you may need to recompile it with special compilation options. To achieve this for the EXAMPLES component:

  1. Remove the component's build directory: 

    host% rm -rf build-EXAMPLES

  2. Add 'FREMOTEDEB=ON' to the Paths file.

  3. Use the make command to recompile the component: 

    host% make