11.1. Packages
To get a better understanding of the eCos toolset, we need to take a closer look at the modules that the tools operate on: packages. As described in Chapter 1, An Introduction to the eCos World, a package is a software component incorporating all necessary source and configuration files for distribution. A package can be for a single hardware device or for an entire networking stack. Packages can be configured, using the different eCos tools, to operate in a mode specific to your application. We see how to manipulate packages with the eCos configuration tools in the Package Control section of this chapter.
In order for the eCos component framework to make use of packages, the package must follow rules imposed by the framework. A CDL script file is included with each package, which describes the package to the component framework. Included in the CDL script files are dependencies for using the package, configuration options and their associated value ranges, and details on how to build the package.
11.1.1. Package Directory Structure
All packages in the eCos repository are located under the packages subdirectory under the root eCos development kit install directory; in our case, D:ecos. A packages directory snapshot is shown in Figure 1.3 in Chapter 1. Because the eCos source code repository is constantly evolving to accommodate new features and hardware platforms, the latest eCos repository might differ from the one shown in Figure 1.3.
As we see in Figure 1.3, the different packages are arranged based on the functionality provided by the package. For example, all device drivers are contained in the devs subdirectory, while all compatibility layer support, such as POSIX and μITRON, is contained under the compat subdirectory. The depth of the subdirectory structure is different for each package. It is a good idea to familiarize yourself with the overall directory structure by browsing through your eCos development kit installation.
Under the packages directory is the package database file ecos.db. This file uses the CDL and contains a high-level description for all packages in the component framework. Additional details about the eCos database file are included later in The Configuration Tool section of this chapter.
Although the depth of the different subdirectory structures varies for each package, each of these packages is comprised of a number of common subdirectories that separate the functionality supplied in the different files. The common directory structure for an example package is shown in Figure 11.1. Not all packages contain all of the common package subdirectories shown in Figure 11.1; some packages contain more, some less.
Figure 11.1. Typical package directory structure example.
NOTE
Our local eCos source code repository, installed in Chapter 10, The Host Development Platform, also contains CVS directories at different levels of our directory tree. These directories are used by the CVS program—in our case, WinCVS—to keep track of information about our local eCos repository and the online eCos repository. We can ignore these directories at this point since they do not contain any source code files for eCos.
It is also important to note that not all of the packages strictly follow the rules for the location of files, making the possibility of the file organization slightly different from package to package. In this section, we look at the general structure of typical packages.
As we see in Figure 11.1, the root of the typical package directory is the version. The actual name of this subdirectory depends on the repository version installed. From our installation completed in Chapter 10, we have a version directory called current.
Having multiple versions for each package allows you to experiment with new versions while maintaining a working version for a particular package. If the new, experimental version of the package does not work in your application, you can always revert to a previous version. Selection of versions for packages is accomplished using the configuration tools, which we get into in the Package Control section of this chapter.
Each package contains a file under the version subdirectory called ChangeLog. The eCos source code repository maintainers use these files to track the changes for each of the different files within a package. These files are useful to get an overview of changes made to the package to determine if you want to update to a current version to make use of particular bug fixes or enhancements. An example of two change log entries is shown in Code Listing 11.1.
Code Listing 11.1. Example ChangeLog entries.
1 2001-09-27 Jonathan Larmour <[email protected]> 2 3 * src/plf_misc.c (hal_platform_init): 4 If not RAM startup, install exception VSRs. 5 6 2000-04-21 Bart Veer <[email protected]> 7 8 * pkgconf/rules.mak: 9 Fix header file dependencies for testcases. |
In Code Listing 11.1, lines 1 and 6 contain the date the changes were made, the developers who made the changes, and the developers' email addresses. Each change is designated with an asterisk (*) as shown on lines 3 and 8. After the asterisks are the files that were altered and their directory location within the package. Sometimes the routine modified is also entered as we see on line 3, in which case the routine hal_platform_init was modified. Lines 4 and 9 describe the changes made.
Under the version root is the cdl subdirectory. This subdirectory must be included within a package. This contains at least one CDL script file that defines the package. Some packages, such as the kernel, might break up the functionality of the CDL script in multiple CDL files. Additional details about CDL script files are contained in The Component Definition Language Overview section of this chapter.
Next is the include subdirectory, which contains public header files for the package. During the eCos library build process, which we go through in Chapter 12, An Example Application Using eCos, some of the header files for packages that are used are copied into the eCos library working directories. This allows an application to include header files needed for a particular package from the working directory rather than using the repository directories.
The src subdirectory contains the source files for the package. This subdirectory must be included within a package. The source files might include .c C language files, .cxx C++ language files, and .S assembly language files. Private header files (with a .h extension), accessible only to the package source code, might also be contained in this directory. The src subdirectory can be broken down further into additional subdirectories to aid with the organization of the source code. For example, see the kernelcurrentsrc and net cpipcurrentsrc subdirectories.
Finally is the tests subdirectory. This subdirectory contains any test files relevant for the package. We look at building and running tests in Chapter 12.
Other subdirectories that are often included under certain packages are doc, which contains documentation for the package, and misc, which contains other files specific to the package such as RedBoot configuration import files for various startup types.
Let's look at the actual directory structure for one of the packages in the eCos source code repository. Figure 11.2 is a snapshot of the i386 PC HAL package directory structure. From this figure, we can see where the common subdirectories are located for this particular package.
Figure 11.2. Current version directory snapshot of the i386 PC HAL package.
As mentioned before, the packages subdirectory is located under the root eCos development kit install directory D:ecos. Since this is a HAL package, it is located under the hal subdirectory. The HAL packages are organized by architecture; in this case, it is the i386 architecture.
The architecture, in this package, is further divided by platform support. The platform component is located under the pc subdirectory. The version subdirectory is called current. Finally, we have the common package directory structure comprised of the subdirectories cdl, doc, include (along with pkgconf), misc, and src.
We can see that the i386 package differs slightly from the common package directory structure shown in Figure 11.1. The additional directories for this package are:
doc— contains documentation and release notes for the package.
pkgconf— includes RAM, ROM, and floppy disk memory configuration files.
misc— contains exported floppy disk and ROM RedBoot configuration files for use with the configuration tools.
11.1.2. The Component Definition Language Overview
We now take a brief look at the CDL. This section gives us a basic understanding of the CDL and how script files are used with packages in the component repository. Using the information in this section, we can then proceed to explore the eCos configuration tools and how the package CDL script files are interpreted in The Configuration Tool section of this chapter. An in-depth look into the CDL is provided online in the eCos Component Writer's Guide:
Details about the CDL command and keyword syntax are in the CDL Language Specification section of the eCos Component Writer's Guide.
CDL is not a new language, it is an extension of the existing Tool Command Language (Tcl) scripting language. The CDL syntax uses Tcl syntax. The CDL is a key part of the eCos component framework that is used in script files (with the extension .cdl) to describe the package to the framework. These CDL script files contain information on all of the configuration options within a package, as well as details on how to build the package.
11.1.2.1. CDL Script Files
Each package has a single top-level CDL script file, typically located in the cdl subdirectory, as shown in Figure 11.1. The first command in the top-level script should be cdl_package, which is used in the package database file ecos.db. There should only be one cdl_package command per package.
The CDL syntax implements a command hierarchy. This allows options to be controlled as a group; therefore, disabling a single component disables all options within the component as well. The hierarchy also enables a simpler representation in the Configuration Tool for navigation and modification of options, as we see in The Configuration Tool section of this chapter.
There are four CDL commands used in script files:
cdl_package— The unit of distribution, which might contain option, component, or interface commands within its body. Typically, this is the top level of the CDL script file. The package command body can make use of most option properties as well as additional properties or commands that apply to the entire package.
cdl_component— A configuration option that might contain additional options or subcomponents within its body. The body of a component command might also contain the same properties as the option command.
cdl_option— The basic unit of configurability that generally contains a single choice. The body of the option command contains properties that describe and define the characteristics of the option. There might also be information to aid in your decision, such as a text description of the option.
cdl_interface— A calculated configuration option that provides an abstraction mechanism. The body of the interface command might contain a subset of the option properties.
Every command must have a command name. All command names must be unique within a configuration. If two names exist within two different packages, it is not possible to load both packages in a configuration.
NOTE
You might notice that some packages use the same CDL command names. For example, all HAL packages define the CDL component name CYG_HAL_STARTUP. Even though all command names must be unique within a configuration, this is fine because only one HAL package can be loaded at a time; therefore, the name CYG_HAL_STARTUP only exists once within a configuration.
Typically, the component framework outputs a #define for every active and enabled option, using the command name as the symbol being defined. For example, enabling the option command named:
CYGIMP_KERNEL_INTERRUPTS_DSRS
which is located within the eCos Kernel package, in the Kernel Interrupt Handling component causes
#define CYGIMP_KERNEL_INTERRUPTS_DSRS 1
to be placed in the designated kernel package header file. Some options are set to values in which case the configured value is used when setting the #define statement.
Command names in the eCos component repository follow a naming convention to avoid name clashes with other packages. An example of a package name is CYGPKG_HAL_I386_PC. The first three characters of the name identify the organization that produced the package; in this case, CYG is for Cygnus Solutions. The next three characters indicate the nature of the option; in this case, PKG is used to indicate this is a package. A complete list of command tags is given in The eCos Component Writer's Guide. The HAL portion of the name indicates the location of the option within the overall hierarchy; in this case, we see that this is a HAL package. The last part, I386_PC, indicates the option itself. This is for the i386 architecture PC platform package.
Each CDL command contains a body that might include properties or commands that describe to the component framework how to handle each option. Properties can be descriptions of the command or values set by you that are used when the package is built. Commands within the CDL command body can define header files generated for the package, list source files to build for the package, or identify constraints that must be met if the package is active. The basic CDL command structure is shown in Code Listing 11.2.
Code Listing 11.2. Basic CDL command structure example.
1 cdl_package PACKAGE_NAME {
2 <package properties and commands>
3 cdl_component COMPONENT_NAME {
4 <component properties and commands>
5 }
6 cdl_option OPTION_NAME {
7 <option properties and commands>
8 }
9 }
|
As we see in Code Listing 11.2, a basic structure for CDL commands contains the command followed by the command name, as shown on line 1. In this case, the package command name is PACKAGE_NAME. Every command body is encapsulated in curly brackets ({}). The # character is used for comments within the CDL script file. Line 2 is the beginning of the package command body and the package command ends on line 9. Package commands and properties are located within the package body. There can be any number of package commands, properties, options, or components in the package body.
Next is a component command on line 3, named COMPONENT_NAME. Within the component command body, shown on line 4, there might be a number of different properties, commands, options, or subcomponents present.
Finally, there is an option command named OPTION_NAME on line 6. The body of the option command is on line 7 and might contain any number of properties and commands to describe and define the option.
Code Listing 11.3 shows an excerpt from the i386 PC HAL package. The script file for this listing is hal_i386_pc.cdl located under the hali386pccurrentcdl directory. However, some of the script commands and properties have been cut out to reduce the size of the listing and isolate the commands we want to examine.
NOTE
The CDL script fragment in Code Listing 11.3 does not show all of the possible commands or properties available. This fragment is intended to familiarize us with some of the basic language of the CDL and the structure of script files. In the Graphical Representation of CDL Script Files section of this chapter we see how the component framework and configuration tools use packages and their CDL script files. For a comprehensive look at the CDL, read The eCos Component Writer's Guide. This document is very useful if you need to develop your own packages for distribution.
Code Listing 11.3. Example CDL script file from i386 PC HAL package.
Let's take a closer look at the CDL script file excerpt shown in Code Listing 11.3. On line 1, which is the first CDL command in the hal_i386_pc.cdl script file, is the CDL package command with the name CYGPKG_HAL_I386_PC. From this name, we can see that this is the i386 architecture PC platform HAL package. The display name of the package is given on line 2 with the display command.
Next, line 3 contains the parent command, which allows this package to be nested under the i386 architecture defined by the name CYGPKG_HAL_I386. The define_header command on line 4 identifies the header file, hal_i386_pc.h, which is generated for this package, and include_dir on line 5 is the location where this header file is placed in the local configuration workspace. We look at the local configuration workspace in Chapter 12 when we build the eCos library.
Line 6 contains the description command, which is used by the Configuration Tool to give a text description of the package contents. The compile command on line 11 lists the files that should be built for this package. The implements commands on lines 13, 14, and 15 describe the general interfaces that are included by selecting the i386 PC package.
Next, is a CDL component command on line 17 named CYG_HAL_STARTUP. On line 19 is the flavor command, which specifies the nature of the component; in this case, data. By designating the flavor as data, when the #define is generated for this component the value is set to one of the legal_values, as shown on line 20. The values that this component can be set to are RAM, FLOPPY, or ROM. If no change is made to the CYG_HAL_STARTUP component, the default_value RAM is used from line 21. The command no_define on line 22 suppresses the normal generation of preprocessor #define symbols in the configuration header file. Additional #define symbols that go into the configuration header file are specified by the define command on line 23.
The final CDL option command on line 38 is named CYGSEM_HAL_I386_PC_ DIAG_SCREEN. This option is of type bool as we can see from the flavor command on line 40, which means that the option is either enabled or disabled. The default for this command is enabled, as shown on line 41 with the default_value of 1.