The XCDL.py Software Requirements Specifications

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 multi-variant cross-building embedded system images.

By multi-variant it should be understood:

• multiple processor architectures (like ARM Cortex-M), with multiple sub-architectures (like M3, M4, M0), multiple manufacturer variants (like STM32F1, STM32F4), multiple families (like STM32F10x Connectivity Line) and multiple devices (like ST STM32F107VG)
• as an extension to architectures, synthetic architectures, like POSIX, should be supported
• multiple hardware platforms (boards, board revisions)
• multiple synthetic run platforms (like OS X, GNU/Linux)
• multiple toolchains (like GCC, LLVM clang)
• multiple build platforms (like OS X, GNU/Linux, Windows)

The XCDL framework will include several tools to:

• generate the artefacts defined by various 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 used, 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); when IDEs (like Eclipse) are used, it translates to an IDE build configuration
• 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.

The first priority is a tool to perform the build process for a given build configuration, described in a manually written set of XCDL definitions. To simplify things, this tool can rely on standard tools, like GNU make. In other words, this tool should generate the build trees with associated makefiles, and run make to perform the actual build.

The second priority is a set of tools to manage the XCDL build configurations. These tools shall allow to:

• create new build configurations by selecting from existing platforms, templates and toolchains
• enable/disable various components
• configure various variables

Until these tools will be available, the build configurations (Python code) will be manually edited with any text editor.

The third priority is a set of tools to manage (create/edit) all the XCDL definitions describing the components and the dependencies between them. Until these tools will be available, the XCDL definitions (Python code) will be edited with any regular text editor.

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 is at least one tool:

• xcdlBuild - that will generate the build folder with the make files, and will run make to build the final artefact

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 xcdlBuild tool

The xcdlBuild tool takes as input:

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

The output is:

• the build tree and the result of running the GNU make files

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 (seems not really necessary)
• component
• option
• interface
• configuration

Nodes can have distinct status attributes:

• isUsed
• isEnabled
• isActive
• isConfigurable

Since multiple boards can be supported by an XCDL component repository, it makes no sense to have all existing boards in use during the configuration process, but only the board required for the application. Using a node automatically uses all parent nodes, recursively, and also all children nodes, recursively. Nodes not in use 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 revision control 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)