11.2. The Configuration Tool

There are two tools you can use to configure the eCos repository according to your specific requirements. As mentioned in Chapter 1, the configuration tools give you the ability to customize the eCos library to meet your specific application needs through source-level configuration. You can use the command-line tool or the graphical Configuration Tool.

The command-line tool does not offer the ability to resolve conflicts interactively. The Configuration Tool provides interactive conflict resolution, as well as an easy-to-use interface for configuration setup and management, the facility to build the eCos RTOS library, and the capability to build and run tests on a target platform. We are going to focus on the use of the Configuration Tool for manipulating our configurations throughout this book. If you would like to become more familiar with the command-line tool, additional information can be found online in the eCos User's Guide:

http://sources.redhat.com/ecos/docs.html

The eCos development tools are located in the D:ecosin directory from our installation complete in Chapter 10. The source code for all of the eCos development tools is located under the D:ecoshost directory.

There are two different versions of the Configuration Tool we installed, 1.3.net and 2.11. The version 1.3.net of the Configuration Tool only supports host development environments running the Windows operating system. Version 2.11 of the Configuration Tool can run on Windows and Linux host development systems.

The major difference between the two versions is that the 1.3.net version includes a graphical window called the Memory Layout Tool (MLT) for manipulating memory configurations. Since the MLT functionality is expected to move into a separate application (at sometime in the future), it is not included in the version 2.11 release of the Configuration Tool.

In this book, we use version 2.11 of the Configuration Tool for configuring the eCos framework and building eCos images. We also cover using the MLT, in version 1.3.net of the Configuration Tool, later in this chapter. Both versions of the Configuration Tool were installed in Chapter 10.

We also get a basic understanding of the relationship between the Configuration Tool and the component repository in this chapter. CDL script files are included with all packages, which allow the Configuration Tool to interpret and display the proper information about a given package.

The Configuration Tool can be invoked by either using the desktop icon, if created during the installation procedure, or through the Start –> Programs –> eCos Configuration Tool menu.

11.2.1. Screen Layout

The first step to understanding the Configuration Tool is to become familiar with the screen layout. Figure 11.3 is a screen snapshot of the Configuration Tool with all window views enabled. All of the windows in the Configuration Tool can be sized according to your needs by adjusting the splitter bars for a given window.

The title bar of the Configuration Tool application displays the configuration file name—in this case, ecosi386net.ecc—along with the application name, eCos Configuration Tool. When a modification has been made to the configuration, an asterisk (*) appears after the configuration filename. This indicates that the modifications made to the configuration have not been saved.

Under the title bar we see the menu bar, which is standard on Windows applications. This contains the menus File, Edit, View, Build, Tools, and Help. The File menu contains the options to save, open, start a new configuration, and import or export a configuration.

The Edit menu includes the cut, copy, and paste options as well as a find option that allows you to search through certain windows for specific words.

The View menu includes options for configuring the settings of the Configuration Tool, control over which windows are displayed, and control over which tool bars are enabled.

The Build menu contains options to build the eCos library and tests, clean the build tree working directory, stop a build in progress, display compiler and linker flags, select the root repository, and enable templates and packages for a particular configuration.

The Tools menu allows you to set up the paths for the build and user tools, display the available platforms, and resolve conflicts.

Finally, the Help menu includes the help documentation for the Configuration Tool and eCos, as well as information about the release of the Configuration Tool. Context-sensitive help topics are displayed for any control within a dialog box by either pressing F1 or clicking the question mark icon in the dialog caption bar and then clicking the control. Some dialog boxes contain a help button as well.

You might want to customize the Configuration Tool settings according to your needs. To do this, select View –> Settings from the menu bar. This brings up the Configuration Tool settings dialog box. The configuration settings in this dialog box are separated into three different tabs.

The first tab is Display. Under this tab, the Configuration Pane settings allow you to Use Macro Names or Use Descriptive Names for the Labels. Typically, it is easier to use the descriptive names for a better explanation of the different labels in the Configuration window and refer to the macro name in the Properties window. You can also set whether you want Integer Items displayed in Decimal or Hexadecimal. The Font can also be set for the different windows in the Configuration Tool. Finally, the splash screen can be enabled or disabled using the Show Initial Splash Screen check box.

Next is the Viewers tab. This allows you to set the program to use for viewing header files, which can be set to use the Associated Viewer (wordpad.exe) or a program you select as This Viewer. The program to use for viewing documentation can also be configured to the Built-in Viewer, Associated Browser (iexplore.exe), or a program you select as This Viewer.

The Conflict Resolution tab is next. This allows you to set the methods the Configuration Tool uses to check for conflicts in your configuration. The available options are After Any Item Changed, Before Saving Configuration and Automatically Suggest Fixes.

Finally is the Run Tests tab. The Configuration Tool automates the downloading and running of tests on the target hardware. This tab allows you to configure the timeout associated with the test download and the connection method to the target, which can either be via serial or Ethernet port. Additional information about running tests using the Configuration Tool is covered in Chapter 12.

The Configuration Tool offers a search tool located under the Edit –> Find menu, or the Find icon on the standard tool bar can be used. The Find tool allows you to search for a text string within a configuration item. The Find dialog box allows you to search in macro names, item names, short descriptions, current values, or default values. This tool is very useful when you need to locate a specific configuration item nested deep within the component repository.

Beneath the menu bar is the tool bar. The tool bar shown in Figure 11.3 is the Standard tool bar. This is enabled by selecting Toolbar under the View menu. The tool bar allows faster execution of different menu options by clicking on the different icons. Hovering over the tool bar icons with the mouse causes a tip to pop up that describes the operation of that particular icon.

At the bottom of the Configuration Tool we see the status bar. In Figure 11.3, the status bar shows Ready and No Conflicts. During manipulation of the configuration, the status bar gives feedback of the operation being performed and any problems that might arise. Additionally, when building the eCos library the status bar gives a progress meter and numerical percentage of the build progress.

During our installation procedure, we selected the build and user tools. However, there might be a circumstance that requires selecting a different location for these tools. In that case, select Tools –> Paths –> Build Tools to set the location of the cross-development tools, such as i386-elf-gcc. To set the user tools, select Tools –> Paths –> User Tools to set the location of the Cygwin tools.

In certain circumstances, such as trying out a new snapshot of the eCos source code, it might be necessary to have the Configuration Tool use a different local source code repository. The repository the Configuration Tool uses is changed by selecting Build –> Repository and then browsing to the location of the local eCos source code. The Configuration Tool then searches for the ecos.db file.

11.2.1.1. Saving Configurations

As mentioned earlier in this section, the Configuration Tool uses the title bar to notify you that the configuration currently loaded has been modified but not yet saved. It does this by displaying an asterisk (*) next to the configuration filename on the title bar.

A configuration can be saved either by using the Save icon on the toolbar or through File –> Save or File –> Save As on the menu bar. Configuration files have a .ecc extension, which stands for eCos Configuration. The saved configuration file contains all of the packages loaded, template used, option settings, and description information, which the Configuration Tool uses to generate the proper eCos image. The configuration files can be viewed using any text editor. A good understanding of configuration files is necessary before attempting to hand edit these files. The Configuration Tool inserts comments into the configuration file to separate different sections of the file.

After saving the configuration file, build and install tree directory structures are created. This is a working directory that the Configuration Tool uses to store files during the build procedure. The working directory structure created after the configuration file is saved is explained in Chapter 12. Code Listing 11.4 shows a portion of a saved configuration file for the i386 PC target using the Net template.

Code Listing 11.4. Example of a saved .ecc configuration file for i386 target.

 1  cdl_configuration eCos {
 2     description "" ;
 3  
 4     # These fields should not be modified.
 5     hardware    pc ;
 6     template    net ;
 7     package -hardware CYGPKG_HAL_I386 current ;
 8     package -hardware CYGPKG_HAL_I386_GENERIC current ;
 9     package -hardware CYGPKG_HAL_I386_PC current ;
10     package -hardware CYGPKG_HAL_I386_PCMB current ;
11  .
12  .
13  .
14     package -template CYGPKG_HAL current ;
15     package -template CYGPKG_IO current ;
16     package -template CYGPKG_IO_SERIAL current ;
17     package -template CYGPKG_INFRA current ;
18     package -template CYGPKG_ISOINFRA current ;
19     package -template CYGPKG_KERNEL current ;
20     package -template CYGPKG_ERROR current ;
21     package -template CYGPKG_IO_FILEIO current ;
22     package -template CYGPKG_NET current ;
23     package -template CYGPKG_IO_ETH_DRIVERS current ;
24  };
25  .
26  .
27  .
28  cdl_option CYGNUM_HAL_COMMON_INTERRUPTS_STACK_SIZE {
29     # Flavor: data
30     user_value 4096
31     # value_source user
32     # Default value:  CYGPKG_KERNEL ? 4096 : 32768
33     #    CYGPKG_KERNEL (unknown) == 0
34     #    --> 32768
35     # Legal values: 1024 to 1048576
36  };

As we see in Code Listing 11.4, the saved configuration file uses the CDL. The main CDL command configuration is shown on line 1. This command lists all information about the hardware, template, and packages used for this configuration.

Line 5 shows the pc hardware target, and line 6 shows the template used for this configuration, net. Lines 7 through 23 list the different packages that are included in this configuration.

On line 28, a different part of the configuration file is shown. Here the CDL command option is shown for the CYGNUM_HAL_COMMON_INTERRUPTS_STACK_SIZE. The # character is used for comments in CDL files. In this case, the comment lines, similar to line 29, give extra information about the CDL command setting. We see on line 30 that the user_value parameter is set to 4096. The Configuration Tool uses this value setting during the build procedure.

Configuration files allow you to store the packages and option settings for a specific configuration used to build an eCos image. You are then able to open this configuration file and edit the settings, by changing options or adding packages, to build a new eCos image.

11.2.1.2. Importing and Exporting Configurations

The import and export features of the Configuration Tool are useful in saving and restoring partial configurations. The import feature, located under File –> Import, is used to restore the exact configuration from a saved configuration file. An eCos Minimal Configuration, with a .ecm ending, includes packages and configuration option value settings for a specific configuration. We use this feature in Chapter 12 to import a RedBoot configuration.

The export feature, located under File –> Export, saves a configuration to a .ecm file. This is useful if you need to replicate the exact configuration settings on another host system. Code Listing 11.5 shows a portion of an exported .ecm file. Exported minimal configuration files can also be viewed with a text editor.

Code Listing 11.5. Example of an exported .ecm file.

1  cdl_option CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL_BAUD {
2  user_value 57600
3  };
4  
5  cdl_option CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL {
6     user_value 1
7  };

Exported minimal configuration files, which also use the CDL, are similar to the saved configuration files. However, the Configuration Tool does not insert comment lines as it does in the saved configuration files. The exported minimal configuration file contains only the differences from the standard configuration settings.

For the example shown in Code Listing 11.5, two configuration options were modified. The first option changed was the baud rate for the console channel (CYGNUM_HAL_VIRTUAL_ VECTOR_CONSOLE_CHANNEL_BAUD) from the default of 38400 to 57600. This command is stored in the file as shown on lines 1 through 3. The second option changed was the debug channel used (CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL) from 0 to 1. This command is stored as shown on lines 5 through 7.

11.2.1.3. Configuration Window

The main window of the Configuration Tool is the Configuration window. As we see in Figure 11.3, this window contains a tree-based representation of the configuration items (packages, components, and options) currently loaded into the configuration on the left side of the splitter bar. Each of these configuration items is enclosed in a cell. To the right of the splitter bar is the version of the package—in this case, the version is current—or the current option value setting.

Clicking on a particular cell activates that configuration item. Clicking on the right side of the splitter bar allows you to modify a particular option. To end editing of a particular cell, you can either click elsewhere in the Configuration window or press Enter. To discard modifications made and revert to the previous value, press the Escape key.

The plus and minus sign icons next to each node allow you to expand or contract the packages, components, or options located within that node. Each node contains an icon before the text to assist you in determining the type of module the node represents. The different icons are shown in Table 11.1.

Table 11.1. Configuration Tool Module Icons

Icon	Description
	Represents a package. Typically located at the highest level and contain components and options for configuration. In Figure 11.3, the packages shown include the eCos HAL, i386 Architecture, and the eCos Kernel.
	Indicates a component. Contain subcomponents or options for configuration. Figure 11.3 includes the HAL Interrupt Handling and ROM Monitor Support components within the eCos HAL package.
	Denotes a Boolean flavor option. This icon represents options that can be either enabled or disabled. Figure 11.3 contains the Boolean flavor options Enable I386 FPU Support and Enable Pentium Class CPU Features.
	Indicates data flavor options of integer type. Options of this type can be set to particular values within their specified ranges.
	Denotes data flavor options of string type. Options of this type can be set to various value strings.
	Represents data flavor options of enumeration type. Options of this type have predefined values that can be set. The different configuration values are represented in a drop-down menu.

Icons for particular options are grayed if they are disabled or unable to be modified using the Configuration Tool. Along with the icon being grayed, the option value is also grayed.

Right-clicking on items in the Configuration window brings up a pop-up menu containing:

• What's This?— pops up a description of the selected item. This description can also be found in the Short Description window.

• Properties— displays a dialog box of the properties for the item. The properties are also found in the Properties window.

• Restore Defaults— sets the value of the item to the default value.

• Visit Documentation— displays the documentation for the item.

• View Header File— opens the header file containing the item. This can also be accomplished by double-clicking the File property in the Properties window. The header file is only displayed if the configuration has been saved.

• Unload Package— available only when right-clicking on packages. This unloads the selected package from the configuration.

11.2.1.4. Conflicts Window

The Conflicts window, shown in Figure 11.3, displays any problems that arise during modification, installation, or removal of configuration items. A conflict occurs when requirements are not met between configuration items that are defined in the CDL.

The Conflicts window is split into three different columns: Item, Conflict, and Property. The Item column displays the macro name of the first item involved in the conflict. The Conflict column shows a description of the conflict type, such as Unsatisfied or Illegal. The Property column contains a description of the configuration item property that caused the conflict. The Conflicts window can be enabled or disabled by selecting View –> Conflicts from the menu bar or using the hot-key combination Alt+5.

Right-clicking on a particular item in the Conflicts window pops up a menu with two options, Locate and Resolve. Locate causes the configuration item to be selected in the Configuration window. Resolve allows you to resolve the conflict prior to building the eCos library. Resolving conflicts is covered in the Using Templates section of this chapter.

11.2.1.5. Properties Window

The Properties window is located below the Conflicts window, as we see in Figure 11.3. This window displays the CDL properties found in the CDL script file for the currently selected configuration item. A detailed description of the relationship between the CDL script files and the Properties window can be found in the Graphical Representation of CDL Script Files section of this chapter. The Properties window can be enabled or disabled by selecting View –> Properties from the menu bar or using the hot-key combination Alt+1.

Two columns divide the Properties window, Property and Value. The Property column gives the property name found in the CDL script file. Each configuration item contains different properties in the command body. The Value column displays the available or current value settings from the CDL script file.

Double-clicking the URL property causes the referenced HTML page to be displayed. This is the same as right-clicking the configuration item, in the Configuration window, and selecting Visit Documentation. Double-clicking on the File property opens the file described in the Value column. This file contains the source code for the configuration option settings. The current configuration must be saved for this to work.

11.2.1.6. Short Description Window

The Short Description window displays a brief description, from the CDL script file, which contains information about the currently selected configuration item. The Short Description window is shown in Figure 11.3.

This window can be enabled or disabled by selecting View –> Short Description from the menu bar or using the hot-key combination Alt+3. The information displayed in the Short Description window is also displayed when right-clicking the configuration item, in the Configuration window, and selecting Visit Documentation.

11.2.1.7. Output Window

The Output window is located at the bottom of the Configuration Tool as shown in Figure 11.3. The Output window displays messages generated by the execution of external tools. For example, when building the eCos library, the Output window displays commands executed during the build process along with any warning or error messages that occur. The Output window can be enabled or disabled by selecting View –> Output from the menu bar or using the hot-key combination Alt+2.

Right-clicking in the Output window pops up a menu that allows you to copy text from the window, clear text from the window, select all text in the window, or save the output in the window to a log file.

11.2.1.8. Memory Layout Window

As previously mentioned, version 1.3.net of the Configuration Tool includes the Memory Layout Tool, which is not present in version 2.11. Version 1.3.net of the Configuration Tool is located under the D:ecosin directory in the file Configtool13net.exe, which we installed in Chapter 10. Version 1.3.net is used to graphically manipulate memory configurations. The other alternative is to edit the memory configuration files by hand.

The mEmory Layout window is a graphical view of the memory configuration based on the currently selected hardware architecture, platform, and Startup Type configuration option. A horizontal bar that is divided into a number of blocks for each memory section represents the memory layout for a region. The name of the memory region is above the horizontal bar along with the address range covered by that region. For example, in Figure 11.4 we see the MLT's graphical representation of the memory configuration for the Motorola PowerPC MBX860 platform with a ROM Startup Type.

The Memory Layout window can be enabled or disabled by selecting View –> Memory Layout from the menu bar or using the hot-key combination Alt+4. In version 1.3.net of the Configuration Tool, the memory layout tool bar can be used to modify memory configurations. This tool bar can be enabled or disabled by selecting View –> Toolbars –> Memory Layout from the menu bar. Right-clicking in the Memory Layout window allows you to view the properties of the selected region or section of memory.

11.2.1.9. Memory Layout Manipulation

There are default memory layouts provided for all supported platforms that do not need to be modified to begin developing using eCos. Modifying the memory layout is necessary when porting eCos to your own platform, which probably differs from any supported platform, or if memory is added to or removed from an evaluation board. Modifications can be made in the Memory Layout window or using the memory layout tool bar.

The memory layout files for each platform are found under the includepkgconf subdirectory within the HAL platform directory structure. Typically, each platform includes RAM and ROM memory layout files that are used by the Configuration Tool based on the Startup Type configuration option selection. Some platforms also contain ROMRAM memory layout files for applications that start in ROM but are copied to RAM for execution. For each Startup Type supported by the platform, there are three different memory layout files.

The first type of memory layout file contains a .h extension, which contains C macro definitions of the memory region. The .ldi files are linker script files that define region and section locations. Finally, the .mlt files contain the description of the memory layout for use by the MLT. When editing the memory layout files by hand, only the .h and .ldi files need to be modified; the .mlt file is only used by the MLT.

Figure 11.4 shows the Memory Layout window for the Motorola PowerPC MBX860 platform with a ROM Startup Type configuration option selected. There are two region names in this memory layout, ram and rom. We can see that the ram region includes the address range 0x0000_0000 to 0x003F_FFFF, and the rom region includes the address range 0xFE00_0000 to 0xFE7F_FFFF.

The different memory sections, such as reserved_vectors in the ram region and text in the rom section, are shown in Figure 11.4. Within each memory section is a short description about that section, which might include the size, alignment, and whether the section is relocated. We can see in Figure 11.4 that the reserved_vectors section in the ram region has a size of 3000 bytes, while the text section in the rom region is aligned on a 4-byte boundary. The base addresses for the two memory regions start at the left with the lowest addresses for that region shown below the horizontal bar. Unused portions of memory are represented with hatching, as shown at the end of the rom region in Figure 11.4.

Code Listing 11.6 contains a fragment of the linker script file, mlt_powerpc_ mbx_rom.ldi, for the Motorola PowerPC MBX860 platform with ROM Startup Type. This .ldi file is generated based on the memory layout configured in Figure 11.4. For additional information about linker scripts and linker commands, see the GNU ld documentation, which can be found online at:

www.gnu.org/manual/manual.html

Code Listing 11.6. Linker script fragment for Motorola PowerPC MBX860 platform with ROM Startup Type.

 1  MEMORY
 2  {
 3     ram : ORIGIN = 0, LENGTH = 0x400000
 4     rom : ORIGIN = 0xfe000000, LENGTH = 0x800000
 5  }
 6  
 7  SECTIONS
 8  {
 9     SECTIONS_BEGIN
10     SECTION_vectors (rom, 0xfe000000, LMA_EQ_VMA)
11     SECTION_text (rom, ALIGN (0x4), LMA_EQ_VMA)
12     SECTION_fini (rom, ALIGN (0x4), LMA_EQ_VMA)
13  .
14  .
15  .
16     SECTIONS_END
17  }

The first command, MEMORY, on line 1 defines the memory regions present in the layout. In Code Listing 11.6, we can see that the ram and rom region definitions are on lines 3 and 4, respectively. The ram region starts at address 0, denoted by the ORIGIN = 0 command on line 3, and has a length of 0x0040_0000, also shown on line 3. The rom region contains the same commands with different start address and length values as we can see on line 4. These correspond to the graphical representation for the ram and rom regions shown in Figure 11.4.

The SECTIONS command defines the different sections present in the memory layout. The macro SECTION_xxx, where xxx defines the section, takes the parameters region, VMA, and LMA. On line 10, for example, we see that the vectors section has a final location at the beginning of the rom region at absolute address 0xFE00_0000. The next section, text, is also located in the rom section and follows the vectors section, since the VMA address is specified as ALIGN (0x4). The symbol LMA_EQ_VMA, or LMA equals VMA, means that the section is not relocated. We can see the graphical representation of the vectors and text sections in the rom region in Figure 11.4.

Modifying or creating memory regions is accomplished using a property sheet. The Property Sheet dialog box for a memory region is displayed either by selecting the Properties icon on the memory layout tool bar, after the specific region is selected, or double-clicking the desired region. To select a memory region, you can click on the region name. The ram region Property Sheet dialog box is shown in Figure 11.5. New memory regions can be created using the New Region icon on the memory layout tool bar.

The General tab is displayed in Figure 11.5. The information in this dialog box ensures that initial and final locations of relocated memory sections are within the appropriate memory region. The Name chosen for a memory region is up to you; however, it should not contain spaces or punctuation characters. In Figure 11.5, the name of the region is ram. The Start Address and Size are specified in bytes and entered as hexadecimal numbers. We can see in Figure 11.5 that the Start Address for the ram region is 0x0000_0000 and the Size is 0x0040_0000, which corresponds to a size of 4 Mbytes (4,194,304 bytes). Therefore, the address range for the ram region, as we see in Figure 11.4, is from 0x0000_0000 to 0x003F_FFFF. In this case, the Read Only check box is not checked because this is a RAM region of memory. The Notes tab can be used to keep any information about the memory region.

Memory sections are also edited using a property sheet. The Property Sheet dialog box for a memory section is displayed either by selecting the Properties icon on the memory layout tool bar, after selecting a specific region, or double-clicking the desired section. New memory sections can be created using the New Section icon on the memory layout tool bar. Figure 11.6 shows the General tab of the reserved_vsr_table section from the Motorola PowerPC MBX860 platform memory layout.

A memory section is either Linker-defined or User-defined. In Figure 11.6, we see this section is User-defined with the name reserved_vsr_table. The same rules apply for naming memory sections as with memory regions—no spaces or punctuation characters. If the section is Linker-defined, a drop-down list containing the names currently not used are presented. The names in the list vary depending on the selected target architecture. When using a template as the baseline for your development, sections will be set up in the memory layout for you. It is then up to you to determine if they need to be relocated or moved into other memory addresses or if new sections need to be added.

If the Known Size check box is checked, then the size, in bytes, is entered as a hexadecimal number. In Figure 11.6, we see that the reserved_vsr_table has a size of 200, or 512 bytes. User-defined sections that do not contain a size are assumed to occupy all memory up to the next section or the end of memory in that region. The Final Location, or Virtual Memory Address (VMA), defines the final location of the section after relocation. Either an Absolute address can be entered or Following a specific section. In Figure 11.6, the reserved_vsr_table follows the reserved_vectors section, which was selected from a drop-down list. The Alignment of the reserved_vsr_table is also specified on a 1-byte boundary. If an Absolute address is used, this should be entered in hexadecimal.

The next tab in the section property sheet is for Relocation. For the Motorola PowerPC MBX860 platform with ROM Startup Type, the only section that is relocated is the data section. We can see this in Figure 11.4 in the ram region that has the description relocated in the data section box below align 10. In Figure 11.7 we see the Relocation tab for the data section. The Relocate Section check box is checked and the Initial Location, or Load Memory Address (LMA), for the data section is specified. The LMA can be either an Absolute address in hexadecimal or Following a specific section that is selected from a drop-down list. In Figure 11.7, the data section LMA is initially loaded in the rom region following the gcc_except_table section. The General tab in the data section property sheet specifies a VMA, or final location, following the reserved_virtual_table section. If we look at Figure 11.4 we can see that the data section is present in both the rom and ram region. Since the data section is relocated from the rom to ram region, it is grayed in the rom region.

The last tab is the Notes tab, which can be used to keep any information about the memory section.

Let's briefly look at how we would access a user-defined memory section. In this example, we create a user-defined section using the MLT and then go through a code listing showing how this section is accessed. We are using the Motorola PowerPC MBX860 platform with ROM Startup Type.

First, the section kfm1 is created using the MLT, as shown in Figure 11.8. We see the MLT representation of the RAM and ROM memory regions. In the RAM memory region, we see the kfm1 section at the end. The section Properties dialog box is also shown for the kfm1 section. In this case, the section starts at address 0x000A_0000 and is 296 bytes long.

When we save our configuration, the Configuration Tool generates the memory layout header file, mlt_powerpc_mbx_rom.h, automatically. This file is stored in the install tree directory structure under the includepkgconf directory. An excerpt from the memory layout header file with the kfm1 section defined is shown in Code Listing 11.7.

Code Listing 11.7. Memory layout file excerpt showing kfm1 section definitions.

1  #define CYGMEM_SECTION_kfm1 (CYG_LABEL_NAME (__kfm1))
2  #define CYGMEM_SECTION_kfm1_SIZE (0x128)

In Code Listing 11.7, we see that line 1 shows the address definition of our kfm1 section we defined using the MLT. The actual address, 0x000A_0000, is contained in the linker script file mlt_powerpc_mbx_rom.ldi, which is also generated by the Configuration Tool. On Line 2, the size for our new section is defined; in this case, the size is 296 (128 in hexadecimal) bytes.

Code Listing 11.8 shows the example code we implement in our application to access our user-defined section kfm1.

Code Listing 11.8. Example of how to access a user-defined memory section.

 1  #include <pkgconf/system.h>
 2  #include <pkgconf/mlt_powerpc_mbx_rom.h>
 3  
 4  //
 5  // Main starting point for the application.
 6  //
 7  void cyg_user_start( void )
 8  {
 9     // Use the memory section as an integer array.
10     char *user_section = (char *)CYGMEM_SECTION_kfm1;
11     unsigned char user_sect_size = CYGMEM_SECTION_kfm1_SIZE;
12     unsigned int index;
13  
14     // Initialize each element in the kfm1 section of memory.
15     for ( index = 0; index < user_sect_size; index++ )
16        user_section[ index ] = 0;
17  }

In Code Listing 11.8, we see that the header file, mlt_powerpc_mbx_rom.h, which defines our new user section kfm1 is included on line 2. On line 10 we set the variable user_section to our user-defined section address, which allows us to access the section using this local variable. The size of the section is set to the variable user_sect_size on line 11, again allowing us to use a local variable to access the size of our user-defined section. Finally, we initialize the user-defined memory section kfm1 to 0, which is shown on lines 15 and 16, using our local variables user_section and user_sect_size.

11.2.2. eCos Repository Database

The Configuration Tool uses the eCos repository database to understand the components within the repository. The descriptions of the packages in the repository database are contained in the file ecos.db, which is located under the D:ecospackages subdirectory in our installation. This file uses the CDL to describe all packages and targets in the database.

The Configuration Tool needs to know the location of this file, and the entire repository. The Configuration Tool searches for the component repository by first using the most recently used repository location, then by using the default location setup by the installation, and finally, by whatever path you select. The component repository location should already be configured properly from our installation.

If you needed to change the location of the component repository, you could do so by selecting Build –> Repository from the menu bar. This brings up a dialog box that allows you to browse to the new location of the repository.

We can see an example of the relationship between the repository database file, ecos.db, and the Configuration Tool in Figure 11.9. In Figure 11.9, the CDL package description for the eCos HAL is shown along with the Configuration window, the Properties window, and the Short Description window from the Configuration Tool. We can see how the Configuration Tool interprets the CDL package for the eCos HAL in order to display the properties and description correctly. The Configuration Tool uses the CDL script file, hal.cdl, shown on line 4 of the ecos.db code fragment in Figure 11.9, to display the proper components within the eCos HAL package.

Along with all of the package descriptions in the ecos.db file, the template descriptions are also contained within the database file. Template descriptions are used by the Configuration Tool to load pre-configured packages for a particular target platform. Details about using templates can be found in the Using Templates section of this chapter. The template description for the i386 PC target platform is shown in Code Listing 11.9.

We see in Code Listing 11.9, line 1 contains the name of the target; in this case, pc. An alias for the target, which is displayed by the Configuration Tool when selecting a template, is shown on line 2. The packages that are loaded by the Configuration Tool when the i386 PC target template is selected are given on lines 3 through 13. These packages give a baseline of functionality for a given target. Packages can then be configured, added, or removed in order to get the specific configuration you need for your target platform. Finally, lines 15 through 19 give the description of this template.

Code Listing 11.9. i386 PC target template description from eCos database file ecos.db.

 1 target pc {
 2    alias       { "i386 PC target" }
 3    packages    { CYGPKG_HAL_I386
 4                  CYGPKG_HAL_I386_GENERIC
 5                  CYGPKG_HAL_I386_PC
 6                  CYGPKG_HAL_I386_PCMB
 7                  CYGPKG_IO_PCI
 8                  CYGPKG_IO_SERIAL_GENERIC_16X5X
 9                  CYGPKG_IO_SERIAL_I386_PC
10                  CYGPKG_DEVS_ETH_INTEL_I82559
11                  CYGPKG_DEVS_ETH_I386_PC_I82559
12                  CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS12887
13                  CYGPKG_DEVICES_WALLCLOCK_I386_PC
14    }
15    description "
16       The pc target provides the
17       packages needed to run eCos
18       binaries on a standard i386
19       PC motherboard."
20 }

Figure 11.10 shows the template dialog box displaying the i386 PC target from Code Listing 11.9. The template dialog box is displayed when Build –> Templates is selected from the menu bar. We can see in Figure 11.10 that the alias description, from line 2, is displayed in the Hardware drop-down list.

Below the target alias is the description for the template, from lines 15 through 19. In this case, the default packages are included, which are described in the Packages in Selected Templates description box. These packages are listed on lines 3 through 13 in Code Listing 11.9. The different options in the package drop-down list are described in the Using Templates section of this chapter.

In certain circumstances, it might be necessary to edit the ecos.db file in order to have the Configuration Tool recognize a package you added. We look at editing the ecos.db file in Chapter 13, Porting eCos.

A file named ChangeLog is also located in the same subdirectory as the ecos.db file. This log file tracks the changes made to the ecos.db file. Entries to this log file are similar to the entries in the other ChangeLog files described in the Package Directory Structure section in this chapter.

11.2.3. Graphical Representation of CDL Script Files

Now that we have looked at the relationship between the repository database file and the Configuration Tool, let's go a step further and examine the relationship between the CDL script files and their graphical representation in the Configuration Tool.

This section gives us a basic understanding for how the Configuration Tool interprets the commands in the CDL script files and uses this information in its different display windows. All CDL commands and properties are not described in this section; however, you should be able to see the basic relationship between the CDL scripts and the Configuration Tool allowing you to investigate other script details on your own.

As we know from the Packages section in this chapter, every package must have at least one CDL script file to define the package. The Configuration Tool uses the CDL script files to display the necessary configuration and description information so that you can set up the package according to your needs. We use the same CDL script file from the i386 PC HAL package described in Code Listing 11.3, which you can look at to get an overview of where each portion of the CDL script commands are located. The line numbers from Code Listing 11.3 are used in the code fragments located in the figures. Figures 11.11, 11.12, and 11.13 show three different portions of the CDL script file and how the Configuration Tool displays this information. Each figure shows a portion of the Configuration window, the Properties window, and the Short Description window.

First, in Figure 11.11, is the CDL package command. Line 1 gives the macro name of the package CYGPKG_HAL_I386_PC, which can also be seen next to the Macro property in the Properties window. Line 2 uses the display command to give a description of the package, which we can see is used in the Configuration window. The i386 PC Target is part of the i386 Architecture. In order to locate the i386 PC Target package under the i386 Architecture, the parent command shown on line 3 is used.

The different properties, on lines 4, 5, and 11 through 15, for the i386 PC Target are displayed in the Properties window. The description command from lines 6 through 9 is shown in the Short Description window.

Within the i386 PC Target package is the Startup Type component. The CDL script file and Configuration Tool representation for the Startup Type component is shown in Figure 11.12. Because this component is part of the CDL package command i386 PC Target (CYG_HAL_I386_PC) body, the Startup Type component is displayed under the i386 PC Target in the Configuration window hierarchy structure.

Again, we see the macro name, CYG_HAL_STARTUP, on line 17, which is also displayed in the Properties window. The display command, on line 18, gives the Configuration Tool a descriptive name for the component to display in the Configuration window.

The properties on lines 19 through 23 are displayed in the Properties window. One note is that since this component has a flavor property of data and a type property of enumeration, a drop-down list is used to show the legal_values to configure this component. We can see the enumeration type icon, as previously described in Table 11.1, next to the Startup Type description in the Configuration window. The legal_values for the i386 PC Target package Startup Type are RAM, FLOPPY, and ROM.

Finally, we see the description command from lines 24 through 35 displayed in the Short Description window.

Finally, we look at the CDL option command Output to PC Screen in Figure 11.13. The macro for this option is on line 38, CYGSEM_HAL_I386_PC_DIAG_SCREEN. This option is also located within the i386 PC Target package as we can see from the hierarchy structure shown in the Configuration window. Line 39 shows the display command represented in the Configuration window with the text Output to PC Screen.

A check box icon to the left of the display text is used for this option since the flavor property is bool, as shown on line 40 and in the Properties window. The other properties on lines 41 and 42 are displayed in the Properties window as well.

As we have seen with the other CDL script fragments, the description command is used by the Configuration Tool to display text in the Short Description window, shown on lines 43 through 46.

11.2.4. Using Templates

Templates are predefined configurations provided in the eCos repository that load specific packages for a supported hardware platform. As described in Chapter 1, templates are used as a baseline starting point to begin selecting the configuration settings specific to your application.

The templates dialog box, shown in Figure 11.10, is displayed by selecting Build –> Templates from the menu bar. We use a template in Chapter 12 to load a baseline of packages and configuration options for our example application.

The templates dialog box allows the selection of a combination of hardware and package templates. The hardware templates are defined in the eCos database file, ecos.db, using CDL script commands. The hardware template is selected from the drop-down list in the Templates dialog box under the Hardware label.

Beneath the drop-down list is a brief description of the target platform selected. The hardware template ensures that the proper packages are loaded into the Configuration Tool for a particular target platform, including HAL, I/O, and device driver packages. There is a hardware template in the drop-down list for each of the supported evaluation platforms supported by eCos, as shown in Appendix A, Supported Processors and Evaluation Platforms.

The package templates are generic across all hardware platforms and are defined under the templates subdirectory located under the D:ecospackages directory. The package template is also selected from a drop-down list under the Packages label in the Templates dialog box.

Next to the package template list is a drop-down list that allows you to select the version of the package template to load. In this case, the current template version is selected.

A brief description of the package template selected is located beneath the drop-down lists. Clicking the Details button displays a scroll list of the packages that are contained in the package template selected, as shown in Figure 11.10.

Each package template contains its own subdirectory containing a file named current.ect, as well as a ChangeLog file. You can generate your own package template files, which can be useful if you need to incorporate different versions of various packages. Before the new package template is noticed, the Configuration Tool needs to be restarted. The package template files use CDL scripts to define the proper packages to load and configuration options to set according to the template. The package templates included with eCos are defined in Table 1.2 in Chapter 1.

11.2.4.1. Conflicts and Resolutions

When templates are loaded into the Configuration Tool, oftentimes conflicts arise between different components and configuration options. How and when conflicts are displayed depends on the settings selected under the Tools –> Options menu. This allows you to check for conflicts after any item is changed, before saving and building, or never.

When the conflict option Automatically Suggest Fix is selected, a dialog box is displayed when a conflict arises by the Configuration Tool, similar to the one shown in Figure 11.14, which allows you to resolve the conflicts before proceeding with the configuration setup.

As we see in Figure 11.14, the top window displays the conflict that needs to be addressed with the columns Item, Conflict, and Property, which is the same format as the Conflicts window. The bottom window gives a Proposed Solution for each conflict. Each proposed solution can be individually enabled or disabled by selecting the check box in the Item column or a global enable, provided by the All button, and disable, provided by the None button, are included in the dialog box. The default state is that all proposed solutions are enabled. Clicking the Continue button applies the proposed solutions selected. Clicking the Cancel button exits the dialog box without applying any solutions.

If you choose not to apply the proposed solutions, the resolve conflicts dialog box can be displayed later by selecting Tools –> Resolve Conflicts from the menu bar. Unresolved conflicts are also displayed in the Conflicts window and a total count is shown on the bottom-right side of the status bar.

11.2.5. Package Control

After a template has been loaded, it is often necessary to load or unload particular packages to set up the configuration to support all of the features for your application. Adding and removing packages is accomplished by using the Packages dialog box as shown in Figure 11.15. This dialog box is displayed by selecting Build –> Packages from the menu bar.

The left side of the Packages dialog box contains a scroll list of all available packages in the eCos component repository under the label Available Packages. The right side contains a scroll list of the packages currently selected in the configuration under the label Use These Packages. The version of the currently selected package is shown in the drop-down list below the label Version. If multiple packages are selected, the versions common to both packages are displayed in the version drop-down list. A brief description of the package is located below the version. The description window is blank when multiple packages are selected. In Figure 11.15, we see that the current version of the RAM Filesystem package is selected from the available packages.

To add a package to the configuration, select the package from the available packages list and click the Add button. Multiple packages can be selected by holding down the Ctrl key while clicking packages. Next, you select the version of the package you want to add from the Version drop-down list. This contains all versions installed under your component repository installation. Since the current version is the one we installed in Chapter 10, this is the only version shown.

To remove a package from the configuration, select the package from the current packages being used and then click the Remove button. Again, multiple packages can be selected by holding down the Ctrl key while clicking packages.