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. --- README.txt | 43 ++++- images/user/exe-app.puml | 72 ++++++++ images/user/exe-debug-jtag.ditaa | 33 ++++ images/user/exe-debug-libdebugger.ditaa | 43 +++++ images/user/exe-debug-qemu.ditaa | 23 +++ images/user/exe-debug.ditaa | 20 ++ images/user/exe-vert-stack.puml | 56 ++++++ images/user/test-cfg-1.puml | 20 ++ images/user/test-cfg-2.puml | 35 ++++ images/user/test-gdb-jtag.puml | 35 ++++ images/user/test-simulation.puml | 23 +++ images/user/test-tftp-seq-1.puml | 35 ++++ images/user/test-tftp-seq-2.puml | 39 ++++ images/user/test-tftp-seq-3.puml | 33 ++++ images/user/test-tftp-seq-4.puml | 26 +++ images/user/test-tftp.puml | 29 +++ user/exe/debugging.rst | 119 ++++++++++++ user/exe/executables.rst | 102 +++++++++++ user/exe/execution.rst | 49 +++++ user/exe/index.rst | 19 ++ user/exe/initialization.rst | 130 +++++++++++++ user/index.rst | 6 +- user/test/create.rst | 7 - user/test/index.rst | 10 - user/test/running.rst | 26 --- user/testing/configuration.rst | 312 ++++++++++++++++++++++++++++++++ user/testing/consoles.rst | 66 +++++++ user/testing/gdb-jtag.rst | 28 +++ user/testing/index.rst | 46 +++++ user/testing/simulation.rst | 27 +++ user/testing/tests.rst | 210 +++++++++++++++++++++ user/testing/tftp.rst | 257 ++++++++++++++++++++++++++ user/tools/tester.rst | 4 +- 33 files changed, 1934 insertions(+), 49 deletions(-) create mode 100644 images/user/exe-app.puml create mode 100644 images/user/exe-debug-jtag.ditaa create mode 100644 images/user/exe-debug-libdebugger.ditaa create mode 100644 images/user/exe-debug-qemu.ditaa create mode 100644 images/user/exe-debug.ditaa create mode 100644 images/user/exe-vert-stack.puml create mode 100644 images/user/test-cfg-1.puml create mode 100644 images/user/test-cfg-2.puml create mode 100644 images/user/test-gdb-jtag.puml create mode 100644 images/user/test-simulation.puml create mode 100644 images/user/test-tftp-seq-1.puml create mode 100644 images/user/test-tftp-seq-2.puml create mode 100644 images/user/test-tftp-seq-3.puml create mode 100644 images/user/test-tftp-seq-4.puml create mode 100644 images/user/test-tftp.puml create mode 100644 user/exe/debugging.rst create mode 100644 user/exe/executables.rst create mode 100644 user/exe/execution.rst create mode 100644 user/exe/index.rst create mode 100644 user/exe/initialization.rst delete mode 100644 user/test/create.rst delete mode 100644 user/test/index.rst delete mode 100644 user/test/running.rst create mode 100644 user/testing/configuration.rst create mode 100644 user/testing/consoles.rst create mode 100644 user/testing/gdb-jtag.rst create mode 100644 user/testing/index.rst create mode 100644 user/testing/simulation.rst create mode 100644 user/testing/tests.rst create mode 100644 user/testing/tftp.rst diff --git a/README.txt b/README.txt index 203c45d..299c94e 100644 --- a/README.txt +++ b/README.txt @@ -22,6 +22,8 @@ The PDF format is created using Latex and that uses texlive packages. This exposes us to the complex world of Latex however the quality of the documents created is worth it. +Images can be created from source using PlantUML and Ditaa. + Production Quality Hosts ------------------------ @@ -36,12 +38,50 @@ The hosts which produce production quality is: NOTE: RedHat Enterprise Linux (RHEL) and Fedora should be the same as CentOS. +Images +------ + +All images should be placed int he 'images' directory and referenced from the +ReST with a relative path. This lets us shared and control images. + +We prefer being able to build images from source. This is not always possible +so SVG format is preferred with generated PNG images so make sure the quality +is consistent when building PDF output. + +We support the PlantUML image language. The PlantUML home page is: + + http://plantuml.com/ + +The page as a link to an 'online demo server' you can use to create images +rathre than installing PlantUML. Save you source then View and save the PNG +format image. The PlantUML language reference guide is: + + http://plantuml.com/PlantUML_Language_Reference_Guide.pdf + +And the web site has online documentation. The image source extension is +'.puml'. + +We also support Ditaa image language. The Ditaa home page is: + + http://ditaa.sourceforge.net/ + +The home page contain the language options. The PlantUML online demo server +supports Ditaa so use that resource as an online tool. The Ditaa image source +extension is '.ditaa'. + +You do not need PlantUML or Ditaa install to build our documentation. The +online resources can be used. Save the source and the generated PNG file in the +same directory under 'images'. + Host Setup ---------- HTML builds directly with Sphinx, PDF requires a full Latex (texlive) install, and building a Single HTML page requires the 'inliner' tool. The -sphinxcontrib-bibtex extension is mandatory. +sphinxcontrib-bibtex extension is mandatory. PlantUML requres the Node.js +package called 'nde-plantuml' which installs the 'puml' command and Ditaa needs +the 'ditaa' command and package. Ditaa images are built using the 'puml' +command. Please add your host as you set it up. @@ -182,7 +222,6 @@ PATH: export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH} export PATH=${HOME}/.local/bin:${PATH} - Arch Linux ~~~~~~~~~~ diff --git a/images/user/exe-app.puml b/images/user/exe-app.puml new file mode 100644 index 0000000..0ca2c69 --- /dev/null +++ b/images/user/exe-app.puml @@ -0,0 +1,72 @@ +' +' Executable Application +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startuml + + folder Application { + file app1.c + file app2.c + } + + rectangle "3rd Party\nHeaders" as 3rd_party_headers { + folder headers as pkg_headers + } + + folder rtems_headers { + file rtems.h + } + + folder std_headers { + file stddef.h + file stdio.h + } + + agent cc + file objects + + Application --> cc : app1.c\napp2.c + pkg_headers --> cc : -Ipkg + rtems_headers --> cc : -Irtems + std_headers --> cc + cc --> objects: **compile** + + rectangle "3rd Party\nLibraries" as 3rd_party { + package libpkg as pkg + } + + folder librtems { + folder rtems + folder posix + folder sapi + folder score + } + + folder stdlibs { + file libc + file libm + file "libstdc++" + } + + agent ld + + objects --> ld : app1.o\napp2.o + pkg --> ld : -lpkg + librtems --> ld : -lrtems + stdlibs --> ld : "-lm\n-lstdc++" + + file executable + + ld --> executable: **link** + + rectangle Target { + agent bootloader + agent memory + } + + executable --> bootloader: **load** + bootloader -right-> memory: **execute** + +@enduml diff --git a/images/user/exe-debug-jtag.ditaa b/images/user/exe-debug-jtag.ditaa new file mode 100644 index 0000000..2ceedbc --- /dev/null +++ b/images/user/exe-debug-jtag.ditaa @@ -0,0 +1,33 @@ +' +' Executable debugging : JTAG +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startditaa + + +---------------------------------+ + | OpenOCD | + | | ++----------+ | +--------+ | +| | TCP | /---------------\ | | | +| GDB |<-------->| GDB server |<->| JTAG | | +| | | \---------------/ | | | ++----------+ | +--------+ | + ^ | ^ | + | +---------------------------|-----+ + /-----\ | USB + | ELF | V + \-----/ /-------\ + | POD | + \-------/ + ^ + | cable + V + +----------+ + | | + | Target | + | | + +----------+ + +@endditaa diff --git a/images/user/exe-debug-libdebugger.ditaa b/images/user/exe-debug-libdebugger.ditaa new file mode 100644 index 0000000..974365c --- /dev/null +++ b/images/user/exe-debug-libdebugger.ditaa @@ -0,0 +1,43 @@ +' +' Executable debugging : libdebugger +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startditaa + + +---------------------------------+ + | RTEMS Executable | + | | ++----------+ | /--------+ | +| | TCP | /---------------\ | | | +| GDB |<-------->| libbsd |<->| | | +| | | | networking | | | | ++----------+ | \---------------/ | | | + ^ | ^ | | | + | | | | | | + /-----\ | V | kernel | | + | ELF | | /---------------\ | | | + \-----/ | | libdebugger |<->| | | + | \---------------/ | | | + | ^ | | | + | | | | | + | +--------+ +--------/ | + | | ^ | + | : | | + | | +----------+ | + | | | | + +-|--------------|----------------+ + | | + +-----|--------------|------------------+ + | V V | + | /-------\ /-------\ +--------+ | + | | debug |<-=-->| cores |<->| | | + | | hw | \-------/ | memory | | + | \-------/ | | | + | +--------+ | + | | + | Target | + +---------------------------------------+ + +@endditaa diff --git a/images/user/exe-debug-qemu.ditaa b/images/user/exe-debug-qemu.ditaa new file mode 100644 index 0000000..168aae6 --- /dev/null +++ b/images/user/exe-debug-qemu.ditaa @@ -0,0 +1,23 @@ +' +' Executable debugging : QEMU +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startditaa + + +-----------------------------------+ + | QEMU | + | | ++----------+ | +----------+ | +| | TCP | /---------------\ | | | +| GDB |<-------->| GDB server |<->| Target | | +| | | \---------------/ | | | ++----------+ | +----------+ | + ^ | | + | +-----------------------------------+ + /-----\ + | ELF | + \-----/ + +@endditaa diff --git a/images/user/exe-debug.ditaa b/images/user/exe-debug.ditaa new file mode 100644 index 0000000..a38ba91 --- /dev/null +++ b/images/user/exe-debug.ditaa @@ -0,0 +1,20 @@ +' +' Executable debugging. +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startditaa + ++----------+ /---------------\ +----------+ +| | TCP | Debug Agent | agent | | +| GDB |<----->| (GDB server) |<---------->| Target | +| | \---------------/ connection | | ++----------+ +----------+ + ^ + | + /-----\ + | ELF | + \-----/ + +@endditaa diff --git a/images/user/exe-vert-stack.puml b/images/user/exe-vert-stack.puml new file mode 100644 index 0000000..720806b --- /dev/null +++ b/images/user/exe-vert-stack.puml @@ -0,0 +1,56 @@ +' +' Executable Application Vertical Stack +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startuml + + node Application [ + Application + ---- + Management + .... + Control + .... + Workers + .... + Protocol + ] + + note right of Application + High Level + end note + + node 3rdParty [ + 3rd Party Packages + ---- + Protobufs + .... + Networking (libbsd) + ] + + node RTEMS [ + RTEMS + ---- + API + .... + Kernel + .... + Drivers + .... + BSP + ] + node Hardware [ + Hardware + ] + + Application .down. 3rdParty + 3rdParty .down. RTEMS + RTEMS .down. Hardware + + note right of Hardware + Low Level + end note + +@enduml diff --git a/images/user/test-cfg-1.puml b/images/user/test-cfg-1.puml new file mode 100644 index 0000000..8264fd2 --- /dev/null +++ b/images/user/test-cfg-1.puml @@ -0,0 +1,20 @@ +' +' Tester Configuration 1. +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startuml + + artifact Defaults + artifact BSP + artifact User + artifact Config + rectangle "RTEMS Test\n(rtems-tester)" as tester + + Defaults -down-> tester: .mc + BSP -down-> tester: .ini + User -down-> tester: .ini + Config -down-> tester: .cfg + +@enduml diff --git a/images/user/test-cfg-2.puml b/images/user/test-cfg-2.puml new file mode 100644 index 0000000..fae4a77 --- /dev/null +++ b/images/user/test-cfg-2.puml @@ -0,0 +1,35 @@ +' +' Tester Configuration 2. +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startuml + + participant Run + database Defaults + database BSP + database User + database Config + + Run -> Defaults: load + activate Defaults + Defaults -> Run: loaded + deactivate Defaults + + Run -> BSP: load + activate BSP + BSP -> Run: BSP macro map loaded + deactivate BSP + + Run -> User: load + activate User + User -> Run: User config loaded + deactivate User + + Run -> Config: execute %{tester} script + activate Config + Config -> Run: finished + deactivate Config + +@enduml diff --git a/images/user/test-gdb-jtag.puml b/images/user/test-gdb-jtag.puml new file mode 100644 index 0000000..fbd1b47 --- /dev/null +++ b/images/user/test-gdb-jtag.puml @@ -0,0 +1,35 @@ +' +' Tester GDB +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startuml + + !define TESTER [rtems-test] + + artifact source + card EXE + agent TESTER + agent gdb + storage results + + agent openocd + agent ser2net + + card console + card pod + node target + + source --> EXE: build + EXE --> [rtems-test]: command line + TESTER --> gdb: GDB MI + gdb --> openocd: remote\nprotocol + TESTER <--> ser2net: telnet + openocd --> pod: USB + pod =down=> target: JTAG + console <=down=> target: UART + ser2net <--> console: USB + TESTER -> results + +@enduml diff --git a/images/user/test-simulation.puml b/images/user/test-simulation.puml new file mode 100644 index 0000000..7c6cfe4 --- /dev/null +++ b/images/user/test-simulation.puml @@ -0,0 +1,23 @@ +' +' Tester Simulation. +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startuml + + !define TESTER [rtems-test] + + artifact source + card EXE + agent TESTER + storage results + agent simulator + + source --> EXE: build + EXE --> [rtems-test]: command line + TESTER --> simulator + simulator --> TESTER: stdout + TESTER -> results + +@enduml diff --git a/images/user/test-tftp-seq-1.puml b/images/user/test-tftp-seq-1.puml new file mode 100644 index 0000000..e3397a6 --- /dev/null +++ b/images/user/test-tftp-seq-1.puml @@ -0,0 +1,35 @@ +' +' Tester TFTP Sequence 1: +' +' Pass and Fail +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startuml + + participant Start + participant Reset + participant UBoot + participant TFTP + participant Test + participant Finish + + note right of Start: target_on_command run before the first test + + Start --> UBoot: tester running, target has reset + activate UBoot + Start -->> Reset: target_on_command + activate Reset + Reset --> UBoot: target power on + deactivate Reset + UBoot --> TFTP: download + deactivate UBoot + activate TFTP + TFTP --> Test: execute + deactivate TFTP + activate Test + Test --> Finish: test pass or fail? + deactivate TFTP + +@enduml diff --git a/images/user/test-tftp-seq-2.puml b/images/user/test-tftp-seq-2.puml new file mode 100644 index 0000000..2d8dca9 --- /dev/null +++ b/images/user/test-tftp-seq-2.puml @@ -0,0 +1,39 @@ +' +' Tester TFTP Sequence 2: +' +' Start Filter Trigger +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startuml + + participant Start + participant Reset + participant UBoot + participant TFTP + participant Test + participant Finish + + note left of Finish: ""target_start_regex"" triggers on target async restart match + + Start --> UBoot : target already running + activate UBoot + UBoot -->> Reset : ""target_start_regex"" + activate Reset + Reset --> UBoot : target running + UBoot --> TFTP : download + activate TFTP + TFTP -->> Reset : ""target_start_regex"" + deactivate UBoot + TFTP --> Test : execute + deactivate TFTP + activate Test + Test --> Finish: test pass or fail? + Test -->> Reset : ""target_start_regex"" + deactivate TFTP + deactivate Test + Reset --> Finish : Invalid + deactivate Reset + +@enduml diff --git a/images/user/test-tftp-seq-3.puml b/images/user/test-tftp-seq-3.puml new file mode 100644 index 0000000..4777e66 --- /dev/null +++ b/images/user/test-tftp-seq-3.puml @@ -0,0 +1,33 @@ +' +' Tester TFTP Sequence 3: +' +' Reset Filter Trigger +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startuml + + participant Start + participant Reset + participant UBoot + participant TFTP + + note right of Start + ""target_reset_regex"" triggers on an async + target console match + end note + + Start --> UBoot : target already running + activate UBoot + Reset --> UBoot : target running + activate Reset + UBoot -->> Reset : ""target_reset_command"" + UBoot --> TFTP : download + deactivate UBoot + activate TFTP + TFTP -->> Reset : ""target_reset_command"" + deactivate TFTP + deactivate Reset + +@enduml diff --git a/images/user/test-tftp-seq-4.puml b/images/user/test-tftp-seq-4.puml new file mode 100644 index 0000000..669a0f5 --- /dev/null +++ b/images/user/test-tftp-seq-4.puml @@ -0,0 +1,26 @@ +' +' Tester TFTP Sequence 4: +' +' Reset Filter Trigger +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startuml + + participant UBoot + participant TFTP + participant Test + participant Reset + participant Finish + + note right of UBoot : A timeout can occur at any time + + UBoot -->> Reset : ""target_reset_command"" + activate Reset + TFTP -->> Reset : ""target_reset_command"" + Test -->> Reset : ""target_reset_command"" + Reset --> Finish : timeout + deactivate Reset + +@enduml diff --git a/images/user/test-tftp.puml b/images/user/test-tftp.puml new file mode 100644 index 0000000..9e2f234 --- /dev/null +++ b/images/user/test-tftp.puml @@ -0,0 +1,29 @@ +' +' Tester Hardware using TFTP network downloading. +' +' Copyright (c) 2018 Chris Johns +' All rights reserved. +' +@startuml + + !define TESTER [rtems-test] + + artifact source + card EXE + agent TESTER + storage results + + agent ser2net + + card console + node target + + source --> EXE: build + EXE --> [rtems-test]: command line + TESTER =down=> target: TFTP\nprotocol + TESTER <=down=> ser2net: telnet + console <=down=> target: UART + ser2net <==> console: USB + TESTER -> results + +@enduml diff --git a/user/exe/debugging.rst b/user/exe/debugging.rst new file mode 100644 index 0000000..3d1aa38 --- /dev/null +++ b/user/exe/debugging.rst @@ -0,0 +1,119 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2018 Chris Johns +.. comment: All rights reserved. + +Debugging +========= +.. index:: Debugging + +An RTEMS executable is debugged by loading the code, data and read-only data +into a target with a debugger connected. The debugger running on a host +computer accesses the ELF file reading the debug information it contains. + +The executable being debugged needs to be built with the compiler and linker +debug options enabled. Debug information makes the ELF executable file large +but it does not change the binary footprint of the executable when resident in +the target. Target boot loaders and file conversion tools extract the binary +code, data and read-only data to create the file embedded on the target. + +An ELF executable built with debug information contains DWARF debug +information. DWARF is a detailed description of the executable a debugger uses +to locate functions, find data, understand the type and structure of a +variable, and know how much entry code every call has. The debugger uses this +information to set breaks points, step functions, step instructions, view the +data and much more. + +We recommend the compiler and linker debug options are always enabled. An ELF +file with debug information can be used to investigate a crash report from a +production system if the production ELF image is archived. The RTEMS tools +chain provides tools that can take an address from a crash dump and find the +corresponding instruction and source line. The extra size the debug information +adds does not effect the target footprint and the extra size on a host is small +compared to the benefits it brings. + +A desktop or server operating system's kernel hosts the executable being +debugged handling the interaction with the executable and the debugger. The +debugger knows how to communicate to the kernel to get the information it +needs. Debugging an embedded executable needs an extra piece called an agent to +connect the target to the debugger. The agent provides a standard remote interface to +the debugger and an agent specific connection to the target. + +.. _fig-exe-debug: + +.. figure:: ../../images/user/exe-debug.png + :width: 80% + :alt: Embedded Executable Debugging + :figclass: align-center + + Embedded Executable Debugging + +The RTEMS tool chain provides the GNU debugger GDB. GDB has a remote protocol +that can run over networks using TCP and UDP protocols. The GDB remote protocol +is available in a number of open source and commercial debugging +solutions. Network debugging using the remote protocol helps setting up a +laboratory, the targets can be remote from the developers desktop allowing for +better control of the target hardware while avoiding the need to plug devices +in to an expensive desktop or server machine. + +The following are some examples of GDB and GDB server environments RTEMS +supports. + +.. index:: QEMU + +QEMU contains a debugging agent for the target being simulated. A QEMU command +line option enables a GDB server and the simulator manages the interaction with +the target processor and it's memory and caches. + +.. _fig-exe-debug-qemu: + +.. figure:: ../../images/user/exe-debug-qemu.png + :width: 70% + :alt: QEMU Executable Debugging + :figclass: align-center + + QEMU Executable Debugging + +.. index:: OpenOCD +.. index:: JTAG + +OpenOCD is a JTAG debugging package that interfaces to a wide of JTAG +pods. JTAG is a low level high speed serial interface modern processors provide +as a means of controlling the core processing logic. The features available depend on +the architecture and processor. Typical functions include: + +#. Processor control and register access + +#. System level register access to allow SOC initialization + +#. General address space access + +#. Cache and MMU control + +#. Break and watch points + +.. _fig-exe-debug-qemu: + +.. figure:: ../../images/user/exe-debug-jtag.png + :width: 70% + :alt: OpenOCD JTAG Executable Debugging + :figclass: align-center + + OpenOCD JTAG Executable Debugging + +.. index:: libdebugger + +The RTEMS kernel has a debugging agent called ``libdebugger``. This is a +software based agent that runs within RTEMS using network services to provide a +remote GDB protocol interface. A growing number of architectures are +supported. The RTEMS debugging agent is for application development providing +thread aware stop model debug experience. + +.. _fig-exe-debug-libdebugger: + +.. figure:: ../../images/user/exe-debug-libdebugger.png + :width: 70% + :alt: Libdebugger Executable Debugging + :figclass: align-center + + Libdebugger Executable Debugging 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. diff --git a/user/exe/execution.rst b/user/exe/execution.rst new file mode 100644 index 0000000..029bd24 --- /dev/null +++ b/user/exe/execution.rst @@ -0,0 +1,49 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2018 Chris Johns +.. comment: All rights reserved. + +Target Execution +================ +.. index:: Target Execution + +Fixed position statically linked executables have a fixed address in a target's +address space. The location in the address space for code, data and read-only +data is fixed. The BSP defines the memory map and it is set by the BSP +developer based on the target's hardware requirements and it's bootloader. + +Targets typically contains a bootloader that is executed after the target's +processor exits reset. A bootloader is specific to a target's processor and +hardware configuration and is responsible for the low level initialization of +the hardware resources needed to load and execute an operating system's +kernel. In the case of RTEMS this is the RTEMS executable. + +Bootloaders vary in size, complexity and functionality. Some architectures have +a number of bootloader stages and others have only minimal support. An example +of a high end system is Xilinx's Zynq processor with three stages. First a mask +ROM in the System On Chip (SOC) executes after reset loading a first stage +bootloader (FSBL) from an SD card, QSPI flash or NAND flash depending on +signals connected to the device. The FSBL loads a second stage bootloader +(SSBL) such as U-Boot and this loads the kernel. U-Boot can be configured to +load a kernel from a range of media and file system formats as well as over a +network using a number of protocols. This structure provides flexibility at the +system level to support development environments such as a workshop or +laboratory through to tightly control production configurations. + +Bootloaders often have custom formats for the executable image they load. The +formats can be simple to keep the bootloader simple or complex to support +check-sums, encryption or redundancy in case an image becomes corrupted. A +bootloader often provides a host tool that creates the required file from the +RTEMS executable's ELF file. + +If RTEMS is to run from RAM the bootloader reads the image and loads the code, +initialized data and read-only data into the RAM and then jumps to a known +entry point. If the code is executed from non-volatile storage the process to +write the image into that storage will have extracted the various binary parts +and written those to the correct location. + +The important point to note is the binary parts of the executable are somehow +loaded into the target's address space ready to execute. The way this done may +vary but the out come is always the same, the binary code, data and read-only +data is resident in the processor's address space at the BSP defined +addresses. diff --git a/user/exe/index.rst b/user/exe/index.rst new file mode 100644 index 0000000..c40b773 --- /dev/null +++ b/user/exe/index.rst @@ -0,0 +1,19 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2018 Chris Johns +.. comment: All rights reserved. + +Executables +*********** +.. index:: Executable +.. index:: Embedded executable + +This section discusses what an RTEMS executable is and what happens when you +execute it in a target. The section discusses how an application executable is +created, what happens when an executable is loaded and run as well as +debugging an execiutable. + +.. include:: executables.rst +.. include:: execution.rst +.. include:: initialization.rst +.. include:: debugging.rst diff --git a/user/exe/initialization.rst b/user/exe/initialization.rst new file mode 100644 index 0000000..9ecee16 --- /dev/null +++ b/user/exe/initialization.rst @@ -0,0 +1,130 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2018 Chris Johns +.. comment: All rights reserved. + +BSP Initialization +================== +.. index:: BSP Initialization + +The bootloader jumps or calls the RTEMS executable's entry point, normally a +fixed address. The BSP entry point or start up code performs: + +#. Low level processor specific initialization that such as setting control + registers so the processor is operating in a mode RTEMS is built for + +#. Cache flushing, clearing and invalidation + +#. Memory management unit (MMU) set up if required + +#. Clear the uninitialized data section + +#. Process a command line if supported by the bootloader + +#. Call ``bootcard`` which disabled interrupts, saves away a command line if + the BSP supports it then call the RTEMS kernel early initialize entry point + ``rtems_initialize_executive``. This call never returns. + +Further BSP initialization happens as part of RTEMS kernel's System +Initialization process. The following handlers are declared and if provided are +placed at the beginning of the initialization handler list. The BSP can +provides: + +``bsp_work_area_initialize`` + This function determines the amount of memory that can be given to RTEMS for + the workspace and the C library heap which ``malloc`` uses. The call + typically uses the ``bsp_work_area_initialize_default`` to perform actually + perform the initialization. + +``bsp_start`` + This function is specialized for each architecture and even for some BSPs. It + performs the low level initialization RTEMS needs so it can run on the + architecture and BSP. + +``bsp_predriver_hook`` + This function can be used to initialize hardware drivers depend on such as + configuring an interrupt controller. The default version is empty and does + nothing. + +BSPs all perform similar operations with common functionality and the RTEMS +kernel provides common code that can be shared between BSPs. The use of the +common code is encouraged for all new BSPs. + +RTEMS Initialization +==================== +.. index:: RTEMS Initialization + +The RTEMS kernel initialization is: + +#. Invoke the registered system initialization handlers + +#. Set the system state to **up** + +#. If the kernel supports SMP request multitasking start. All online cores are + transferred to the **ready to start multitasking** state. + +#. Start threaded multitasking. RTEMS starts multitasking by getting the first + thread to run and dispatching it. + +C++ static object constructors are called in the context of the first running +thread before the thread body is entered. + +System Initialization Handlers +------------------------------ + +RTEMS supports the automatic registration of services used in +applications. This method of initialization automatically configures RTEMS with +only the services used in an application. There is no manual configuration of +services used and no updating of initialization function tables. + +RTEMS uses specialized sections in the ELF executable to perform this task. The +system is based on the `FreeBSD SYSINT Framework +`_. Ordered +initialization is performed before multitasking is started. + +The RTEMS Tool ``rtems-exeinfo`` can provide some detail about the registered +handlers. The following shows the initialization handlers for the *hello world* +sample application in the RTEMS kernel's testsuite:: + + $ rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe + RTEMS Executable Info 5.5416cfa39dd6 + rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe + exe: arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe + + Compilation: + Producers: 2 + | GNU AS 2.31.1: 14 objects + | GNU C11 7.3.0 20180125 (RTEMS 5, RSB e55769c64cf1a201588565a5662deafe3f1ccdcc, Newlib 103b055035fea328f8bc7826801760fb1c055683): 284 objects + Common flags: 4 + | -march=armv7-a -mthumb -mfpu=neon -mfloat-abi=hard + + Init sections: 2 + .init_array + 0x001047c1 frame_dummy + .rtemsroset + 0x00104c05 bsp_work_area_initialize + 0x00104c41 bsp_start + 0x0010eb45 zynq_debug_console_init + 0x0010ec19 rtems_counter_sysinit + 0x0010b779 _User_extensions_Handler_initialization + 0x0010c66d rtems_initialize_data_structures + 0x00107751 _RTEMS_tasks_Manager_initialization + 0x0010d4f5 _POSIX_Keys_Manager_initialization + 0x0010dd09 _Thread_Create_idle + 0x0010cf01 rtems_libio_init + 0x001053a5 rtems_filesystem_initialize + 0x0010546d _Console_simple_Initialize + 0x0010c715 _IO_Initialize_all_drivers + 0x001076d5 _RTEMS_tasks_Initialize_user_tasks_body + 0x0010cfa9 rtems_libio_post_driver + +The section ``.rtemsroset`` lists the handlers called in order. The handlers +can be split into the BSP initialization handlers that start the BSP: + +- ``bsp_work_area_initialize`` +- ``bsp_start`` +- ``zynq_debug_console_init`` +- ``rtems_counter_sysinit`` + +And the remainder are handlers for services used by the application. The list +varies based on the services the application uses. diff --git a/user/index.rst b/user/index.rst index 48870a1..0f60166 100644 --- a/user/index.rst +++ b/user/index.rst @@ -51,10 +51,12 @@ to the Community Project hosted at http://www.rtems.org/. hardware/index bsps/index - tools/index - + exe/index + testing/index tracing/index + tools/index + support/index glossary/index diff --git a/user/test/create.rst b/user/test/create.rst deleted file mode 100644 index b86453a..0000000 --- a/user/test/create.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Creating A Test -=============== -.. index:: Creating a Test - -XXX: How to create a test. diff --git a/user/test/index.rst b/user/test/index.rst deleted file mode 100644 index 7ae43fe..0000000 --- a/user/test/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Test Suite -********** - -XXX: All about the test suite. - - -.. include:: running.rst -.. include:: create.rst diff --git a/user/test/running.rst b/user/test/running.rst deleted file mode 100644 index 5184ae1..0000000 --- a/user/test/running.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Running -======== -.. index:: Running a Test - -XXX: How to run tests via waf. - - -Host ----- - -XXX: Host-based tests - - -Simulation ----------- -.. index:: Test Simulation - -XXX: Simulator - - - -Hardware --------- -XXX: Running on real hardware. diff --git a/user/testing/configuration.rst b/user/testing/configuration.rst new file mode 100644 index 0000000..a58b373 --- /dev/null +++ b/user/testing/configuration.rst @@ -0,0 +1,312 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2018 Chris Johns +.. comment: All rights reserved. + +Tester Configuration +-------------------- + +The RTEMS Tester and RTEMS Run are controlled by configuration data and +scripts. The user specifies a BSP on the command line using the ``--rtems-bsp`` +option as well as optionally specifying a user configuration file using +``--user-config``. + +The Figure :ref:`fig-tester-config-1` shows the various sources of +configuration data and their format. The ``ini`` files are the standard INI +format, the ``mc`` are the internal RTEMS Toolkit's Macro format, and ``cfg`` +is the RTEMS Toolkit's Configuration script format, the same format used by the +RTEMS Source Builder. + +.. _fig-tester-config-1: + +.. figure:: ../../images/user/test-cfg-1.png + :width: 50% + :alt: RTEMS Tester and Run Configuration Files + :figclass: align-center + + RTEMS Tester and Run Configuration Files + +Configuration data is held in a macro database keyed on the macro name. Macros +can be expanded in configuration scripts using the syntax ``%{name}``. The +macro database is layered using maps. The defaults and values created when a +configure script runs live the in the ``global`` map. Values read from the BSP +and User INI configuration files are loaded into maps based on the BSP +name. This lets a single User configuration file contain specialized +configuration values for a number of BSPs and the tester and run commands +select the values based on the selected BSP. Macros are expanded using the BSP +map first giving those values the highest priority. User defined values are +loaded after the BSP configuration values overwriting them letting a user +speckles a BSP's default configuration for their local needs. + +Figure :ref:`fig-tester-config-2` shows the configuration loading and script +execution order. + +.. _fig-tester-config-2: + +.. figure:: ../../images/user/test-cfg-2.png + :width: 50% + :alt: RTEMS Tester and Run Configuration Load and Execute Sequence + :figclass: align-center + + RTEMS Tester and Run Configuration Load and Execute Sequence + +Defaults +^^^^^^^^ + +The RTEMS Tester and RTEMS Run are primed using defaults from the file +``rtems/testing/testing.mc``. All default settings can be overridden in a BSP or +User configuration file. + +.. index:: BSP configuration, User configuration +BSP and User Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The BSP and User configuration files are INI format files. The BSP +configuration file has to have an INI section that is the name of the BSP +passed on the command line. The section has the following mandatory values: + +.. index:: bsp +``bsp`` + The name of the BSP. The BSP name is used to create a macro map to hold the + BSP's configuration data. Typically this is the same as the BSP name used on + the command line. + +.. index:: arch +``arch`` + The name of the BSP architecture. This is need for the GDB configuration + scripts where the architecture specific GDB needs to run. It is mandatory so + the *arch/bsp* standard RTEMS BSP string can be used. + +.. index:: tester +``tester`` + The tester or run configuration script. This is the name of the configuration + script the RTEMS Tester or RTEMS Run executes as a back end. The ``tester`` + value is typically of the form ``%{_rtscripts}/