RTEMS Classic API Guide Release 6.7b289f6 (23th September 2021) © 1988, 2020 RTEMS Project and contributors CONTENTS 1 Preface 3 2 Overview 7 2.1 Introduction......................................8 2.2 Real-time Application Systems............................9 2.3 Real-time Executive.................................. 10 2.4 RTEMS Application Architecture........................... 11 2.5 RTEMS Internal Architecture............................. 12 2.6 User Customization and Extensibility......................... 14 2.7 Portability....................................... 15 2.8 Memory Requirements................................. 16 2.9 Audience........................................ 17 2.10 Conventions...................................... 18 2.11 Manual Organization................................. 19 3 Key Concepts 23 3.1 Introduction...................................... 24 3.2 Objects......................................... 25 3.2.1 Object Names................................. 25 3.2.2 Object IDs................................... 26 3.2.2.1 Object ID Format........................... 26 3.2.3 Object ID Description............................. 26 3.3 Communication and Synchronization........................ 28 3.4 Locking Protocols................................... 29 3.4.1 Priority Inversion............................... 29 3.4.2 Immediate Ceiling Priority Protocol (ICPP)................. 29 3.4.3 Priority Inheritance Protocol......................... 30 3.4.4 Multiprocessor Resource Sharing Protocol (MrsP)............. 30 3.4.5 O(m) Independence-Preserving Protocol (OMIP).............. 30 3.5 Thread Queues..................................... 31 3.6 Time.......................................... 32 3.7 Timer and Timeouts.................................. 33 3.8 Memory Management................................. 34 4 RTEMS Data Types 35 4.1 Introduction...................................... 36 4.2 List of Data Types................................... 37 i 5 Scheduling Concepts 41 5.1 Introduction...................................... 42 5.2 Background....................................... 43 5.2.1 Scheduling Algorithms............................ 43 5.2.2 Priority Scheduling.............................. 43 5.2.3 Scheduling Modification Mechanisms.................... 44 5.2.3.1 Task Priority and Scheduling.................... 44 5.2.3.2 Preemption.............................. 44 5.2.3.3 Timeslicing.............................. 45 5.2.3.4 Manual Round-Robin........................ 45 5.2.4 Dispatching Tasks............................... 45 5.2.5 Task State Transitions............................. 46 5.3 Uniprocessor Schedulers............................... 49 5.3.1 Deterministic Priority Scheduler....................... 49 5.3.2 Simple Priority Scheduler.......................... 49 5.3.3 Earliest Deadline First Scheduler...................... 49 5.3.4 Constant Bandwidth Server Scheduling (CBS)............... 50 5.4 SMP Schedulers.................................... 51 5.4.1 Earliest Deadline First SMP Scheduler.................... 51 5.4.2 Deterministic Priority SMP Scheduler.................... 51 5.4.3 Simple Priority SMP Scheduler....................... 51 5.4.4 Arbitrary Processor Affinity Priority SMP Scheduler............ 51 5.5 Directives........................................ 52 5.5.1 rtems_scheduler_ident()........................... 53 5.5.2 rtems_scheduler_ident_by_processor()................... 54 5.5.3 rtems_scheduler_ident_by_processor_set()................. 55 5.5.4 rtems_scheduler_get_maximum_priority()................. 57 5.5.5 rtems_scheduler_map_priority_to_posix()................. 58 5.5.6 rtems_scheduler_map_priority_from_posix()................ 59 5.5.7 rtems_scheduler_get_processor()...................... 60 5.5.8 rtems_scheduler_get_processor_maximum()................ 61 5.5.9 rtems_scheduler_get_processor_set().................... 62 5.5.10 rtems_scheduler_add_processor()...................... 63 5.5.11 rtems_scheduler_remove_processor().................... 64 6 Initialization Manager 67 6.1 Introduction...................................... 68 6.2 Background....................................... 69 6.2.1 Initialization Tasks.............................. 69 6.2.2 The Idle Task................................. 69 6.2.3 Initialization Manager Failure........................ 69 6.3 Operations....................................... 70 6.3.1 Initializing RTEMS.............................. 70 6.3.2 Global Construction.............................. 74 6.4 Directives........................................ 76 6.4.1 rtems_initialize_executive()......................... 77 7 Task Manager 79 7.1 Introduction...................................... 80 7.2 Background....................................... 81 7.2.1 Task Definition................................ 81 7.2.2 Task Control Block.............................. 81 ii 7.2.3 Task Memory................................. 81 7.2.4 Task Name................................... 82 7.2.5 Task States................................... 82 7.2.6 Task Priority.................................. 82 7.2.7 Task Mode................................... 83 7.2.8 Accessing Task Arguments.......................... 84 7.2.9 Floating Point Considerations........................ 84 7.2.10 Building a Task Attribute Set......................... 85 7.2.11 Building a Mode and Mask.......................... 85 7.3 Operations....................................... 87 7.3.1 Creating Tasks................................. 87 7.3.2 Obtaining Task IDs.............................. 87 7.3.3 Starting and Restarting Tasks........................ 87 7.3.4 Suspending and Resuming Tasks....................... 87 7.3.5 Delaying the Currently Executing Task................... 88 7.3.6 Changing Task Priority............................ 88 7.3.7 Changing Task Mode............................. 88 7.3.8 Task Deletion................................. 88 7.3.9 Setting Affinity to a Single Processor.................... 89 7.3.10 Transition Advice for Removed Notepads.................. 89 7.3.11 Transition Advice for Removed Task Variables............... 89 7.4 Directives........................................ 90 7.4.1 rtems_task_create().............................. 91 7.4.2 rtems_task_construct()............................ 96 7.4.3 rtems_task_ident().............................. 99 7.4.4 rtems_task_self()............................... 101 7.4.5 rtems_task_start().............................. 102 7.4.6 rtems_task_restart()............................. 104 7.4.7 rtems_task_delete().............................. 106 7.4.8 rtems_task_exit()............................... 108 7.4.9 rtems_task_suspend()............................ 109 7.4.10 rtems_task_resume()............................. 111 7.4.11 rtems_task_is_suspended().......................... 112 7.4.12 rtems_task_set_priority()........................... 113 7.4.13 rtems_task_get_priority().......................... 115 7.4.14 rtems_task_mode().............................. 117 7.4.15 rtems_task_wake_after()........................... 120 7.4.16 rtems_task_wake_when().......................... 121 7.4.17 rtems_task_get_scheduler()......................... 122 7.4.18 rtems_task_set_scheduler()......................... 123 7.4.19 rtems_task_get_affinity()........................... 125 7.4.20 rtems_task_set_affinity()........................... 127 7.4.21 rtems_task_iterate()............................. 129 7.4.22 RTEMS_TASK_STORAGE_SIZE()...................... 130 7.5 Deprecated Directives................................. 131 7.5.1 ITERATE_OVER_ALL_THREADS - Iterate Over Tasks............ 132 7.6 Removed Directives.................................. 133 7.6.1 TASK_GET_NOTE - Get task notepad entry................. 134 7.6.2 TASK_SET_NOTE - Set task notepad entry................. 135 7.6.3 TASK_VARIABLE_ADD - Associate per task variable............ 136 7.6.4 TASK_VARIABLE_GET - Obtain value of a per task variable........ 137 iii 7.6.5 TASK_VARIABLE_DELETE - Remove per task variable........... 138 8 Interrupt Manager 139 8.1 Introduction...................................... 140 8.2 Background....................................... 143 8.2.1 Processing an Interrupt............................ 143 8.2.2 RTEMS Interrupt Levels........................... 144 8.2.3 Disabling of Interrupts by RTEMS...................... 144 8.3 Operations....................................... 145 8.3.1 Establishing an ISR.............................. 145 8.3.2 Directives Allowed from an ISR....................... 145 8.4 Directives........................................ 148 8.4.1 rtems_interrupt_catch()........................... 149 8.4.2 rtems_interrupt_disable().......................... 151 8.4.3 rtems_interrupt_enable()........................... 153 8.4.4 rtems_interrupt_flash()............................ 154 8.4.5 rtems_interrupt_local_disable()....................... 155 8.4.6 rtems_interrupt_local_enable()....................... 157 8.4.7 rtems_interrupt_is_in_progress()...................... 158 8.4.8 rtems_interrupt_lock_initialize()...................... 159 8.4.9 rtems_interrupt_lock_destroy()....................... 160 8.4.10 rtems_interrupt_lock_acquire()....................... 161 8.4.11 rtems_interrupt_lock_release()....................... 163 8.4.12 rtems_interrupt_lock_acquire_isr()..................... 164 8.4.13 rtems_interrupt_lock_release_isr()..................... 165 8.4.14 rtems_interrupt_lock_interrupt_disable().................