RTEMS C User Documentation Release 4.11.3 ©Copyright 2016, RTEMS Project (built 15th February 2018) CONTENTS I RTEMS C User’s Guide1 1 Preface 5 2 Overview 9 2.1 Introduction...................................... 10 2.2 Real-time Application Systems............................ 11 2.3 Real-time Executive.................................. 12 2.4 RTEMS Application Architecture........................... 13 2.5 RTEMS Internal Architecture............................. 14 2.6 User Customization and Extensibility......................... 15 2.7 Portability....................................... 16 2.8 Memory Requirements................................. 17 2.9 Audience........................................ 18 2.10 Conventions...................................... 19 2.11 Manual Organization................................. 20 3 Key Concepts 23 3.1 Introduction...................................... 24 3.2 Objects......................................... 25 3.2.1 Object Names................................. 25 3.2.2 Object IDs................................... 25 3.2.2.1 Thirty-Two Object ID Format.................... 25 3.2.2.2 Sixteen Bit Object ID Format.................... 26 3.2.3 Object ID Description............................. 26 3.3 Communication and Synchronization........................ 27 3.4 Time.......................................... 28 3.5 Memory Management................................. 29 4 RTEMS Data Types 31 4.1 Introduction...................................... 32 4.2 List of Data Types................................... 33 5 Scheduling Concepts 37 5.1 Introduction...................................... 38 5.2 Scheduling Algorithms................................ 39 5.2.1 Priority Scheduling.............................. 39 5.2.2 Deterministic Priority Scheduler....................... 39 5.2.3 Simple Priority Scheduler.......................... 40 i 5.2.4 Simple SMP Priority Scheduler....................... 40 5.2.5 Earliest Deadline First Scheduler...................... 40 5.2.6 Constant Bandwidth Server Scheduling (CBS)............... 40 5.3 Scheduling Modification Mechanisms........................ 42 5.3.1 Task Priority and Scheduling......................... 42 5.3.2 Preemption.................................. 42 5.3.3 Timeslicing.................................. 42 5.3.4 Manual Round-Robin............................. 42 5.4 Dispatching Tasks................................... 43 5.5 Task State Transitions................................. 44 6 Initialization Manager 47 6.1 Introduction...................................... 48 6.2 Background....................................... 49 6.2.1 Initialization Tasks.............................. 49 6.2.2 System Initialization............................. 49 6.2.3 The Idle Task................................. 49 6.2.4 Initialization Manager Failure........................ 49 6.3 Operations....................................... 51 6.3.1 Initializing RTEMS.............................. 51 6.3.2 Shutting Down RTEMS............................ 52 6.4 Directives........................................ 53 6.4.1 INITIALIZE_EXECUTIVE - Initialize RTEMS................. 54 6.4.2 SHUTDOWN_EXECUTIVE - Shutdown RTEMS............... 55 7 Task Manager 57 7.1 Introduction...................................... 58 7.2 Background....................................... 59 7.2.1 Task Definition................................ 59 7.2.2 Task Control Block.............................. 59 7.2.3 Task States................................... 59 7.2.4 Task Priority.................................. 59 7.2.5 Task Mode................................... 60 7.2.6 Accessing Task Arguments.......................... 60 7.2.7 Floating Point Considerations........................ 61 7.2.8 Per Task Variables............................... 61 7.2.9 Building a Task Attribute Set......................... 62 7.2.10 Building a Mode and Mask.......................... 62 7.3 Operations....................................... 64 7.3.1 Creating Tasks................................. 64 7.3.2 Obtaining Task IDs.............................. 64 7.3.3 Starting and Restarting Tasks........................ 64 7.3.4 Suspending and Resuming Tasks....................... 64 7.3.5 Delaying the Currently Executing Task................... 64 7.3.6 Changing Task Priority............................ 65 7.3.7 Changing Task Mode............................. 65 7.3.8 Notepad Locations.............................. 65 7.3.9 Task Deletion................................. 65 7.3.10 Transition Advice for Obsolete Directives.................. 65 7.3.10.1 Notepads............................... 65 7.4 Directives........................................ 67 7.4.1 TASK_CREATE - Create a task........................ 68 ii 7.4.2 TASK_IDENT - Get ID of a task........................ 70 7.4.3 TASK_SELF - Obtain ID of caller....................... 71 7.4.4 TASK_START - Start a task.......................... 72 7.4.5 TASK_RESTART - Restart a task....................... 73 7.4.6 TASK_DELETE - Delete a task........................ 74 7.4.7 TASK_SUSPEND - Suspend a task...................... 75 7.4.8 TASK_RESUME - Resume a task....................... 76 7.4.9 TASK_IS_SUSPENDED - Determine if a task is Suspended......... 77 7.4.10 TASK_SET_PRIORITY - Set task priority................... 78 7.4.11 TASK_MODE - Change the current task mode............... 79 7.4.12 TASK_GET_NOTE - Get task notepad entry................. 80 7.4.13 TASK_SET_NOTE - Set task notepad entry................. 81 7.4.14 TASK_WAKE_AFTER - Wake up after interval................ 82 7.4.15 TASK_WAKE_WHEN - Wake up when specified............... 83 7.4.16 ITERATE_OVER_ALL_THREADS - Iterate Over Tasks............ 84 7.4.17 TASK_VARIABLE_ADD - Associate per task variable............ 85 7.4.18 TASK_VARIABLE_GET - Obtain value of a per task variable........ 86 7.4.19 TASK_VARIABLE_DELETE - Remove per task variable........... 87 8 Interrupt Manager 89 8.1 Introduction...................................... 90 8.2 Background....................................... 91 8.2.1 Processing an Interrupt............................ 91 8.2.2 RTEMS Interrupt Levels........................... 91 8.2.3 Disabling of Interrupts by RTEMS...................... 91 8.3 Operations....................................... 93 8.3.1 Establishing an ISR.............................. 93 8.3.2 Directives Allowed from an ISR....................... 93 8.4 Directives........................................ 95 8.4.1 INTERRUPT_CATCH - Establish an ISR................... 96 8.4.2 INTERRUPT_DISABLE - Disable Interrupts................. 97 8.4.3 INTERRUPT_ENABLE - Enable Interrupts.................. 98 8.4.4 INTERRUPT_FLASH - Flash Interrupts................... 99 8.4.5 INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor 100 8.4.6 INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor. 101 8.4.7 INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock.......... 102 8.4.8 INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock........... 103 8.4.9 INTERRUPT_LOCK_RELEASE - Release an ISR Lock............ 104 8.4.10 INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR.... 105 8.4.11 INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR.... 106 8.4.12 INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress.......... 107 9 Clock Manager 109 9.1 Introduction...................................... 110 9.2 Background....................................... 111 9.2.1 Required Support............................... 111 9.2.2 Time and Date Data Structures....................... 111 9.2.3 Clock Tick and Timeslicing.......................... 111 9.2.4 Delays..................................... 111 9.2.5 Timeouts.................................... 111 9.3 Operations....................................... 113 9.3.1 Announcing a Tick.............................. 113 iii 9.3.2 Setting the Time............................... 113 9.3.3 Obtaining the Time.............................. 113 9.4 Directives........................................ 114 9.4.1 CLOCK_SET - Set date and time....................... 115 9.4.2 CLOCK_GET - Get date and time information............... 116 9.4.3 CLOCK_GET_TOD - Get date and time in TOD format........... 117 9.4.4 CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format... 118 9.4.5 CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch.... 119 9.4.6 CLOCK_GET_TICKS_PER_SECOND - Get ticks per second......... 120 9.4.7 CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value... 121 9.4.8 CLOCK_TICK_LATER - Get tick value in the future............. 122 9.4.9 CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds 123 9.4.10 CLOCK_TICK_BEFORE - Is tick value is before a point in time...... 124 9.4.11 CLOCK_GET_UPTIME - Get the time since boot.............. 125 9.4.12 CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval for- mat....................................... 126 9.4.13 CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot...... 127 9.4.14 CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot 128 10 Timer Manager 129 10.1 Introduction...................................... 130 10.2 Background....................................... 131 10.2.1 Required Support............................... 131 10.2.2 Timers..................................... 131 10.2.3 Timer Server................................. 131 10.2.4 Timer Service Routines............................ 131 10.3 Operations....................................... 132 10.3.1 Creating a Timer..............................