path: root/user/exe/executables.rst
diff options
authorChris Johns <>2018-05-20 08:32:42 +1200
committerChris Johns <>2018-11-03 16:36:32 +1100
commit8b67c9135cb78abc394d43e449ccc6387c73f014 (patch)
tree6d4a21905a43cc4f476a1d6013baf151ce39ade5 /user/exe/executables.rst
parent21c1a4492a6c437d057c3af605278e9ba5edcac0 (diff)
user: Add RTEMS executable and test documentation.
Diffstat (limited to '')
1 files changed, 102 insertions, 0 deletions
diff --git a/user/exe/executables.rst b/user/exe/executables.rst
new file mode 100644
index 0000000..d911006
--- /dev/null
+++ b/user/exe/executables.rst
@@ -0,0 +1,102 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. comment: Copyright (c) 2018 Chris Johns <>
+.. comment: All rights reserved.
+RTEMS Executable
+.. index:: RTEMS Executable
+Running executables is the most important part of working with RTEMS, it is
+after all how you run your application and use the RTEMS kernel services.
+An RTEMS executable is embedded in a target and executing an embedded
+executable has challenges not faced when executing software on a desktop or
+server computer. A desktop or server operating system kernel provides all the
+support needed to bring an executable's code and data into a process's address
+space passing control to it and cleaning up when it exits. An embedded target
+has to provide similar functionality to execute an embedded executable.
+An RTEMS Source Builder (RSB) built RTEMS tool chain is used to create RTEMS
+executables. The tool chain executable creates a fixed position statically
+linked Extendable Loader Format (ELF) file that contains the RTEMS kernel,
+standard libraries, 3rd party libraries and application code. RTEMS executes in
+a single address space which means it does not support the ``fork`` or ``exec``
+system calls so statically linking all the code is the easiest and best way to
+create an executable.
+An RTEMS application is constructed vertically with the RTEMS kernel, BSP
+support code and drivers close to the hardware, above which sit the RTEMS
+Application Programming Interfaces (API) for control of threads, mutex and
+other resources an application may use. Middle-ware services like networking,
+interpreted languages, and protocol stacks sit between the RTEMS APIs and the
+application components. The software built into an executable can be see as a
+vertical software stack.
+.. _fig-exe-vert-stack:
+.. figure:: ../../images/user/exe-vert-stack.png
+ :width: 35%
+ :alt: Vertical Software Stack
+ :figclass: align-center
+ Vertical Software Stack
+Building an Application
+.. index:: Building an Application
+RTEMS views any code it is running and using it's interfaces as an
+application. RTEMS conforms to a number of international standards such as
+POSIX and can build and run portable code written in languages such as C, C++
+and Ada.
+Applications are built from source into ELF object files, 3rd party packages
+can be built as libraries or they can be imported as source into an application
+code base. The application, 3rd party packages, RTEMS and standard libraries
+are linked to create the RTEMS executable. The executable is transferred to the
+target and a bootloader loads it from the non-volatile storage into RAM or the
+code is executed in place in the non-volatile storage. The target hardware
+defines what happens.
+.. _fig-exe-app:
+.. figure:: ../../images/user/exe-app.png
+ :width: 90%
+ :alt: Building an Application
+ :figclass: align-center
+ Building an Application
+The standard and 3rd party libraries are a collection of object files built
+using the same set of tools the application source is compiled with. The
+package collects it's object files into an archive or library.
+RTEMS does not provide a standard application build system. The RTEMS ecosystem
+provides support so a range of build systems can be used. Applications can be
+built with ``make``, ``autotools``, ``cmake``, ``waf`` and more. User should
+select a build system that meets their project, system, corporate or personal
+Machine Flags and ABI
+.. index:: Machine flags
+.. index:: Application Binary Interface
+.. index:: ABI
+All code in an RTEMS executable must be built with the same machine flags. The
+machine flags control the instruction set and application binary interface
+(ABI) the compiler generates. As the executable is statically linked all code
+must use the same instruction set the hardware is configured to support and all
+code must conform to the same ABI. Any variation can result in unpredictable
+behavior such as crashes, failures or lock ups. It is recommend an executable
+is built with the same or equivalent tool set. Mixing of tool set versions can
+also result in undefined behavior. The RTEMS tool ``rtems-execinfo`` can audit
+an RTEMS executable and list the machine flags and compilers used.
+RTEMS by default does not support instruction emulation for unsupported
+instructions. RTEMS applications are normally built from source so binary
+compatibility is not as important as performance. Instruction emulation is
+costly to execute and rebuilding the executable with the correct instruction
+set only needs to be done once.