RTEMS User Manual Release 6.7b289f6 (23th September 2021) © 1988, 2020 RTEMS Project and contributors CONTENTS 1 Introduction 3 1.1 Overview........................................4 1.2 Features.........................................5 1.3 Ecosystem.......................................8 1.3.1 Rational....................................8 1.3.2 Open Source..................................9 1.3.3 Deployment..................................9 1.4 Real-time Application Systems............................ 10 1.5 Real-time Executive.................................. 11 2 Quick Start 13 2.1 Preparation....................................... 14 2.1.1 Host Computer................................ 14 2.1.2 Selecting a BSP................................ 14 2.1.3 Selecting a Version of RTEMS........................ 15 2.2 Choose an Installation Prefix............................. 16 2.3 Obtain the Sources................................... 17 2.3.1 Releases.................................... 17 2.3.2 Git....................................... 18 2.3.3 Offline Download............................... 18 2.4 Install the Tool Suite.................................. 19 2.4.1 Need for RTEMS-Specific Cross-Compiler.................. 20 2.5 Build a Board Support Package (BSP)........................ 21 2.5.1 RSB BSP Build................................. 21 2.5.2 Manual BSP Build............................... 22 2.6 Test a Board Support Package (BSP)......................... 25 2.7 Build Your Application................................. 27 2.8 Build an RSB Package................................. 31 2.8.1 RTEMS Packages............................... 31 2.8.2 BSP Stack Build................................ 31 2.8.3 Package Build................................. 33 2.9 GSoC Getting Started................................. 34 2.9.1 Installing Dependencies........................... 34 2.9.2 Choosing an installation prefix........................ 34 2.9.3 Downloading the Sources.......................... 35 2.9.4 Installing the Tool Suite........................... 35 2.9.5 Building the Board Support Package.................... 35 2.9.6 Testing the Board Support Package..................... 35 i 2.9.7 Prove You Can Work On RTEMS....................... 35 2.9.8 Creating and Sending Patches........................ 36 3 Support and Contributing 37 3.1 RTEMS Project Support................................ 38 3.1.1 Users Mailing List............................... 38 3.1.2 Documentation................................ 38 3.1.3 All Mailing Lists................................ 38 3.1.4 IRC....................................... 38 3.2 Report Bugs...................................... 39 3.2.1 Search for Existing Bugs........................... 39 3.2.2 Not RTEMS Bugs............................... 39 3.2.3 Good Bug Reports............................... 40 3.2.4 Nobody Fixes my Bug............................. 41 3.3 Contributing...................................... 42 3.3.1 How to Contribute?.............................. 42 3.3.2 Preparing and Sending Patches....................... 42 3.3.3 Checklist for Patches............................. 42 3.3.4 Patch Review Process............................. 43 3.3.5 Why Contribute?............................... 43 3.3.6 Common Questions and Answers...................... 45 3.4 Commercial Support Services............................. 47 4 Host Computer 49 4.1 Python......................................... 50 4.1.1 Virtual Environment............................. 50 4.1.2 Symbolic Link................................. 51 4.1.3 Directly Invoking Python........................... 51 4.2 Host Operating Systems................................ 52 4.3 POSIX Hosts...................................... 54 4.3.1 Root Access.................................. 54 4.3.2 Linux...................................... 54 4.3.2.1 ArchLinux.............................. 54 4.3.2.2 CentOS................................ 55 4.3.2.3 Fedora................................ 55 4.3.2.4 Raspbian............................... 55 4.3.2.5 Ubuntu................................ 55 4.3.2.6 Linux Mint.............................. 56 4.3.2.7 openSUSE.............................. 56 4.3.3 FreeBSD.................................... 56 4.3.4 NetBSD.................................... 57 4.4 Apple macOS...................................... 58 4.4.1 Catalina.................................... 58 4.4.2 Sierra..................................... 58 4.4.3 Mavericks................................... 58 4.5 Microsoft Windows.................................. 59 4.5.1 Windows Path Length............................. 59 4.5.2 Windows Spaces In Paths........................... 59 4.5.3 Parallel Builds with Make.......................... 60 4.5.4 POSIX Support................................ 60 4.5.5 Python..................................... 60 4.5.6 MSYS2..................................... 61 ii 4.5.7 Cygwin..................................... 62 5 Installation 65 5.1 Releases......................................... 66 5.1.1 RTEMS Tools and Kernel........................... 67 5.2 Developer (Unstable)................................. 73 5.2.1 POSIX and OS X Host Tools Chain...................... 73 5.2.2 Windows Host Tool Chain.......................... 78 5.2.2.1 RTEMS Windows Tools....................... 78 5.2.2.2 Building the Kernel......................... 82 5.3 RTEMS Kernel..................................... 87 5.3.1 Development Sources............................. 87 5.3.2 Tools Path Set Up............................... 87 5.3.3 Bootstrapping................................. 87 5.3.4 Building a BSP................................ 88 5.3.5 Installing A BSP................................ 91 5.3.6 Contributing Patches............................. 92 5.4 Project Sandboxing.................................. 94 6 Target Hardware 97 6.1 Targets......................................... 98 6.2 Architectures...................................... 99 6.3 Tiers.......................................... 101 7 BSP Build System 103 7.1 Overview........................................ 104 7.2 Work Flow....................................... 105 7.3 Commands....................................... 106 7.3.1 Help...................................... 106 7.3.2 BSP List.................................... 106 7.3.3 BSP Defaults.................................. 106 7.3.4 Configure................................... 107 7.3.5 Build, Clean, and Install........................... 107 7.4 Configuration..................................... 108 7.5 Migration from Autoconf/Automake......................... 110 8 Board Support Packages 113 8.1 aarch64 (AArch64).................................. 114 8.1.1 Qemu A53................................... 114 8.1.1.1 Boot via ELF............................. 114 8.1.1.2 Clock Driver............................. 114 8.1.1.3 Console Driver............................ 114 8.1.1.4 Running Executables......................... 114 8.1.2 Qemu A72................................... 114 8.1.2.1 Boot via ELF............................. 114 8.1.2.2 Clock Driver............................. 114 8.1.2.3 Console Driver............................ 115 8.1.2.4 Running Executables......................... 115 8.1.3 Qemu Xilinx Versal.............................. 115 8.1.3.1 Boot via ELF............................. 115 8.1.3.2 Clock Driver............................. 115 8.1.3.3 Console Driver............................ 115 iii 8.1.3.4 Running Executables......................... 115 8.1.4 Qemu Xilinx ZynqMP............................. 116 8.1.4.1 Boot on QEMU............................ 116 8.1.4.2 Boot on ZynqMP Hardware..................... 116 8.1.4.3 Hardware Boot Image Generation................. 116 8.1.4.4 Clock Driver............................. 116 8.1.4.5 Console Driver............................ 116 8.1.4.6 SDHCI Driver............................. 117 8.1.4.7 Network Configuration....................... 117 8.1.4.8 Running Executables on QEMU................... 117 8.2 arm (ARM)....................................... 118 8.2.1 altera-cyclone-v (Intel Cyclone V)...................... 118 8.2.1.1 Boot via U-Boot........................... 118 8.2.1.2 Clock Driver............................. 118 8.2.1.3 Console Driver............................ 118 8.2.1.4 I2C Driver.............................. 119 8.2.1.5 Network Interface Driver...................... 119 8.2.1.6 MMC/SDCard Driver........................ 119 8.2.1.7 USB Host Driver........................... 119 8.2.1.8 Caveats................................ 119 8.2.2 atsam..................................... 119 8.2.3 beagle..................................... 119 8.2.3.1 Boot via U-Boot........................... 120 8.2.3.2 Getting the Device Tree Blob.................... 120 8.2.3.3 Writing the uEnv.txt file....................... 120 8.2.3.4 I2C Driver.............................. 120 8.2.3.5 SPI Driver............................... 121 8.2.3.6 Debugging using libdebugger.................... 121 8.2.3.7 Debugging Beagle Bone Black using a JTAG debugger and gdb. 122 8.2.4 stm32h7.................................... 123 8.2.4.1 Clock Driver............................. 124 8.2.4.2 Console Driver............................ 124 8.2.4.3 Network Interface Driver...................... 124 8.2.4.4 USB Host Driver........................... 124 8.2.5 csb336..................................... 124 8.2.6 csb337..................................... 124 8.2.7