.. 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.