RTEMS Documentation Project
RTEMS User Manual
6.a3cfaea
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. Build a Board Support Package (BSP)
2.5.1. RSB BSP Build
2.5.2. Manual BSP Build
2.6. Test a Board Support Package (BSP)
2.7. Build Your Application
2.8. Build an RSB Package
2.8.1. RTEMS Packages
2.8.2. BSP Stack Build
2.8.3. Package Build
2.9. GSoC Getting Started
2.9.1. Installing Dependencies
2.9.2. Choosing an installation prefix
2.9.3. Downloading the Sources
2.9.4. Installing the Tool Suite
2.9.5. Building the Board Support Package
2.9.6. Testing the Board Support Package
2.9.7. Prove You Can Work On RTEMS
2.9.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. Discord
3.2. Report Bugs
3.2.1. Search for Existing Bugs
3.2.2. Not RTEMS Bugs
3.2.3. Creating Good Bug Reports
3.2.4. Nobody Fixes my Bug
3.3. Contributing
3.3.1. How to Contribute?
3.3.2. Preparing and Submitting Merge Requests
3.3.3. Checklist for Merge Requests
3.3.4. Review Process
3.3.5. Updating a Merge Request
3.3.6. Rebasing a Merge Request
3.3.7. Approvers
3.3.8. Why Contribute?
3.3.9. Common Questions and Answers
3.4. Commercial Support Services
4. Host Computer
4.1. Python
4.1.1. Virtual Environment
4.1.2. Symbolic Link
4.1.3. Directly Invoking Python
4.2. Host Operating Systems
4.3. POSIX Hosts
4.3.1. Root Access
4.3.2. Linux
4.3.2.1. ArchLinux
4.3.2.2. CentOS
4.3.2.3. Fedora
4.3.2.4. Raspbian
4.3.2.5. Ubuntu
4.3.2.6. Linux Mint
4.3.2.7. openSUSE
4.3.3. FreeBSD
4.3.4. NetBSD
4.4. Apple macOS
4.4.1. Python
4.4.2. Sonoma
4.4.3. Ventura
4.4.4. Monterey
4.4.5. Catalina
4.4.6. Sierra
4.4.7. Mavericks
4.5. Microsoft Windows
4.5.1. Windows Path Length
4.5.2. Windows Spaces In Paths
4.5.3. Parallel Builds with Make
4.5.4. POSIX Support
4.5.5. Python
4.5.6. MSYS2
4.5.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. Building a BSP
5.3.3. Installing A BSP
5.3.4. Contributing Patches
5.4. Project Sandboxing
6. Deployment
6.1. RSB Deployment
6.1.1. Deployment Repository
6.1.2. Tools Configuration
6.1.3. Tools and Kernel
6.1.4. Tools and Kernel with Config
6.1.5. Tools, Kernel and Packages
6.1.6. Tools, Kernel with Config and Packages
7. Target Hardware
7.1. Targets
7.2. Architectures
7.3. Tiers
8. BSP Build System
8.1. Overview
8.2. Work Flow
8.3. Commands
8.3.1. Help
8.3.2. BSP List
8.3.3. BSP Defaults
8.3.4. Configure
8.3.5. Build, Clean, and Install
8.4. Configuration
8.5. Migration from Autoconf/Automake
9. Board Support Packages
9.1. aarch64 (AArch64)
9.1.1. Qemu A53
9.1.1.1. Boot via ELF
9.1.1.2. Clock Driver
9.1.1.3. Console Driver
9.1.1.4. Running Executables
9.1.2. Qemu A72
9.1.2.1. Boot via ELF
9.1.2.2. Clock Driver
9.1.2.3. Console Driver
9.1.2.4. Running Executables
9.1.3. Qemu Xilinx Versal
9.1.3.1. Boot via ELF
9.1.3.2. Clock Driver
9.1.3.3. Console Driver
9.1.3.4. Running Executables
9.1.4. Xilinx ZynqMP
9.1.4.1. Boot on QEMU
9.1.4.2. Boot on ZynqMP Hardware
9.1.4.3. Hardware Boot Image Generation
9.1.4.4. Example: Booting a RTEMS image on the ZCU102 ZynqMP board
9.1.4.5. Clock Driver
9.1.4.6. Console Driver
9.1.4.7. SDHCI Driver
9.1.4.8. Network Configuration
9.1.4.9. Running Executables on QEMU
9.1.5. Raspberry Pi 4B
9.1.5.1. Clock Driver
9.1.5.2. Console Driver
9.1.5.3. GPIO Driver
9.1.5.4. Preparing to boot
9.1.5.5. JTAG Setup
9.2. arm (ARM)
9.2.1. altera-cyclone-v (Intel Cyclone V)
9.2.1.1. Boot via U-Boot
9.2.1.2. Clock Driver
9.2.1.3. Console Driver
9.2.1.4. I2C Driver
9.2.1.5. Network Interface Driver
9.2.1.6. MMC/SDCard Driver
9.2.1.7. USB Host Driver
9.2.1.8. Caveats
9.2.2. atsam
9.2.3. beagle
9.2.3.1. Boot via U-Boot
9.2.3.2. Drivers
9.2.3.3. Debugging using libdebugger
9.2.3.4. Debugging Beagle Bone Black using a JTAG debugger and gdb
9.2.3.5. Debugging using a JTAG debugger and gdb without any bootcode
9.2.3.6. Testing
9.2.4. csb336
9.2.5. csb337
9.2.6. edb7312
9.2.7. fvp (Fixed Virtual Platform)
9.2.7.1. Run an Executable
9.2.7.2. Clock Driver
9.2.7.3. Console Driver
9.2.8. gumstix
9.2.9. imx (NXP i.MX)
9.2.9.1. Build Configuration Options
9.2.9.2. Clock settings for different boards
9.2.9.3. Boot via U-Boot
9.2.9.4. Boot via barebox
9.2.9.5. Clock Driver
9.2.9.6. Console Driver
9.2.9.7. I2C Driver
9.2.9.8. SPI Driver
9.2.9.9. Network Interface Driver
9.2.9.10. MMC/SDCard Driver
9.2.9.11. Caveats
9.2.10. imxrt (NXP i.MXRT)
9.2.10.1. Build Configuration Options
9.2.10.2. Adapting to a different board
9.2.10.3. Boot Process of IMXRT1050-EVKB
9.2.10.4. Flash Image
9.2.10.5. FDT
9.2.10.6. Clock Driver
9.2.10.7. IOMUX
9.2.10.8. Console Driver
9.2.10.9. I2C Driver
9.2.10.10. SPI Driver
9.2.10.11. Network Interface Driver
9.2.10.12. NXP SDK files
9.2.10.13. Clocks and SDRAM
9.2.10.14. Caveats
9.2.11. lm3s69xx
9.2.12. lpc176x
9.2.13. lpc24xx (NXP LPC17XX/LPC24XX/LPC40XX)
9.2.13.1. Clock Driver
9.2.13.2. Console Driver
9.2.13.3. I2C Bus Driver
9.2.13.4. SPI Bus Driver
9.2.13.5. Network Interface Driver
9.2.13.6. USB Driver
9.2.13.7. Framebuffer Driver
9.2.13.8. RTC Driver
9.2.14. raspberrypi
9.2.14.1. Setup SD card
9.2.14.2. Kernel image
9.2.14.3. SPI Driver
9.2.14.4. I2C Driver
9.2.14.5. Testing using QEMU
9.2.15. realview-pbx-a9
9.2.16. rtl22xx
9.2.17. smdk2410
9.2.18. stm32f4
9.2.19. stm32h7
9.2.19.1. Clock Driver
9.2.19.2. Console Driver
9.2.19.3. Network Interface Driver
9.2.19.4. USB Host Driver
9.2.19.5. SD/MMC Driver
9.2.19.6. How to run RTEMS on the board
9.2.20. tms570
9.2.21. xen (Xen on ARM)
9.2.21.1. Execution
9.2.21.2. Additional Information
9.2.22. xilinx-zynq
9.2.22.1. Bootloader
9.2.22.2. Clocks
9.2.22.3. Console
9.2.22.4. Network
9.2.22.5. Debugging with xilinx_zynq_a9_qemu
9.2.23. xilinx-zynqmp
9.2.24. Xilinx ZynqMP RPU
9.2.24.1. Clock Driver
9.2.24.2. Console Driver
9.2.24.3. Boot on ZynqMP Hardware
9.2.24.4. Hardware Boot Image Generation
9.2.24.5. Boot on QEMU
9.2.24.6. Running Executables on QEMU
9.2.24.7. Debugging Executables on QEMU
9.3. bfin (Blackfin)
9.3.1. bf537Stamp
9.3.2. eZKit533
9.3.3. TLL6527M
9.4. i386
9.4.1. pc386
9.4.1.1. Build Configuration Options
9.4.1.2. Runtime Options
9.4.1.3. Testing with Qemu
9.4.1.4. Running on a PC hardware
9.4.1.5. Clock Drivers
9.4.1.6. Console Drivers
9.4.1.7. Frame-Buffer Drivers
9.4.1.8. Network Interface Drivers
9.4.1.9. USB Host Drivers
9.4.1.10. RTC Drivers
9.4.1.11. I2C Drivers
9.4.1.12. SPI Drivers
9.4.1.13. Legacy Drivers
9.5. lm32 (LatticeMicro32)
9.5.1. lm32_evr
9.5.2. milkymist
9.6. m68k (Motorola 68000 / ColdFire)
9.6.1. av5282
9.6.2. csb360
9.6.3. gen68340
9.6.4. gen68360
9.6.5. genmcf548x
9.6.6. mcf5206elite
9.6.7. mcf52235
9.6.8. mcf5225x
9.6.9. mcf5235
9.6.10. mcf5329
9.6.10.1. Overview
9.6.11. mrm332
9.6.12. mvme147
9.6.13. mvme147s
9.6.14. mvme162
9.6.14.1. Overview
9.6.14.2. Board Setup
9.6.14.3. Downloading and Executing
9.6.15. mvme167
9.6.16. uC5282
9.7. microblaze (MicroBlaze)
9.7.1. KCU105 QEMU
9.7.1.1. Boot via ELF
9.7.1.2. Clock Driver
9.7.1.3. Console Driver
9.7.1.4. Network Driver
9.7.1.5. QSPI NOR JFFS2 Driver
9.7.1.6. Running Executables
9.7.1.7. Debugging with QEMU
9.7.2. KCU105
9.7.2.1. Clock Driver
9.7.2.2. Console Driver
9.7.2.3. Debugging
9.8. mips (MIPS)
9.8.1. csb350
9.8.2. hurricane
9.8.3. jmr3904
9.8.4. malta
9.8.5. rbtx4925
9.8.6. rbtx4938
9.9. moxie
9.9.1. moxiesim
9.10. nios2 (Nios II)
9.10.1. nios2_iss
9.11. or1k (OpenRISC 1000)
9.11.1. generic_or1k
9.12. powerpc (PowerPC)
9.12.1. beatnik
9.12.2. gen5200
9.12.3. gen83xx
9.12.4. haleakala
9.12.5. motorola_powerpc
9.12.5.1. Boot Image Generation
9.12.6. mpc55xxevb
9.12.7. mpc8260ads
9.12.8. mvme3100
9.12.9. mvme5500
9.12.10. psim
9.12.11. qemuppc
9.12.12. qoriq (QorIQ)
9.12.12.1. Boot via U-Boot
9.12.12.2. Clock Driver
9.12.12.3. Console Driver
9.12.12.4. Network Interface Driver
9.12.12.5. Topaz Hypervisor Guest
9.12.13. ss555
9.12.14. t32mppc
9.12.15. tqm8xx
9.12.16. virtex
9.12.17. virtex4
9.12.18. virtex5
9.13. riscv (RISC-V)
9.13.1. riscv
9.13.1.1. Build Configuration Options
9.13.1.2. Interrupt Controller
9.13.1.3. Clock Driver
9.13.1.4. Console Driver
9.13.1.5. QEMU
9.13.1.6. Spike
9.13.1.7. Microchip PolarFire SoC
9.13.1.8. Kendryte K210
9.13.2. noel
9.13.2.1. Reference Designs
9.13.2.2. Build Configuration Options
9.13.3. griscv
9.13.4. NIOS V
9.13.4.1. Reference Designs
9.13.4.2. Build Configuration Options
9.13.4.3. Building the Cyclone 10 LP BSP
9.13.4.4. Program Cyclone 10 LP Evaluation Board
9.14. sh (SuperH)
9.14.1. gensh1
9.14.2. gensh2
9.14.3. gensh4
9.14.4. shsim
9.15. sparc64 (SPARC V9)
9.15.1. niagara
9.15.2. usiii
9.16. sparc (SPARC / LEON)
9.16.1. erc32
9.16.2. leon2
9.16.3. leon3
9.16.3.1. Driver Manager
9.16.3.2. Build Configuration Options
9.17. v850 (V850)
9.17.1. gdbv850sim
9.18. x86_64
9.18.1. amd64
9.18.1.1. Build Configuration Options
9.18.1.2. Testing with QEMU
9.18.1.3. Using the RTEMS tester
9.18.1.4. Paging
9.18.1.5. Interrupt Setup
9.18.1.6. Clock Driver
9.18.1.7. Console Driver
10. Executables
10.1. RTEMS Executable
10.2. Building an Application
10.2.1. Machine Flags and ABI
10.3. Target Execution
10.4. BSP Initialization
10.5. RTEMS Initialization
10.5.1. System Initialization Handlers
10.6. Dynamic Loader
10.6.1. System Design
10.6.2. Loader Interface
10.6.3. Symbols
10.6.3.1. Base Image Symbols
10.6.3.2. Embedded Symbols
10.6.3.3. Loadable Symbols
10.6.4. Unresolved Symbols
10.6.5. Libraries
10.6.6. Large Memory
10.6.7. Allocator
10.6.8. Languages
10.6.9. Thread Local Storage
10.6.10. Architectures
10.6.10.1. AArch64
10.6.10.2. ARM
10.6.10.3. PowerPC
10.7. Device Tree
10.7.1. Building the DTB
10.7.2. Using Device Tree Overlay
11. Debugging
11.1. Debugging with GDB
11.1.1. Debugging with GDB and QEMU
11.1.1.1. Steps to Set Up Remote Debugging with QEMU
11.1.2. Debugging with GDB and OpenOCD
11.1.3. Debugging with GDB and libdebugger
11.2. Pretty Printing and GDB
11.2.1. Enabling Pretty-printing in RTEMS
12. Testing
12.1. Test Banners
12.2. Test Controls
12.2.1. Expected Test States
12.2.2. Test Configuration
12.3. Test Builds
12.4. Tester Configuration
12.4.1. Defaults
12.4.2. BSP and User Configuration
12.4.3. Configuration Scripts
12.4.3.1. Console
12.4.3.2. Execute
12.4.3.3. GDB
12.4.3.4. TFTP
12.4.3.5. Wait
12.5. Coverage Analysis
12.6. Consoles
12.7. Simulation
12.8. GDB and JTAG
12.9. TFTP and U-Boot
12.9.1. Target Hardware
12.9.1.1. U-Boot Set Up
12.9.2. BSP Configuration
12.9.3. TFTP Sequences
13. Tracing
13.1. Introduction to Tracing
13.1.1. RTEMS Trace Using Trace Buffering
13.1.2. RTEMS Trace Using Printk
13.2. Tracing Examples
13.2.1. Features
13.2.2. Prerequisites
13.2.3. Demonstration
13.3. Capture Engine
13.3.1. Capture Engine Commands
13.3.2. Example
13.4. Trace Linker
13.4.1. Command Line
13.4.2. Configuration (INI) files
13.4.2.1. Tracer Section
13.4.2.2. Options section
13.4.2.3. Trace Section
13.4.2.4. Function Section
13.4.2.5. Generators
13.4.3. Development
13.5. Event Recording
13.5.1. Target System: Configuration and Event Generation
13.5.2. Transfer of Event Records to the Host Computer
13.5.3. Analysis of Event Records on the Host Computer
14. Changing Versions
14.1. RTEMS 4.11 to RTEMS 5
14.1.1. Application Configuration Options
14.1.2. Clock Manager
14.1.3. File Descriptors
14.1.4. Networking
14.1.5. Shell Environment
14.2. RTEMS 5 to RTEMS 6
14.2.1. Update to GCC 10 and Later
14.2.2. No -specs bsp_specs GCC Option
14.2.3. Replacements for Removed APIs
15. Host Tools
15.1. RTEMS Linker
15.2. RTEMS Symbols
15.2.1. Symbol Table
15.2.2. 2-Pass Linking
15.2.3. Command
15.2.4. Examples
15.3. RTEMS Executable Infomation
15.3.1. System Initialisation
15.3.2. Command
15.3.3. Examples
15.4. RTEMS BSP Builder
15.4.1. Developer Workflows
15.4.2. Build Characteristics
15.4.2.1. Profiles
15.4.2.2. Builds
15.4.3. Build Configurations
15.4.4. Performance
15.4.5. Command
15.4.5.1. Examples
15.5. RTEMS Tester and Run
15.5.1. Available BSP testers
15.5.2. Building RTEMS Tests
15.5.3. Running the Tests
15.5.4. Test Status
15.5.4.1. Pass
15.5.4.2. Fail
15.5.4.3. User-input
15.5.4.4. Expected-fail
15.5.4.5. Indeterminate
15.5.4.6. Benchmark
15.5.4.7. Timeout
15.5.4.8. Invalid
15.5.5. Logging
15.5.5.1. All
15.5.5.2. Failures
15.5.5.3. None
15.5.6. Reporting
15.5.7. Running Tests in Parallel
15.5.8. Command Line Help
15.6. RTEMS Boot Image
15.6.1. Boot Loaders
15.6.1.1. U-Boot
15.6.2. Hosts
15.6.2.1. FreeBSD
15.6.2.2. Linux
15.6.2.3. MacOS
15.6.3. Configuration
15.6.4. Command
15.6.5. Examples
15.7. RTEMS TFTP Proxy
15.7.1. Operation
15.7.2. Configuration
15.7.3. Command
15.7.4. Examples
16. Source Builder
16.1. Why Build from Source?
16.2. Project Sets
16.2.1. Bare Metal
16.2.2. RTEMS
16.2.3. Patches
16.2.3.1. Testing a Newlib Patch
16.3. Cross and Canadian Cross Building
16.3.1. Cross Building
16.3.2. Canadian Cross Building
16.4. Third-Party Packages
16.4.1. Vertical Integration
16.4.2. Building
16.4.3. Adding
16.4.4. Host and Build Flags
16.4.5. BSP Support
16.4.6. BSP Configuration
16.5. Configuration
16.5.1. Source and Patches
16.5.1.1. HTTP, HTTPS, and FTP
16.5.1.2. GIT
16.5.2. Macros and Defaults
16.5.2.1. Macro Maps and Files
16.5.2.2. Personal Macros
16.5.3. Configuration Reports
16.5.3.1. Report Mailing
16.5.4. Build Set Files
16.5.5. Configuration Control
16.5.6. Personal Configurations
16.5.7. New Configurations
16.5.7.1. Layering by Including
16.5.7.2. Configuration File Numbering
16.5.7.3. Common Configuration Scripts
16.5.7.4. DTC Example
16.5.7.5. Debugging
16.5.8. Scripting
16.5.8.1. Expanding
16.5.8.2. %prep
16.5.8.3. %build
16.5.8.4. %install
16.5.8.5. %clean
16.5.8.6. %include
16.5.8.7. %name
16.5.8.8. %summary
16.5.8.9. %release
16.5.8.10. %version
16.5.8.11. %buildarch
16.5.8.12. %source
16.5.8.13. %patch
16.5.8.14. %hash
16.5.8.15. %echo
16.5.8.16. %warning
16.5.8.17. %error
16.5.8.18. %select
16.5.8.19. %define
16.5.8.20. %undefine
16.5.8.21. %if
16.5.8.22. %ifn
16.5.8.23. %ifarch
16.5.8.24. %ifnarch
16.5.8.25. %ifos
16.5.8.26. %else
16.5.8.27. %endfi
16.5.8.28. %bconf_with
16.5.8.29. %bconf_without
16.6. Commands
16.6.1. Checker (sb-check)
16.6.2. Defaults (sb-defaults)
16.6.3. Set Builder (sb-set-builder)
16.6.4. Track (sb-track)
16.7. Building and Deploying Tool Binaries
16.8. Bugs, Crashes, and Build Failures
16.8.1. Contributing
16.9. History
17. Rust
17.1. Bare Metal Rust with RTEMS
17.1.1. Build a Container
17.1.2. Build the RTEMS Tools
17.1.3. Build and Install the RTEMS BSPs
17.1.4. Install and Setup Rust Tools
17.1.5. Setup a Rust Project and Create Sources
17.1.6. Build and Run on RISC-V
17.1.7. Build and Run on SPARC
18. Glossary
Index
RTEMS User Manual
9.
Board Support Packages
9.2.
arm (ARM)
9.2.5.
csb337
9.2.5.
csb337
ΒΆ
TODO.