RTEMS User Manual (5.2-rc1).

Copyrights and License

© 2020 Niteesh Babu

© 2020 Utkarsh Rai

© 2019 Vijay Kumar Banerjee

© 2018 Amaan Cheval

© 2018 Marçal Comajoan Cara

© 2018 Shashvat Jain

© 2018 Vidushi Vashishth

© 2017 Tanu Hari Dixit

© 2016, 2019 embedded brains GmbH

© 2016, 2019 Sebastian Huber

© 2012, 2020 Chris Johns

© 2012, 2020 Gedare Bloom

© 1988, 2018 On-Line Applications Research Corporation (OAR)

This document is available under the Creative Commons Attribution-ShareAlike 4.0 International Public License.

The authors have used their best efforts in preparing this material. These efforts include the development, research, and testing of the theories and programs to determine their effectiveness. No warranty of any kind, expressed or implied, with regard to the software or the material contained in this document is provided. No liability arising out of the application or use of any product described in this document is assumed. The authors reserve the right to revise this material and to make changes from time to time in the content hereof without obligation to notify anyone of such revision or changes.

The RTEMS Project is hosted at https://www.rtems.org. Any inquiries concerning RTEMS, its related support components, or its documentation should be directed to the RTEMS Project community.

RTEMS Online Resources

Home	https://www.rtems.org
Documentation	https://docs.rtems.org
Mailing Lists	https://lists.rtems.org
Bug Reporting	https://devel.rtems.org/wiki/Developer/Bug_Reporting
Git Repositories	https://git.rtems.org
Developers	https://devel.rtems.org

• 1. Introduction
  • 1.1. Overview
  • 1.2. Features
  • 1.3. Ecosystem
    • 1.3.1. Rational
    • 1.3.2. Open Source
    • 1.3.3. Deployment
  • 1.4. Real-time Application Systems
  • 1.5. Real-time Executive
• 2. Quick Start
  • 2.1. Preparation
    • 2.1.1. Host Computer
    • 2.1.2. Selecting a BSP
    • 2.1.3. Selecting a Version of RTEMS
  • 2.2. Choose an Installation Prefix
  • 2.3. Obtain the Sources
    • 2.3.1. Releases
    • 2.3.2. Git
    • 2.3.3. Offline Download
  • 2.4. Install the Tool Suite
    • 2.4.1. Need for RTEMS-Specific Cross-Compiler
  • 2.5. Bootstrap the RTEMS Sources
  • 2.6. Build a Board Support Package (BSP)
    • 2.6.1. RSB BSP Build
    • 2.6.2. Manual BSP Build
  • 2.7. Test a Board Support Package (BSP)
  • 2.8. Build Your Application
  • 2.9. Build an RSB Package
    • 2.9.1. RTEMS Packages
    • 2.9.2. BSP Stack Build
    • 2.9.3. Package Build
  • 2.10. GSoC Getting Started
    • 2.10.1. Installing Dependencies
    • 2.10.2. Choosing an installation prefix
    • 2.10.3. Downloading the Sources
    • 2.10.4. Installing the Tool Suite
    • 2.10.5. Building the Board Support Package
    • 2.10.6. Testing the Board Support Package
    • 2.10.7. Prove You Can Work On RTEMS
    • 2.10.8. Creating and Sending Patches
• 3. Support and Contributing
  • 3.1. RTEMS Project Support
    • 3.1.1. Users Mailing List
    • 3.1.2. Documentation
    • 3.1.3. All Mailing Lists
    • 3.1.4. IRC
  • 3.2. Report Bugs
    • 3.2.1. Search for Existing Bugs
    • 3.2.2. Not RTEMS Bugs
    • 3.2.3. Good Bug Reports
    • 3.2.4. Nobody Fixes my Bug
  • 3.3. Contributing
    • 3.3.1. How to Contribute?
    • 3.3.2. Preparing and Sending Patches
    • 3.3.3. Checklist for Patches
    • 3.3.4. Patch Review Process
    • 3.3.5. Why Contribute?
    • 3.3.6. Common Questions and Answers
  • 3.4. Commercial Support Services
• 4. Host Computer
  • 4.1. Host Operating Systems
  • 4.2. POSIX Hosts
    • 4.2.1. Root Access
    • 4.2.2. Linux
      • 4.2.2.1. ArchLinux
      • 4.2.2.2. CentOS
      • 4.2.2.3. Fedora
      • 4.2.2.4. Raspbian
      • 4.2.2.5. Ubuntu
      • 4.2.2.6. Linux Mint
      • 4.2.2.7. openSUSE
    • 4.2.3. FreeBSD
    • 4.2.4. NetBSD
  • 4.3. Apple macOS
    • 4.3.1. Catalina
    • 4.3.2. Sierra
    • 4.3.3. Mavericks
  • 4.4. Microsoft Windows
    • 4.4.1. Windows Path Length
    • 4.4.2. Windows Spaces In Paths
    • 4.4.3. Parallel Builds with Make
    • 4.4.4. POSIX Support
    • 4.4.5. Python
    • 4.4.6. MSYS2
    • 4.4.7. Cygwin
• 5. Installation
  • 5.1. Releases
    • 5.1.1. RTEMS Tools and Kernel
  • 5.2. Developer (Unstable)
    • 5.2.1. POSIX and OS X Host Tools Chain
    • 5.2.2. Windows Host Tool Chain
      • 5.2.2.1. RTEMS Windows Tools
      • 5.2.2.2. Building the Kernel
  • 5.3. RTEMS Kernel
    • 5.3.1. Development Sources
    • 5.3.2. Tools Path Set Up
    • 5.3.3. Bootstrapping
    • 5.3.4. Building a BSP
    • 5.3.5. Installing A BSP
    • 5.3.6. Contributing Patches
  • 5.4. Project Sandboxing
• 6. Target Hardware
  • 6.1. Targets
  • 6.2. Architectures
  • 6.3. Tiers
• 7. Board Support Packages
  • 7.1. aarch64 (AArch64)
  • 7.2. arm (ARM)
    • 7.2.1. altera-cyclone-v (Intel Cyclone V)
      • 7.2.1.1. Boot via U-Boot
      • 7.2.1.2. Clock Driver
      • 7.2.1.3. Console Driver
      • 7.2.1.4. I2C Driver
      • 7.2.1.5. Network Interface Driver
      • 7.2.1.6. MMC/SDCard Driver
      • 7.2.1.7. USB Host Driver
      • 7.2.1.8. Caveats
    • 7.2.2. atsam
    • 7.2.3. beagle
      • 7.2.3.1. Boot via U-Boot
      • 7.2.3.2. Getting the Device Tree Blob
      • 7.2.3.3. Writing the uEnv.txt file
      • 7.2.3.4. I2C Driver
      • 7.2.3.5. SPI Driver
    • 7.2.4. csb336
    • 7.2.5. edb7312
    • 7.2.6. gumstix
    • 7.2.7. imx (NXP i.MX)
      • 7.2.7.1. Build Configuration Options
      • 7.2.7.2. Clock settings for different boards
      • 7.2.7.3. Boot via U-Boot
      • 7.2.7.4. Boot via barebox
      • 7.2.7.5. Clock Driver
      • 7.2.7.6. Console Driver
      • 7.2.7.7. I2C Driver
      • 7.2.7.8. SPI Driver
      • 7.2.7.9. Network Interface Driver
      • 7.2.7.10. MMC/SDCard Driver
      • 7.2.7.11. Caveats
    • 7.2.8. lm3s69xx
    • 7.2.9. lpc176x
    • 7.2.10. imx (NXP i.MX)
      • 7.2.10.1. Build Configuration Options
      • 7.2.10.2. Clock settings for different boards
      • 7.2.10.3. Boot via U-Boot
      • 7.2.10.4. Boot via barebox
      • 7.2.10.5. Clock Driver
      • 7.2.10.6. Console Driver
      • 7.2.10.7. I2C Driver
      • 7.2.10.8. SPI Driver
      • 7.2.10.9. Network Interface Driver
      • 7.2.10.10. MMC/SDCard Driver
      • 7.2.10.11. Caveats
    • 7.2.11. raspberrypi
      • 7.2.11.1. Setup SD card
      • 7.2.11.2. Kernel image
      • 7.2.11.3. Testing using QEMU
    • 7.2.12. realview-pbx-a9
    • 7.2.13. rtl22xx
    • 7.2.14. smdk2410
    • 7.2.15. tms570
    • 7.2.16. xen (Xen on ARM)
      • 7.2.16.1. Execution
      • 7.2.16.2. Additional Information
    • 7.2.17. xilinx-zynq
    • 7.2.18. xilinx-zynqmp
  • 7.3. bfin (Blackfin)
    • 7.3.1. bf537Stamp
    • 7.3.2. eZKit533
    • 7.3.3. TLL6527M
  • 7.4. epiphany (Epiphany)
    • 7.4.1. epiphany_sim
  • 7.5. i386
    • 7.5.1. pc386
  • 7.6. lm32 (LatticeMicro32)
    • 7.6.1. lm32_evr
    • 7.6.2. milkymist
  • 7.7. m68k (Motorola 68000 / ColdFire)
    • 7.7.1. av5282
    • 7.7.2. csb360
    • 7.7.3. gen68340
    • 7.7.4. gen68360
    • 7.7.5. genmcf548x
    • 7.7.6. mcf5206elite
    • 7.7.7. mcf52235
    • 7.7.8. mcf5225x
    • 7.7.9. mcf5235
    • 7.7.10. mcf5329
      • 7.7.10.1. Overview
    • 7.7.11. mrm332
    • 7.7.12. mvme147
    • 7.7.13. mvme147s
    • 7.7.14. mvme162
      • 7.7.14.1. Overview
      • 7.7.14.2. Board Setup
      • 7.7.14.3. Downloading and Executing
    • 7.7.15. mvme167
    • 7.7.16. uC5282
  • 7.8. microblaze (Microblaze)
  • 7.9. mips (MIPS)
    • 7.9.1. csb350
    • 7.9.2. hurricane
    • 7.9.3. jmr3904
    • 7.9.4. malta
    • 7.9.5. rbtx4925
    • 7.9.6. rbtx4938
  • 7.10. moxie
    • 7.10.1. moxiesim
  • 7.11. nios2 (Nios II)
    • 7.11.1. nios2_iss
  • 7.12. or1k (OpenRISC 1000)
    • 7.12.1. generic_or1k
  • 7.13. powerpc (PowerPC)
    • 7.13.1. beatnik
    • 7.13.2. gen5200
    • 7.13.3. gen83xx
    • 7.13.4. haleakala
    • 7.13.5. motorola_powerpc
      • 7.13.5.1. Boot Image Generation
    • 7.13.6. mpc55xxevb
    • 7.13.7. mpc8260ads
    • 7.13.8. mvme3100
    • 7.13.9. mvme5500
    • 7.13.10. psim
    • 7.13.11. qemuppc
    • 7.13.12. qoriq (QorIQ)
      • 7.13.12.1. Boot via U-Boot
      • 7.13.12.2. Clock Driver
      • 7.13.12.3. Console Driver
      • 7.13.12.4. Network Interface Driver
      • 7.13.12.5. Topaz Hypervisor Guest
    • 7.13.13. ss555
    • 7.13.14. t32mppc
    • 7.13.15. tqm8xx
    • 7.13.16. virtex
    • 7.13.17. virtex4
    • 7.13.18. virtex5
  • 7.14. riscv (RISC-V)
    • 7.14.1. riscv
      • 7.14.1.1. Build Configuration Options
      • 7.14.1.2. Interrupt Controller
      • 7.14.1.3. Clock Driver
      • 7.14.1.4. Console Driver
    • 7.14.2. griscv
  • 7.15. sh (SuperH)
    • 7.15.1. gensh1
    • 7.15.2. gensh2
    • 7.15.3. gensh4
    • 7.15.4. shsim
  • 7.16. sparc64 (SPARC V9)
    • 7.16.1. niagara
    • 7.16.2. usiii
  • 7.17. sparc (SPARC / LEON)
    • 7.17.1. erc32
    • 7.17.2. leon2
    • 7.17.3. leon3
  • 7.18. v850 (V850)
    • 7.18.1. gdbv850sim
  • 7.19. x86_64
    • 7.19.1. amd64
      • 7.19.1.1. Build Configuration Options
      • 7.19.1.2. Testing with QEMU
        • 7.19.1.2.1. Building TianoCore’s UEFI firmware, OVMF
      • 7.19.1.3. Boot RTEMS via FreeBSD’s bootloader
      • 7.19.1.4. Paging
      • 7.19.1.5. Interrupt Setup
      • 7.19.1.6. Clock Driver
      • 7.19.1.7. Console Driver
• 8. Executables
  • 8.1. RTEMS Executable
  • 8.2. Building an Application
    • 8.2.1. Machine Flags and ABI
  • 8.3. Target Execution
  • 8.4. BSP Initialization
  • 8.5. RTEMS Initialization
    • 8.5.1. System Initialization Handlers
  • 8.6. Debugging
  • 8.7. Dynamic Loader
    • 8.7.1. System Design
    • 8.7.2. Loader Interface
    • 8.7.3. Symbols
      • 8.7.3.1. Base Image Symbols
      • 8.7.3.2. Embedded Symbols
      • 8.7.3.3. Loadable Symbols
    • 8.7.4. Unresolved Symbols
    • 8.7.5. Libraries
    • 8.7.6. Large Memory
    • 8.7.7. Allocator
    • 8.7.8. Languages
    • 8.7.9. Thread Local Storage
    • 8.7.10. Architectures
      • 8.7.10.1. ARM
      • 8.7.10.2. PowerPC
  • 8.8. Device Tree
    • 8.8.1. Building the DTB
    • 8.8.2. Using Device Tree Overlay
• 9. Testing
  • 9.1. Test Banners
  • 9.2. Test Controls
    • 9.2.1. Expected Test States
    • 9.2.2. Test Configuration
  • 9.3. Test Builds
  • 9.4. Tester Configuration
    • 9.4.1. Defaults
    • 9.4.2. BSP and User Configuration
    • 9.4.3. Configuration Scripts
      • 9.4.3.1. Console
      • 9.4.3.2. Execute
      • 9.4.3.3. GDB
      • 9.4.3.4. TFTP
  • 9.5. Coverage Analysis
  • 9.6. Consoles
  • 9.7. Simulation
  • 9.8. GDB and JTAG
  • 9.9. TFTP and U-Boot
    • 9.9.1. Target Hardware
      • 9.9.1.1. U-Boot Set Up
    • 9.9.2. BSP Configuration
    • 9.9.3. TFTP Sequences
• 10. Tracing
  • 10.1. Introduction to Tracing
    • 10.1.1. RTEMS Trace Using Trace Buffering
    • 10.1.2. RTEMS Trace Using Printk
  • 10.2. Tracing Examples
    • 10.2.1. Features
    • 10.2.2. Prerequisites
    • 10.2.3. Demonstration
  • 10.3. Capture Engine
    • 10.3.1. Capture Engine Commands
    • 10.3.2. Example
  • 10.4. Trace Linker
    • 10.4.1. Command Line
    • 10.4.2. Configuration (INI) files
      • 10.4.2.1. Tracer Section
      • 10.4.2.2. Options section
      • 10.4.2.3. Trace Section
      • 10.4.2.4. Function Section
      • 10.4.2.5. Generators
    • 10.4.3. Development
  • 10.5. Event Recording
    • 10.5.1. Target System: Configuration and Event Generation
    • 10.5.2. Transfer of Event Records to the Host Computer
    • 10.5.3. Analysis of Event Records on the Host Computer
• 11. Changing Versions
  • 11.1. RTEMS 4.11 to RTEMS 5
    • 11.1.1. Application Configuration Options
    • 11.1.2. Clock Manager
    • 11.1.3. File Descriptors
    • 11.1.4. Networking
    • 11.1.5. Shell Environment
• 12. Host Tools
  • 12.1. RTEMS Linker
  • 12.2. RTEMS Symbols
    • 12.2.1. Symbol Table
    • 12.2.2. 2-Pass Linking
    • 12.2.3. Command
    • 12.2.4. Examples
  • 12.3. RTEMS Executable Infomation
    • 12.3.1. System Initialisation
    • 12.3.2. Command
    • 12.3.3. Examples
  • 12.4. RTEMS BSP Builder
    • 12.4.1. Developer Workflows
    • 12.4.2. Build Characteristics
      • 12.4.2.1. Profiles
      • 12.4.2.2. Builds
        • 12.4.2.2.1. All Build
    • 12.4.3. Build Configurations
    • 12.4.4. Performance
    • 12.4.5. Command
      • 12.4.5.1. Examples
  • 12.5. RTEMS Tester and Run
    • 12.5.1. Available BSP testers
    • 12.5.2. Building RTEMS Tests
    • 12.5.3. Running the Tests
    • 12.5.4. Test Status
      • 12.5.4.1. Pass
      • 12.5.4.2. Fail
      • 12.5.4.3. User-input
      • 12.5.4.4. Expected-fail
      • 12.5.4.5. Indeterminate
      • 12.5.4.6. Benchmark
      • 12.5.4.7. Timeout
      • 12.5.4.8. Invalid
    • 12.5.5. Logging
      • 12.5.5.1. All
      • 12.5.5.2. Failures
      • 12.5.5.3. None
    • 12.5.6. Reporting
    • 12.5.7. Running Tests in Parallel
    • 12.5.8. Command Line Help
  • 12.6. RTEMS Boot Image
    • 12.6.1. Boot Loaders
      • 12.6.1.1. U-Boot
    • 12.6.2. Hosts
      • 12.6.2.1. FreeBSD
      • 12.6.2.2. Linux
      • 12.6.2.3. MacOS
    • 12.6.3. Configuration
    • 12.6.4. Command
    • 12.6.5. Examples
  • 12.7. RTEMS TFTP Proxy
    • 12.7.1. Operation
    • 12.7.2. Configuration
    • 12.7.3. Command
    • 12.7.4. Examples
• 13. Source Builder
  • 13.1. Why Build from Source?
  • 13.2. Project Sets
    • 13.2.1. Bare Metal
    • 13.2.2. RTEMS
    • 13.2.3. Patches
      • 13.2.3.1. Testing a Newlib Patch
  • 13.3. Cross and Canadian Cross Building
    • 13.3.1. Cross Building
    • 13.3.2. Canadian Cross Building
  • 13.4. Third-Party Packages
    • 13.4.1. Vertical Integration
    • 13.4.2. Building
    • 13.4.3. Adding
    • 13.4.4. Host and Build Flags
    • 13.4.5. BSP Support
    • 13.4.6. BSP Configuration
  • 13.5. Configuration
    • 13.5.1. Source and Patches
      • 13.5.1.1. HTTP, HTTPS, and FTP
      • 13.5.1.2. GIT
    • 13.5.2. Macros and Defaults
      • 13.5.2.1. Macro Maps and Files
      • 13.5.2.2. Personal Macros
    • 13.5.3. Configuration Reports
      • 13.5.3.1. Report Mailing
    • 13.5.4. Build Set Files
    • 13.5.5. Configuration Control
    • 13.5.6. Personal Configurations
    • 13.5.7. New Configurations
      • 13.5.7.1. Layering by Including
      • 13.5.7.2. Configuration File Numbering
      • 13.5.7.3. Common Configuration Scripts
      • 13.5.7.4. DTC Example
      • 13.5.7.5. Debugging
    • 13.5.8. Scripting
      • 13.5.8.1. Expanding
      • 13.5.8.2. %prep
      • 13.5.8.3. %build
      • 13.5.8.4. %install
      • 13.5.8.5. %clean
      • 13.5.8.6. %include
      • 13.5.8.7. %name
      • 13.5.8.8. %summary
      • 13.5.8.9. %release
      • 13.5.8.10. %version
      • 13.5.8.11. %buildarch
      • 13.5.8.12. %source
      • 13.5.8.13. %patch
      • 13.5.8.14. %hash
      • 13.5.8.15. %echo
      • 13.5.8.16. %warning
      • 13.5.8.17. %error
      • 13.5.8.18. %select
      • 13.5.8.19. %define
      • 13.5.8.20. %undefine
      • 13.5.8.21. %if
      • 13.5.8.22. %ifn
      • 13.5.8.23. %ifarch
      • 13.5.8.24. %ifnarch
      • 13.5.8.25. %ifos
      • 13.5.8.26. %else
      • 13.5.8.27. %endfi
      • 13.5.8.28. %bconf_with
      • 13.5.8.29. %bconf_without
  • 13.6. Commands
    • 13.6.1. Checker (sb-check)
    • 13.6.2. Defaults (sb-defaults)
    • 13.6.3. Set Builder (sb-set-builder)
    • 13.6.4. Set Builder (sb-builder)
  • 13.7. Building and Deploying Tool Binaries
  • 13.8. Bugs, Crashes, and Build Failures
    • 13.8.1. Contributing
  • 13.9. History
• 14. Glossary