DO NOT FORK OR CLONE THIS REPOSITORY
This is an unofficial fork of eChronos. Please use the official echronos repository instead.
The eChronos RTOS is a real-time operating system (RTOS) originally developed by NICTA and Breakaway Consulting Pty. Ltd.
It is intended for tightly resource-constrained devices without memory protection. To this end, the RTOS code base is designed to be highly modular and configurable on multiple levels, so that only the minimal amount of code necessary is ever compiled into a given system image.
Available implementations currently target ARM Cortex-M4, and (as of writing, only QEMU-emulated) PowerPC e500.
To obtain the source code, use the following commands:
git clone https://github.com/echronos/echronos.git cd echronos
See the Prerequisites section for instructions on downloading and installing all prerequisites. The following assumes they have been set up.
Set up the build environment:
Build and run an example system for the RTOS variant Rigel on QEMU-emulated ARMv7-M:
prj/app/prj.py build machine-qemu-simple.example.rigel-system # Run the generated system in qemu (press `ctrl-c` to close QEMU after it is finished) qemu-system-arm -M simple-armv7m -S -s -nographic -semihosting -kernel out/machine-qemu-simple/example/rigel-system/system # To connect and view debug output run gdb in another shell prompt # Note: The Rigel example will end by deliberately triggering a fatal error arm-none-eabi-gdb -ex "target remote :1234" -ex "b fatal" out/machine-qemu-simple/example/rigel-system/system (gdb) c ... task a: start delay irq tick irq tick irq tick irq tick task a: complete delay Breakpoint 1, fatal (error_id=error_id@entry=1 '\001') (gdb) quit
Build and run an example system for the RTOS variant Kochab on QEMU-emulated PowerPC e500:
prj/app/prj.py build machine-qemu-ppce500.example.kochab-system # Run the generated system in qemu (press `ctrl-a` then 'x' to close QEMU after you are finished) qemu-system-ppc -M ppce500 -S -s -nographic -kernel out/machine-qemu-ppce500/example/kochab-system/system # To connect and view debug output run gdb in another shell prompt # Note: The Kochab example will end with task b cycling forever between "blocked" and "unblocked" powerpc-linux-gnu-gdb -ex "target remote :1234" -ex "b debug_print" out/machine-qemu-ppce500/example/kochab-system/system (gdb) c ... Breakpoint 1, debug_print (msg=0x33b4 "tick") (gdb) c Breakpoint 1, debug_print (msg=0x33e8 "task b blocking") (gdb) c Breakpoint 1, debug_print (msg=0x33b4 "tick") (gdb) c Breakpoint 1, debug_print (msg=0x33f8 "task b unblocked") (gdb) quit
The following tools are supplied with this repository in the
- Python 3.3 for the Python scripts in the repository
arm-none-eabiGNU toolchain and
arm-none-eabi-gdbfor building and debugging the RTOS for ARMv7-M
setenv script makes these tools the default ones by including them in the PATH environment variable.
To obtain and build
qemu-system-arm with target
simple-armv7m for testing the
machine-qemu-simple systems, run:
git clone https://github.com/BreakawayConsulting/QEMU.git cd QEMU ./configure --target-list=arm-softmmu --disable-cocoa --disable-curses --disable-vnc --disable-tools --without-pixman --disable-console --disable-default-devices --disable-slirp --disable-curl --disable-guest-base --disable-guest-agent --disable-blobs --audio-drv-list= --audio-card-list= --disable-usb --disable-ide --disable-pie --enable-debug --disable-sdl --disable-fdt --disable-spice --disable-xen --disable-werror make export PATH=`pwd`/arm-softmmu:$PATH
To obtain the
powerpc-linux-gnu GNU toolchain for building the RTOS for PowerPC e500 on Ubuntu Linux systems, run:
sudo apt-get install gcc-powerpc-linux-gnu
To obtain the
qemu-system-ppc emulator for running the
machine-qemu-ppce500 systems on Ubuntu Linux systems, run:
sudo apt-get install qemu-system-ppc
To obtain, build, and install
powerpc-linux-gnu-gdb for debugging PowerPC e500 systems, run:
git clone git://sourceware.org/git/binutils-gdb.git mkdir gdb-powerpc-linux-gnu cd gdb-powerpc-linux-gnu ../binutils-gdb/configure --target=powerpc-linux-gnu --with-expat=yes --with-libexpat-prefix=/usr/local make make install
Note that building
powerpc-linux-gnu-gdb requires the
expat C library for parsing XML and you may need to install this first.
On Ubuntu Linux systems this can be done by:
sudo apt-get install libexpat-dev
wkhtmltopdf needed for building user documentation on Ubuntu Linux systems:
sudo apt-get install pandoc sudo apt-get install wkhtmltopdf
Basic RTOS concepts and usage are documented in this README.
Pregenerated RTOS API manuals can be found on the eChronos GitHub wiki.
They can also be generated with the command
x.py build docs.
The software model and structure of the RTOS is governed by two stages of customization.
In the first stage, features, in the form of components, are customized for and composed into variants of the RTOS such that each variant has a specific feature set.
This stage is supported by the
In the second stage, the RTOS variant is customized to the specific properties and requirements of a specific application.
Although this customization is limited to the functionality provided by the given variant, it controls details such as the number of tasks required by the application.
This stage is supported by the
The two stages can optionally be separated by deploying a product release to an application project. The application project is then only exposed to the second stage and the variant and functionality of the RTOS they require.
The following sections cover these concepts in more detail.
Variants and Components
The RTOS comes in a number of different variants, each offering a specific set of features for a particular platform.
The RTOS variant Rigel supports tasks, co-operative round-robin scheduling, mutexes, signals, and interrupt events which can trigger the sending of signals. It is available for QEMU-emulated ARMv7-M.
The RTOS variant Kochab supports tasks, preemptive priority scheduling, mutexes with priority inheritance, semaphores, signals, and interrupt events which can cause task preemption and trigger the sending of signals. It is available for the ARMv7-M STM32F4-Discovery board, and QEMU-emulated PowerPC e500.
Features are implemented as individual components in individual C files.
Unlike typical C-based software, the RTOS does not compile components individually and later link them into a single binary.
Instead, the RTOS
x.py tool merges the component files of a variant into a single C file called the RTOS module.
The feature set of each RTOS variant is specified within the
x.py tool itself.
This allows for better compile-time optimizations.
x.py tool also supports building product releases of the RTOS.
A product release bundles a set of variants and target platforms tailored for a certain application product that builds on the RTOS.
Thus, the application product sees only what it needs without being needlessly exposed to all features and platforms supported by the RTOS.
The variants and platforms contained in a release are defined by
Systems, Modules and Packages
An RTOS system encompasses the entirety of the OS and an application on top of it. It consists in particular of:
- the OS in the form of a variant of the RTOS with a feature set suitable for the application (e.g., which form of scheduling is supported)
- a system configuration that tailors the variant to the specific application instance (e.g., how many task or mutexes the application requires)
- the application code itself
Systems are built via the
prj tool which implements the RTOS build system.
At the build system level, systems are composed of modules (such as the RTOS module), so modules provide the unit of composition and reusability.
In its simplest form, a module is a C file and that is usually all that applications need to know about modules. However, modules can consist of the following elements:
- Entity definition file named
<module_name>.py, specifying the module contents and customization options by providing a
- C and header file named
<module_name>.c/h, providing the public interface and its implementation of the module in C
- Assembly file named
<module_name>.s, providing the module functionality as assembly code
- Linker script named
<module_name>.ld, specifying linker commands for linking the system (not just the module)
- XML Configuration schema (as a standalone file or integrated into the entity definition script or source code files), specifying the configuration parameters supported by the module
- Builder module script
<module_name>.py, defining a
system_build()function to be executed in order for the system to be built. The presence of this function distinguishes the module as a Builder module.
A system is statically defined and configured in its system configuration in a
This is an XML file that lists the modules that make up a system and provides configuration parameters for each of the modules.
.prx file includes a static declaration of all the RTOS resources used by the system, including all tasks, mutexes, semaphores, interrupt handlers, etc.
prj tool reads
.prx files and composes, compiles, and links all the code to produce a system binary.
A complete system typically consists of
- an RTOS module
- modules dictating the build process for the target platform
- one or more modules containing platform-specific assembly code needed by the RTOS variant to implement low-level OS functionality
- one or more modules containing user-provided code that implement the application functionality
For example, the Kochab RTOS example system for QEMU-emulated PowerPC e500 (defined in
packages/machine-qemu-ppce500/example/kochab-system.prx) contains the following modules:
ppce500.rtos-kochab, the Kochab variant of the RTOS for ppce500.
ppce500.default-linker, which define building and linking for ppce500.
ppce500.vectable, which provide assembly-level RTOS code for ppce500.
generic.debug, which define stubs for debug printing.
machine-qemu-ppce500.example.kochab-test, the user-provided test program for Kochab QEMU-emulated PowerPC e500.
On the file system, modules are grouped into packages, allowing modules to be organised based on common characteristics (such as platform or intended usage).
For example, the PowerPC e500 RTOS variant modules are grouped together with the
vectable modules in the
As another example, platform-agnostic RTOS example code such as the
timer-test modules are grouped together in the
As described above,
x.py provides the means to generate all the different RTOS variants and
prj provides the means to combine an RTOS module with other modules to produce a system binary.
There are two main steps in building an RTOS-based system from the RTOS repository.
Step 1: Generate the RTOS variants.
./x.py build packages
This generates all the RTOS variants.
For each variant specified in
x.py it finds the appropriate components and combines them into the RTOS variant.
The resulting variant can be found in
Please look at the documentation inside
x.py for more information on the tool.
Step 2: Build a system.
prj/app/prj.py build <system name>
This finds the appropriate
.prx file, combines the required modules and generates a system binary.
prj can be further configured using the top level
project.prj file, which specifies tasks that are automatically performed when
prj is run as well as the locations to look for modules and
.prx configuration files.
As a convenience
prj can be configured to automatically regenerate RTOS modules whenever it is run.
This is done by including the following line in the
<startup-script>./x.py build partials --allow-unknown-filetypes</startup-script>
prj/manuals/prj-user-manual for more information on the
components directory contains the RTOS component source and documentation.
packages directory provides various platform-specific RTOS modules and other source modules.
RTOS modules generated by
x.py are output to locations within the
packages directory structure.
x.py tool provides an interface for:
- RTOS module and product release generation (
- task management (
x.py task), and
- testing (
prj directory contains everything related to the
prj tool, which provides an interface for configuring and building systems as compositions of source modules.
release directory is created by
x.py, and contains all releasable artifacts such as product releases.
tools directories contain external tools committed to the repository in order for the repository to be self-contained in its ability to provide everything that is needed for development.
tools/LICENSE.txt for license information regarding the contents of these directories.
pm directory contains project management related meta-data.
This meta-data is crucial for documenting that our internal development processes are correctly followed, as well as providing a record for external audit.
The feature documentation for completed development tasks resides in
pm/tasks/completed, and their reviews can be found under
docs directory contains various release documentation-related content, including templates for auto-generated manuals and top-level README files for product releases.
rtos directory contains a model of the RTOS schedulers implemented in Python for testing purposes.
Common Development Tasks
Developing a RTOS variant
To generate the code for all available RTOS variants:
./x.py build packages
The resulting RTOS code is placed into
The RTOS variants themselves are specified as lists of components within
Adding a new RTOS variant means adding the appropriate list entries to
x.py, and adding new component code in the
components directory structure if necessary.
Please see the existing component code under
components for examples on how to develop RTOS components.
Building user documentation
Manuals for all RTOS variants are built using:
./x.py build docs
The manuals are output to
packages/<platform>/rtos-<variant>/documentation.* in HTML, Markdown and PDF.
Like the RTOS component code, the user manual content is componentized so that only the user documentation for components present in a particular RTOS variant appears in the user manual for that variant.
components/*/docs.md for examples of componentized user documentation.
To build just the
prj tool binary for stand-alone use:
# The `prj` binary is output to `prj_build_x86_64-unknown-linux-gnu/prj` ./x.py build prj
Configuring and building a system
To build a system, use the
prj build sub-tool of
prj, supplying the system name as argument.
The name of the system is the basename of its
.prx file, minus its
.prx extension, appended to a dot-separated string indicating the sub-package location in which it can be found.
For example, to build the system whose
.prx file is located at
packages/machine-qemu-ppce500/example/kochab-timer-demo.prx, from the top level of the repository:
prj/app/prj.py build machine-qemu-ppce500.example.kochab-timer-demo
Alternatively, assuming the
prj tool binary is on the PATH:
prj build machine-qemu-ppce500.example.kochab-timer-demo
Building a product release
To build all product releases, run:
. setenv ./x.py build prj ./x.py build docs ./x.py build partials ./x.py build release
The releases are defined in the top-level
release_cfg.py script and are generated by
Each product release contains:
README.mdfile containing a brief introduction to the release
build_infofile containing the commit hash of the RTOS repository from which the release was built
sharedirectory, containing the package directory structure containing all the released packages
- a pre-built
prjbinary for the host platform targeted by the release
Note that any user manuals available for each RTOS variant in the release can be found at
share/packages/<platform>/rtos-<variant>/documentation.* in HTML, Markdown and PDF.
Using a product release
After unpacking the product release, create a
project.prj file for your software project in order to be able to use the
prj tool that comes packaged with the release.
project.prj contains, at the very least, a
search-path entry to give
prj a hint as to where to find modules.
Here is a example that points to its relative location from the root of the release:
<?xml version="1.0" encoding="UTF-8" ?> <project> <search-path>share/packages</search-path> </project>
After this, the
prj binary packaged with the release can be used in the same way as in the RTOS repository.
Additional application code can be placed in other directories as long as they are included as search paths in the project.prj file.
For example, to build the Kochab timer demo system provided with the PowerPC e500 release of the RTOS for Linux, run:
x86_64-unknown-linux-gnu/bin/prj build machine-qemu-ppce500.example.kochab-timer-demo
Note that the PATH environment variable needs to be set up manually so that it includes the tools invoked by