From 8b67c9135cb78abc394d43e449ccc6387c73f014 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Sun, 20 May 2018 08:32:42 +1200 Subject: user: Add RTEMS executable and test documentation. --- user/exe/executables.rst | 102 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 user/exe/executables.rst (limited to 'user/exe/executables.rst') 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 +needs. + +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. -- cgit v1.2.3