Revision as of 18:00, 8 January 2013

Introduction

Purpose

This document is intended for software architects, designers, and developers, and should provide the necessary input during the design, implementation and maintenance of the XCDL framework.

Scope

This document refers to the XCDL configuration definition language, the XCDL framework and the associated build process.

The main focus of XCDL is to support cross-building embedded system images.

The XCDL framework will include several tools to:

• generate build configurations
• manage the specific metadata

The toolchains and other general purpose tools used by XCDL during the build process are not considered part of the XCDL framework.

Definitions and acronyms

• CDL - the Configuration Definition Language, as the configuration mechanism used by eCos
• XCDL - the eXtensible Configuration Definition Language and framework, inspired by CDL
• XCDL software component - a set of source files that perform a given function, standalone or depending on other components, together with some metadata
• XCDL component metadata - additional informations added to software components to describe dependencies, requirements and constraints
• XCDL configuration tools - tools running on development machines to create and manage XCDL configurations and component metadata
• XCDL configurations - specific metadata definitions, that describe the requirements of an application, like which components are enabled, the values for preprocessor definitions, toolchain selection, build details, etc
• XCDL build configurations - the result of processing an XCDL configuration, usually a build folder with associated build related files (like GNU Make files)
• XCDL requirements - direct requirements, generally components that are mandatory for the build to succeed, like base classes
• XCDL constraints - in general hardware dependencies, like the presence of a certain peripheral, but dependencies to software options can also be used

References

• eCos - The embedded configurable operating system by Cygnus Solutions (Wikipedia)
• Manual: The eCos Component Writer’s Guide, by Bart Veer and John Dallaway, published in 2001, available from eCos Documentation.
• Book: Embedded software development with eCos, by Anthony J. Massa, published in 2003 at Prentice Hall, available from Amazon
• Book: Software Build Systems: Principles and Experience, by Peter Smith, published in 2011 at Addison Wesley, available from Amazon
• IEEE Std 830-1998: IEEE Recommended Practice for Software Requirements Specifications, published in 1998

Overview

This document is based on IEEE Std 830-1998 recommendations, but may not follow them by the letter.

Overall description

Product perspective

The XCDL definition language is functionally inspired by eCos CDL, but has a different syntax and supports a slightly different functionality.

The initial versions of the XCDL tools will be written in Python and should be able to run on OS X, GNU/Linux and Windows.

These tools shall allow to:

• create new configurations by selecting from existing platforms and templates
• enable/disable various components
• configure various variables
• generate build configurations (like build trees and associated makefiles)

These tools might also:

• manage component metadata (create/edit metadata definitions)

All configuration operations shall be available from command line environments. Additional graphical versions of the tools, running standalone or integrated in various IDEs (like Eclipse, Xcode), are considered for future versions of the framework.

The build process based on the build configurations generated shall be able to run from unattended scripts, to support continuous integration.

Product functions

The XCDL definitions should be able to describe the dependencies between various software components in order to:

• minimize the number of source files processed during the build
• generate a consistent set of preprocessor definitions
• assist XCDL tools in creating and managing configurations

User characteristics

There are several roles for XCDL users:

• application software developer, who contributes application code to a given project
• application project manager, who creates and manages application configurations
• enterprise component developers, who create and manage private XCDL components (the equivalent of enterprise libraries) to be used in multiple applications
• open source component developers, who create and manage public XCDL component repositories, like µOS++ Second Edition.

Constraints

The XCDL tools should be able to run on OS X, GNU/Linux and Windows.

Assumptions and dependencies

The current version of the SRS is based on the initial experience with the first Python prototype version, and is intended to support the development of µOS++ Second Edition. As implementation will progress, it is possible that new features will be considered.

Apportioning of requirements

Integration of configuration tools and of generated build configurations with IDEs like Eclipse, Xcode etc will be considered in the next versions of the XCDL framework.

Specific requirements

External interface requirements

Q: How does the software interact with people, the system’s hardware, other hardware, and other software?

The XCDL framework does not directly interact with system hardware, or with other hardware.

It does interact with people, via the command line interface.

It also interacts with development tools, i.e. generates files to be used by GNU Make.

Future versions might also interact with:

• people via custom graphical tools
• people via industry standard IDE tools, like Eclipse

Interactions with the application developer(s)

During application development, the most often performed operation by the application developer is the build process.

The input is:

• the XCDL configuration

The output is:

• the final application image, usually a binary file.

Interactions with the application project manager

The next interaction with people is the creation of the XCDL configurations.

The input is:

• one or several enterprise component repositories
• one or several open source component repositories
• the user selection.

Using the XCDL configuration tool, the project manager selects:

• the board where the application is intended to run
• one or more configuration templates referring to the components needed by the application (like minimal, network, usb, etc)
• the toolchain to be used

The project manager then:

• enables/disables various components
• sets different values to various options, like number of threads, stack sizes, etc

The output of this process is:

• the XCDL configuration.

The XCDL configuration can be later edited, either manually with a text editor, or with the XCDL configuration tools.

Interaction with the component developers

The component developers, who create and manage XCDL components (the equivalent of libraries), need to create, in addition to the usual source files, some XCDL component metadata to describe dependencies, requirements and constraints.

There can be enterprise or open source component repositories.

The XCDL component metadata can be edited either with a text editor, or with the XCDL configuration tools.

Functional requirements

Q: What is the software supposed to do?

In the first version of the XCDL configuration tools, the build process will be done in the usual way, in two steps:

• from the XCDL configuration, generate the build folder and the required GNU Make files
• run GNU Make in the build folder to compile and link the application

Future versions might integrate them, possibly integrating parts of the sCons project.

In the first version of XCDL, there are at least two separate tools:

• configMakefile - that will generate the build folder and the Make files
• xcdlConfig - that will create and manage the XCDL configuration file

The configMakefile tool

The configMakefile tool takes as input:

• a list of folders where XCDL repositories are located (so any number of open source or enterprise repositories are accommodated)
• an XCDL configuration file, defining multiple build configurations, like Debug/Release, eventually running on multiple boards
• the internal id of the specific configuration
• the id of the desired toolchain

The output is:

• the build tree and the GNU Make files

The xcdlConfig tool

For the initial run, the xcdlConfig tool takes as input:

• a list of folders where XCDL repositories are located (so any number of open source or enterprise repositories are accommodated)

The output is:

• the XCDL configuration file
• an optional log file

For subsequent configuration edits, the input also includes:

• the XCDL configuration file

In future versions it might be possible to also edit XCDL metadata files.

At user request, the list of folders where XCDL repositories are located can be saved in the XCDL configuration file, so that subsequent invocations will need only the configuration file. Similarly the configMakefile invocation will be simplified.

However please note that storing absolute paths in configuration files makes the configuration files non-portable, so they cannot be saved in revision control systems and used on other platforms.

The XCDL metadata trees

By default, the metadata associated to various software components shall follow the same hierarchy as the folders where the components are stored. Custom hierarchies should be possible, by defining explicit parent nodes.

The tree nodes are XCDL objects, each with specific properties:

• package
• component
• option
• interface
• configuration

Nodes can have distinct status attributes:

• isLoaded
• isEnabled
• isActive

Since multiple boards can be supported by an XCDL component repository, it makes no sense to have all loaded during the configuration process, but only the board required for the application. Loading a node automatically loads all parent nodes, recursively. Nodes not loaded are not presented in the XCDL configuration tools.

During the configuration process the user may select which components to include in the build and which components are not needed, by manually enabling/disabling components. Disabling a component automatically disables all children components. Components may have requirements, so enabling a component may automatically trigger enabling other components, recursively.

Components may also have constraints, for example a certain driver may be optimised to use the DMA, but only if the peripheral supports DMA. Common constraints are related to hardware, but software constraints can be defined too. The active/inactive state is automatically computed, and a component is active if and only if all of its constraints are satisfied.

In addition to dependencies definitions, the XCDL metadata should provide some grouping definitions, to assist the XCDL tools in providing meaningful suggestions for major selections, for example when creating a new configuration the list of available boards should be presented.

Performance requirements

Q: What is the speed, availability, response time, recovery time of various software functions, etc.?

Considering that the XCDL tools will usually run on development machines, which have more than average resources (RAM and CPU), the tools performances shall not be an issue.

Design constraints

Q: Are there any required standards in effect, implementation language, policies for database integrity, resource limits, operating environment(s) etc.?

The first version of XCDL will be written in Python 2.7.

The XCDL metadata should be stored in standard text files, editable with common text editors.

The first version will store the metadata in Python format (files with .py extension). Future versions might also accept other formats, like JSON.

Software system attributes

Q: What are the portability, correctness, maintainability, security, etc. considerations?

Being written in Python, the configuration tools are, at least theoretically, portable.

Other requirements

Tip: Should not describe any design or implementation details.

• the XCDL framework shall not be specific to a versioning system, svn/git/hg/etc shall be accepted
• the build configs may run on identical or different hardware (different boards, different processors, different amounts of ram/flash, etc); an example of such a config was used for the Metrilog SDI-12 sensors, where the Debug config used a larger AVR than the Release.
• shall allow multiple toolchains
• shall be C/C++ centric and shall handle C/C++ dependencies automatically (obviously)
• shall provide support for testing (continuous integration)
• shall provide support for custom build steps, using external tools (for example for adding a binary checksum, custom metadata, etc)

Future versions:

• should allow integration with Eclipse CDT
• might allow integration with other IDEs like Visual Studio, NetBeans

• should provide as much help as possible to specific steps like flash programming, debug, profiling
• might provide support for documentation generating tools (Doxygen)