Home

RTEMS C User's Guide - RTEMS Documentation

1. 0 129 event set building 00 129 event set definition 22 129 OVENS chaise eerte bode oie hades RPUPHERERPA TE 129 extensioti SELG renien a AO a ERTEAN 231 external addresses definition 163 352 F fatal error detection slslesluue 185 fatal error processing 00 000 185 fatal error user extension 00 00s 185 fatal error announce slsseeeeess 187 fatal erfORS 22 3d ber ERR REPRE 185 fire a task based timer at wall time 96 fire a timer after an interval 92 fire a timer at wall time 93 fire task based a timer after an interval 95 flash interrupts coi sik pea dad p ReETMRR des 68 floating pont sese DUbROLURUOREERS CE xus 34 flush a semaphore 0cce eee eeees 112 flush messages on a queue 005 127 G get buffer from partition 147 get class from object ID 14 get ID of a barrier 2 2 0000 221 get ID of a message queue 04 119 get ID of a partition 145 get ID of a period iiio ere rere 208 get ID Of ports vases sce oo ieee even eee 166 get ID Of TegiON colorem e EP RRRBIDC E ERR bey 154 get ID of asemaphore 107 get ID of task does libt Rer RI EE ririt 42 get ID of a
2. 163 interrupt level task sseeeesuueeess 33 interrupt levels 222b lI Rei Ded 62 interrupt PLOCESSING lice eI VIT RI Pris 61 IQ Control iidem pr e PT DRE 184 TO Manager co usa EP PEU ER wie HE eek 171 is interrupt in progress ssssusuuuuus 69 is task suspended eee e eee eee 49 ISR vs ASR ivicaiteedh biddiesie Maeek eid be 135 iterate over all threads 0 0 eee ee 56 L lock a barrier s co sseceadsaceie as ssdesosaestd 223 lock a semaphores 1 0 loe ros 109 lookup device major and minor number 179 M major device number 05 172 manual round robin eee eee 190 Memory managemenL isoeseee er vidas re es 16 message queue attributes 113 imessage quelles zc eei Ere Iq Re br UPPER 113 MESSAGES ec rede WAPHRPECEDOPRPTHRR E RIPE DIIS 113 minor device number uuesesssuss 172 MPCI and remote operations 212 MPQGL entry polnis eR Ree Rev ed 274 MPG definition eee bet RDRR RR 274 MUltiprocessM Eeee i e ps tortie exes 271 multiprocessing topologies suus 271 Multiprocessor Communications Interface Table UOTE 265 Multiprocessor Configuration Table 263 mutual exclusion ssseeeeeee esee 99 N nanoseconds extension sese esse 82 nanoseconds time accuracy ssssssss 82 nodes definition 0 0 ce
3. 122 R rate mononitonic tasks 000 00 0s 195 Rate Monotonic Scheduling Algorithm definition PT 197 353 read from a device eee e eee eee 182 receive event condition 0 133 receive message from a queue 124 region attribute set building 149 region add memory ee sees 156 r gion definition 4 e 4 rper RAS 149 TEPON Srce serura ia ee edd pure EET Re ees 149 register a device driver 2 05 175 r gisSter device ose EE RE LEDEE TERES 178 release barriep i22 o 6 Si Seeks bener 224 release a semaphore 00 eee eee eee ITI reset MET ciui uses Re Rx RR RP UY 97 reset statistics of all periods 215 reset statistics of period 0006 214 fesizesegmentis o eo ee i aer DEPO ER CP E dd 161 restarting a task eere Y eS 45 resuming task o Re p eas Habe nas 48 return buffer to partitition 148 return segment LO TeglOn oii nose pe epe pee 159 RMS Algorithm definition esses 197 RMS First Deadline Rule 199 RMS Processor Utilization Rule 198 RMS schedulability analysis 198 round robin scheduling 190 RTEMS API Configuration Table 254 RTEMS Configuration Table 250 runtime driver registration 172 S
4. 295 rtems option e ug v ea RR E vs 20 rtems packet prefix sese 20 rtems partition create sss 143 rtems partition delete 146 rtems partition get buffer 147 rtems_partition_ident 145 rtems_partition_return_buffer 148 rtems port create cee eee eee eee 165 rtems_port_delete 0 0 00 167 rtems_port_external_to_internal 168 rtems_port_ident cscs eee m nee 166 rtems port internal to external 169 rtems rate monotonic cancel 209 rtems rate monotonic create 207 rtems_rate_monotonic_delete 210 rtems_rate_monotonic_get_statistics 213 rtems_rate_monotonic_get_status 212 rtems rate monotonic ident 208 rtems rate monotonic period 211 rtems_rate_monotonic_period_statistics bis pete E EE E E E te bs 213 216 rtems_rate_monotonic_period_status 212 rtems_rate_monotonic_report_statistics 216 rtems_rate_monotonic_reset_all_statistics pes E E E E E E EEEE EET 215 rtems_rate_monotonic_reset_statistics 214 rtems region create eee ee 153 rtems region delete 155 rtems region extend s 156 rtems region get segment 157 rtems_region_get_segment_size 160 349 rtems_region_ident
5. s 154 rtems region resize segment 161 rtems region return segment 159 rtems semaphore create sess 105 rtems semaphore delete 108 rtems semaphore flush 112 rtems_semaphore_ident 107 rtems_semaphore_obtain 0 109 rtems semaphore release 111 rtems shutdown executive 30 rtens signal Catch e rb 138 rtens signal send obere ey vs 139 rtems signal set c csc eser ee 20 135 rtems single ic scce pit eerie a deen ERE RAR 21 rtems status Codes e See egere Res 21 rtemns tasK ilg lp dpa EER 21 34 rtems task argument sss 21 rtems_task_begin_extension 21 235 rtems task create eese 40 rtems task create extension 21 233 rtems task delete seess 46 rtems task delete extension 21 294 rtems task ntry nil liec RENEA AE buste 2 rtems task exitted extension 21 235 rtems task get note sseeeess 52 rtems task id t 22 hese de ees aeS 42 rtems_task_is_suspended 49 rtems_task_mode cece cece eee 33 51 rtems_task_priority 00 21 82 rtems task restart lo ls d e ienis 45 rtems task restart extension 21 234 rtems task resume sese 48 rtemns task Self le s d P LerUES 43
6. typedef rtems_extension rtems_fatal_extension Internal errors Source the source bool is internal uint32 t the error typedef struct rtems_task_create_extension thread_create rtems_task_start_extension thread_start rtems_task_restart_extension thread_restart rtems_task_delete_extension thread_delete rtems_task_switch_extension thread_switch rtems_task_begin_extension thread_begin rtems_task_exitted_extension thread_exitted rtems_fatal_extension fatal rtems_extensions_table thread_create is the address of the user supplied subroutine for the TASK_CREATE extension If this extension for task creation is defined it is called from the task_create directive A value of NULL indicates that no extension is provided thread_start is the address of the user supplied subroutine for the TASK_START extension If this extension for task initiation is defined it is called from the task_start directive A value of NULL indicates that no extension is provided thread_restart is the address of the user supplied subroutine for the TASK_RESTART extension If this extension for task re initiation is defined it is called from the task_restart directive A value of NULL indicates that no extension is provided Chapter 23 Configuring a System 263 thread_delete is the address of the user supplied subroutine for the TASK_DELETE extension If this RTEMS extension for task deletion is defined it is cal
7. 179 16 4 6 IO OPEN Open a device lsessseeeeeeeeeeeee 180 16 4 7 IO CLOSE Close a device 0 000 cee eee eee eee 181 16 4 8 IO READ Read from a device sssssssesssse 182 16 4 9 IO WRITE Write to a device seseeeeseeese 183 16 4 10 IO CONTROL Special device services 184 IT Fatal Error MIgHUager cemere 185 Iiri IntroductlOm eve E DRE Re RC EPERE EDEN uU berS CI 185 I2 Ba ckeroundiis us Rpei ERE sme e RENE ER pb eos 185 17 9 Operations ood exire rr bete RDRE RE er e pari ta RI e d eda 185 17 3 1 Announcing a Fatal Error 0 000 urr eee 185 I4 JDir CUyeszisieetuues discre a e dora Detalles Sp alge ade RO dca deg RR n 186 17 4 1 FATAL ERROR OCCURRED Invoke the fatal error Tiatieller ose ieidei teriner t doxtevciegh n Gani dentist hese 187 18 Scheduling Concepts 189 18 1 Introduction egurren b Rr ERE RPRPP DEEP CP 189 18 2 Scheduling Mechanisms 0000 e eee eee eee eens 189 18 2 1 Task Priority and Scheduling 22005 189 18 2 2 Pr empL1On oc lebende e a e iciee a wags Re dixe 190 18 2 3 Timeslcel E 2 nssesieti be cette ace epe a aa 190 18 2 4 Manual Round Robin 0c cece eee eee eee 190 18 2 5 Dispatching a8k8 s eecett nea RA tede eke eles 190 18 3 Task State Transitions uc RR REDE I BPDEEPE ES 191 19 Rate Monotonic Manager 195
8. ihntptr o b 2102 55i a I de dad 22 Concept Index Concept Index A add memory to a region 0 156 announce arrival of package 278 announce fatal error ee eee ee 187 aperiodic task definition 196 ASR cgoivee tadla path howd ee er R TP RP nse 135 ASR mode building esses 136 ASR vS ISR oa scere bee e IEEE dee 135 asynchronous signal routine 135 B DATED eiddi PRU REP ORERIRPIPLPNME 217 binary semaphores 0 e eee eee eee 99 Board Support Packages 00000 225 broadcast message to a queue 123 BSP definition eR eLiRE RR RRSRERG 4 nx 225 BSP Ss cck vecaveke IEPREEE ER eater ee heed eee 225 buffers definition esse ead ears ERR RR 141 build object id from components 300 build object name 2 eee eee 292 C cancel a peri d sinc sec Vaasa este we ge Rr geod 209 cancel ber e ex eee 90 chain append a node uulsssusus 328 chain append a node unprotected 329 chain extract a node cece eee eee 325 chain get first node sisi rn ts 326 chain get head o per iti Miorre RE 316 chain get tail esenp an e RUPEE eb 317 chain imniti lize ec SWEEP eee RE 313 chain initialize empty 06 314 chain insert a node 000 0 cece eee 32T chain is chain empty
9. rtems_name name rtems id period rtems status code status name rtems build name P E R D status rtems_rate_monotonic_create name amp period if status RTEMS_STATUS_SUCCESSFUL printf rtems monotonic create failed with status of Ad Nn rc exit 1 while 1 1 if rtems rate monotonic period period 100 RTEMS TIMEOUT break Perform some periodic actions h missed period so delete period and SELF status rtems rate monotonic delete period if status RTEMS STATUS SUCCESSFUL printf rtems rate monotonic delete failed with status of d n status l exit 1 status rtems_task_delete SELF should not return printf rtems task delete returned with status of d n status exit 1 The above task creates a rate monotonic period as part of its initialization The first time the loop is executed the rtems_rate_monotonic_period directive will initiate the period for 100 ticks and return immediately Subsequent invocations of the rtems_rate_ monotonic_period directive will result in the task blocking for the remainder of the 100 tick period If for any reason the body of the loop takes more than 100 ticks to execute the rtems_rate_monotonic_period directive will return the RTEMS_TIMEOUT status If the above task misses its deadline it will delete the rate monotonic period and itself 19 3 8 Task with M
10. uint32_t node uint32_t maximum_nodes uint32_t maximum_global_objects uint32 t maximum proxies uint32 t extra mpci receive server stack rtems mpci table User mpci table rtems multiprocessing table node is a unique processor identifier and is used in routing messages be tween nodes in a multiprocessor configuration Each processor must have a unique node number RTEMS assumes that node numbers start at one and increase sequentially This assumption can be used to advantage by the user supplied MPCI layer Typically this re quirement is made when the node numbers are used to calculate the address of inter processor communication links Zero should be avoided as a node number because some MPCI layers use node zero to represent broadcasted packets Thus it is recommended that node numbers start at one and increase sequentially When using the rtems confdefs h mechanism for configuring an RT EMS appli cation the value for this field corresponds to the setting of the macro CONFIGURE MP NODE NUMBER If not defined by the application then the CONFIGURE MP NODE NUMBER macro defaults to the value of the NODE NUMBER macro which is set on the compiler command line by the RTEMS Multiprocessing Test Suites maximum nodes is the number of processor nodes in the system When using the rtems confdefs h mechanism for configuring an RTEMS applica tion the value for this field corresponds to the setting of the macro CONFIGURE MP
11. 247 CONFIGURE_MAXIMUM_SEMAPHORES 247 CONFIGURE MAXIMUM TASKS 0 247 CONFIGURE_MAXIMUM_TIMERS 247 CONFIGURE_MAXIMUM_USER_EXTENSIONS 247 CONFIGURE_MEMORY_OVERHEAD 244 CONFIGURE_MESSAGE_BUFFER_MEMORY 244 CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE 244 CONFIGURE_MICROSECONDS_PER_TICK 243 CONFIGURE_MINIMUM_STACK_SIZE 243 CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS 246 CONFIGURE_MP_MAXIMUM_NODES 246 CONFIGURE_MP_MAXIMUM_PROXIES 246 CONFIGURE_MP_MPCI_TABLE_POINTER 246 CONFIGURE MP NODE NUMBER 246 CONFIGURE NUMBER OF TERMIOS PORTS 242 CONFIGURE POSIX HAS OWN INIT THREAD TABLE Settee segue See eedebedqe e egere ie ers 248 CONFIGURE POSIX INIT THREAD ENTRY POINT EP 249 CONFIGURE POSIX INIT THREAD STACK SIZE 249 CONFIGURE POSIX INIT THREAD TABLE 248 CONFIGURE RTEMS INIT TASKS TABLE 247 CONFIGURE_TASK_STACK_ALLOCATOR 243 CONFIGURE_TASK_STACK_DEALLOCATOR 243 348 CONFIGURE_TERMIOS_DISABLED 242 CONFIGURE_TICKS_PER_TIMESLICE 243 CONFIGURE USE IMFS AS BASE FILESYSTEM 242 CONFIGURE ZERO WORKSPACE AUTOMATICALLY 243 I 2nb4D Tolosa Rcs Sd Re AUR OG a SS Re ARR 20 POE 2 AN NM 21 Jnt64 An AE EAE E A aca desde outa 21 Jnt9 d ros ee tee esate aE ws a a D und
12. rtems isr entry new isr handler rtems vector number vector rtems isr entry old isr handler J DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL ISR established successfully RTEMS_INVALID_NUMBER illegal vector number RTEMS_INVALID_ADDRESS illegal ISR entry point or invalid old_isr_handler DESCRIPTION This directive establishes an interrupt service routine ISR for the specified interrupt vector number The new_isr_handler parameter specifies the entry point of the ISR The entry point of the previous ISR for the specified vector is returned in old_isr_handler To release an interrupt vector pass the old handler s address obtained when the vector was first capture NOTES This directive will not cause the calling task to be preempted 66 RTEMS C User s Guide 6 4 2 INTERRUPT_DISABLE Disable Interrupts CALLING SEQUENCE void rtems_interrupt_disable rtems_interrupt_level level 3 this is implemented as a macro and sets level as a side effect DIRECTIVE STATUS CODES NONE DESCRIPTION This directive disables all maskable interrupts and returns the previous level A later invocation of the rtems_interrupt_enable directive should be used to restore the interrupt level NOTES This directive will not cause the calling task to be preempted This directive is implemented as a macro which modifies the level parameter Chapter 6 Interrupt Manager 67 6 4 3 INTERRUPT_ENABLE Enable Interrupts CALL
13. CONFIGURE MAXIMUM PRIORITY is the maximum numeric priority of any task in the system and one less that the number of priority levels in the system The numerically greatest priority is the logically lowest priority in the system and will thus be used by the IDLE task Valid values for this configuration parameter must be one 1 less than than a power of two 2 between 4 and 256 inclusively In other words valid values are 3 7 31 63 127 and 255 Reducing the number of priorities in the system reduces the amount of memory allocated from the RTEMS Workspace By default RTEMS supports 256 priority levels ranging from 0 to 255 so the default value for this field is 255 CONFIGURE MINIMUM STACK SIZE is set to the number of bytes the application wants the minimum stack size to be for every task or thread in the system By default this is set to the recommended minimum stack size for this processor CONFIGURE INTERRUPT STACK SIZE is set to the size of the interrupt stack The interrupt stack size is usually set by the BSP but since this memory may be allocated from the RTEMS Ram Workspace it must be accounted for The default for this field is the configured minimum stack size NOTE In some BSPs changing this constant does NOT change the size of the interrupt stack only the amount of memory reserved for it If not specified the interrupt stack will be of minimum size The default value is the configured minimum stack size CONFIGURE TASK
14. The application developer should remember the following key characteristics of event oper ations when utilizing the event manager e Events provide a simple synchronization facility e Events are aimed at tasks e Tasks can wait on more than one event simultaneously e Events are independent of one another e Events do not hold or transport data e Events are not queued In other words if an event is sent more than once to a task before being received the second and subsequent send operations to that same task have no effect An event set is posted when it is directed or sent to a task A pending event is an event that has been posted but not received An event condition is used to specify the event set which the task desires to receive and the algorithm which will be used to determine when the request is satisfied An event condition is satisfied based upon one of two algorithms which are selected by the user The RTEMS_EVENT_ANY algorithm states that an event condition is satisfied when at least a single requested event is posted The RTEMS_EVENT_ALL algorithm states that an event condition is satisfied when every requested event is posted 11 2 2 Building an Event Set or Condition An event set or condition is built by a bitwise OR of the desired events The set of valid events is RTEMS_EVENT_0 through RTEMS_EVENT_31 If an event is not explicitly specified in the set or condition then it is not present Events are specifically d
15. 12 3 2 Sending a Signal Set The rtems_signal_send directive allows both tasks and ISRs to send signals to a target task The target task and a set of signals are specified to the rtems_signal_send directive The sending of a signal to a task has no effect on the execution state of that task If the task is not the currently running task then the signals are left pending and processed by the task s ASR the next time the task is dispatched to run The ASR is executed immediately before the task is dispatched If the currently running task sends a signal to itself or is sent a signal from an ISR its ASR is immediately dispatched to run provided signal processing is enabled If an ASR with signals enabled is preempted by another task or an ISR and a new signal set is sent then a new copy of the ASR will be invoked nesting the preempted ASR Upon completion of processing the new signal set control will return to the preempted ASR In this situation the ASR must be reentrant Like events identical signals sent to a task are not queued In other words sending the same signal multiple times to a task without any intermediate signal processing occurring for the task has the same result as sending that signal to that task once 12 3 3 Processing an ASR Asynchronous signals were designed to provide the capability to generate software inter rupts The processing of software interrupts parallels that of hardware interrupts As a result the di
16. 28 4 2 Initialize Empty CALLING SEQUENCE void rtems_chain_initialize_empty rtems_chain_control the_chain 25 RETURNS Returns nothing DESCRIPTION This function take in a pointer to a chain control and initializes it to empty NOTES This call will discard any nodes on the chain Chapter 28 Chains 315 28 4 3 Is Null Node CALLING SEQUENCE bool rtems chain is null node const rtems chain node the node 25 RETURNS Returns true is the node point is NULL and false if the node is not NULL DESCRIPTION Tests the node to see if it is a NULL returning true if a null 316 RTEMS C User s Guide 28 4 4 Head CALLING SEQUENCE rtems_chain_node rtems_chain_head rtems_chain_control the_chain RETURNS Returns the permanent head node of the chain DESCRIPTION This function returns a pointer to the first node on the chain Chapter 28 Chains 317 28 4 5 Tail CALLING SEQUENCE rtems chain node rtems_chain_tail rtems chain control the chain 25 RETURNS Returns the permanent tail node of the chain DESCRIPTION This function returns a pointer to the last node on the chain 318 RTEMS C User s Guide 28 4 6 Are Two Nodes Equal CALLING SEQUENCE bool rtems_chain_are_nodes_equal const rtems_chain_node left const rtems chain node right i RETURNS This function returns true if the left node and the right node are equal and false otherwise DESCRIPTION This
17. If an uncorrectable error occurs in the user provided MPCI layer the fatal error handler should be invoked RTEMS assumes the reliable transmission and reception of messages by the MPCI and makes no attempt to detect or correct errors 24 2 5 Proxies A proxy is an RTEMS data structure which resides on a remote node and is used to represent a task which must block as part of a remote operation This action can occur as part of the rtems semaphore obtain and rtems message queue receive directives If the object were local the task s control block would be available for modification to indicate it was blocking on a message queue or semaphore However the task s control block resides only on the same node as the task As a result the remote node must allocate a proxy to represent the task until it can be readied The maximum number of proxies is defined in the Multiprocessor Configuration Table Each node in a multiprocessor system may require a different number of proxies to be configured The distribution of proxy control blocks is application dependent and is different from the distribution of tasks 24 2 6 Multiprocessor Configuration Table The Multiprocessor Configuration Table contains information needed by RTEMS when used in a multiprocessor system This table is discussed in detail in the section Multiprocessor Configuration Table of the Configuring a System chapter 274 RTEMS C User s Guide 24 3 Multiprocessor Communications
18. barrier deleted while waiting RTEMS INVALID ID invalid barrier id DESCRIPTION This directive acquires the barrier specified by id The RTEMS WAIT and RTEMS NO WAIT components of the options parameter indicate whether the calling task wants to wait for the barrier to become available or return immediately if the barrier is not currently available With either RTEMS_WAIT or RTEMS NO WAIT if the current barrier count is positive then it is decremented by one and the barrier is successfully acquired by returning immediately with a successful return code Conceptually the calling task should always be thought of as blocking when it makes this call and being unblocked when the barrier is released If the barrier is configured for manual release this rule of thumb will always be valid If the barrier is configured for automatic release all callers will block except for the one which is the Nth task which trips the automatic release condition The timeout parameter specifies the maximum interval the calling task is willing to be blocked waiting for the barrier If it is set to RTEMS NO TIMEOUT then the calling task will wait forever If the barrier is available or the RTEMS NO WAIT option component is set then timeout is ignored NOTES The following barrier acquisition option constants are defined by RTEMS e RTEMS WAIT task will wait for barrier default e RTEMS NO WAIT task should not wait A clock tick is required
19. extension set created successfully RTEMS_INVALID_NAME invalid extension set name RTEMS_TOO_MANY too many extension sets created DESCRIPTION This directive creates a extension set The assigned extension set id is returned in id This id is used to access the extension set with other user extension manager directives For control and maintenance of the extension set RTEMS allocates an ESCB from the local ESCB free pool and initializes it NOTES This directive will not cause the calling task to be preempted Chapter 22 User Extensions Manager 239 22 4 2 EXTENSION_IDENT Get ID of a extension set CALLING SEQUENCE rtems_status_code rtems_extension_ident rtems_name name rtems_id id DIRECTIVE STATUS CODES RTEMS SUCCESSFUL extension set identified successfully RTEMS INVALID NAME extension set name not found DESCRIPTION This directive obtains the extension set id associated with the extension set name to be acquired If the extension set name is not unique then the extension set id will match one of the extension sets with that name However this extension set id is not guaranteed to correspond to the desired extension set The extension set id is used to access this extension set in other extension set related directives NOTES This directive will not cause the running task to be preempted 240 RTEMS C User s Guide 22 4 3 EXTENSION_DELETE Delete a extension set CALLING SEQUENCE rte
20. rtems id id rtems task entry entry point rtems task argument argument J DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL ask started successfully RTEMS_INVALID_ADDRESS invalid task entry point RTEMS_INVALID_ID invalid task id RTEMS_INCORRECT_STATE task not in the dormant state RTEMS_ILLEGAL_ON_REMOTE_OBJECT cannot start remote task DESCRIPTION This directive readies the task specified by id for execution based on the priority and execution mode specified when the task was created The starting address of the task is given in entry_point The task s starting argument is contained in argument This argument can be a single value or used as an index into an array of parameter blocks The type of this numeric argument is an unsigned integer type with the property that any valid pointer to void can be converted to this type and then converted back to a pointer to void The result will compare equal to the original pointer NOTES The calling task will be preempted if its preemption mode is enabled and the task being started has a higher priority Any actions performed on a dormant task such as suspension or change of priority are nullified when the task is initiated via the rtems_task_start directive Chapter 5 Task Manager 45 5 4 5 TASK_RESTART Restart a task CALLING SEQUENCE rtems_status_code rtems_task_restart rtems_id id rtems_task_argument argument DIRECTIVE STATUS CODES RTEMS SUCCESSFUL tas
21. s initialization giving the entries in this table the lower major numbers The format of each entry in the Device Driver Table is defined in the following C structure typedef struct rtems_device_driver_entry initialization_entry rtems_device_driver_entry open_entry rtems_device_driver_entry close_entry rtems_device_driver_entry read_entry Chapter 23 Configuring a System 261 rtems_device_driver_entry write_entry rtems_device_driver_entry control_entry rtems_driver_address_table initialization entry is the address of the entry point called by rtems_io_initialize to initialize a device driver and its associated devices open entry is the address of the entry point called by rtems io open close entry is the address of the entry point called by rtems io close read entry is the address of the entry point called by rtems io read write entry is the address of the entry point called by rtems io write control entry is the address of the entry point called by rtems io control Driver entry points configured as NULL will always return a status code of RTEMS SUCCESSFUL No user code will be executed in this situation A typical declaration for a Device Driver Table might appear as follows rtems driver address table Driver table 2 tty initialize tty open tty close major 0 tty read tty write tty control I lp_initialize lp_open lp close major 1 NULL lp_write lp_control
22. 0 if status RTEMS_STATUS_SUCCESSFUL printf rtems task start failed with status of d n status exit 1 status rtems_task_delete SELF should not return printf rtems task delete returned with status of d n status exit 1 rtems_task user_application rtems_task_argument argument 336 RTEMS C User s Guide application specific initialization goes here while 1 1 infinite loop APPLICATION CODE GOES HERE This code will typically include at least one directive which causes the calling task to give up the processor define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER for stdio define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER for time services Bi define CONFIGURE MAXIMUM TASKS 2 define CONFIGURE INIT TASK NAME rtems build name E X A M define CONFIGURE RTEMS INIT TASKS TABLE define CONFIGURE INIT include lt confdefs h gt Chapter 31 Glossary 31 Glossary active aperiodic task application ASR asynchronous 337 A term used to describe an object which has been created by an application A task which must execute only at irregular intervals and has only a soft deadline In this document software which makes use of RTEMS see Asynchronous Signal Routine Not related in order or timing to other occurrences in the system Asynchronous Signal Routine awakened big endian
23. 19 4 6 RATE_MONOTONIC_GET_STATUS Obtain status from a period CALLING SEQUENCE rtems_status_code rtems_rate_monotonic_get_status rtems_id id rtems_rate_monotonic_period_status status 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL period initiated successfully RTEMS INVALID ID invalid rate monotonic period id RTEMS INVALID ADDRESS invalid address of status DESCRIPTION This directive returns status information associated with the rate monotonic period id in the following data structure typedef struct rtems_id owner rtems_rate_monotonic_period_states state rtems_rate_monotonic_period_time_t since_last_period rtems_thread_cpu_usage_t executed_since_last_period rtems rate monotonic period status A configure time option can be used to select whether the time information is given in ticks or seconds and nanoseconds The default is seconds and nanoseconds If the period s state is RATE MONOTONIC INACTIVE both time values will be set to 0 Otherwise both time val ues will contain time information since the last invocation of the rtems rate monotonic period directive More specifically the ticks since last period value contains the elapsed time which has occurred since the last invocation of the rtems rate monotonic period directive and the ticks executed since last period contains how much processor time the owning task has consumed since the invocation of the rtems rate monotonic period di
24. 2005 263 23 11 Multiprocessor Communications Interface Table 265 23 12 Determining Memory Requirements 2005 266 23 13 Sizing the RTEMS RAM Workspace 2005 267 24 Multiprocessing Manager 271 24 TWntrodactiotiss 2s0 ns chan dagen reta RR Rp nre eoe iaa 271 24 2 Background tr pA RU RR i RR EEE naa 271 24 21 NOES coii seceecr RR Rp pete nett RRER PS teens as 211 21 22 Global Objects eu cene nate EP ee A Res 272 24 2 3 Global Object Table 0 0 eee eee 272 24 2 4 Remote Operations cece eee eene 272 24 2 9 IPTOMICS lt 23 Dept x equ Mug aot Ta a ness ARR ERS 219 24 2 0 Multiprocessor Configuration Table 273 24 3 Multiprocessor Communications Interface Layer 274 24 3 1 INDEIALIZATION 223 esayessieee e nn CERES Eme 274 xii RTEMS C User s Guide 24 3 2 GET PACKET iir apinn Y RR uerbi d s RE niii 275 24 3 3 RE TURN PACK ET 2 pte AeERERIP erra bx mS 275 24 3 4 RECEIVE_PACKET 0 c rerik ikai re nn 275 24 3 5 j SEND PACKET RR RISIAELPLDDPSeRE RR Gore 276 24 3 6 Supporting Heterogeneous Environments 276 24 4 OPELALIONS sseie coeds enced e REPSORWR ERG pret ERI E Uns 211 24 4 1 Announcing a Packet 0 00 e eee eee 21 24 5 Directives eco e Re ER Reb IC E EEES EO EEEE A 277 24 5 1 MULTIPROCESSING ANNOUNCE Announce the arrival OL a packet iode i mU ager ka
25. 3 RTEMS Data Types 3 1 Introduction This chapter contains a complete list of the RTEMS primitive data types in alphabetical order This is intended to be an overview and the user is encouraged to look at the ap propriate chapters in the manual for more information about the usage of the various data types 3 2 List of Data Types The following is a complete list of the RTEMS primitive data types in alphabetical order rtems_address is the data type used to manage addresses It is equivalent to a void pointer rtems_asr is the return type for an RTEMS ASR rtems_asr_entry is the address of the entry point to an RTEMS ASR rtems_attribute is the data type used to manage the attributes for RTEMS ob jects It is primarily used as an argument to object create routines to specify char acteristics of the new object rtems_boolean may only take on the values of TRUE and FALSE This type is deprecated Use bool instead rtems_context is the CPU dependent data structure used to manage the integer and system register portion of each task s context rtems_context_fp is the CPU dependent data structure used to manage the floating point portion of each task s context rtems_device_driver is the return type for a RTEMS device driver routine rtems_device_driver_entry is the entry point to a RTEMS device driver routine rtems_device_major_number is the data type used to manage device major num bers rtems_device_minor_n
26. 90 RTEMS C User s Guide 8 4 3 TIMER CANCEL Cancel a timer CALLING SEQUENCE rtems status code rtems timer cancel rtems id id 23 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL timer canceled successfully RTEMS INVALID ID invalid timer id DESCRIPTION This directive cancels the timer id This timer will be reinitiated by the next invocation of rtems timer reset rtems timer fire after or rtems timer fire when with this id NOTES This directive will not cause the running task to be preempted Chapter 8 Timer Manager 91 8 4 4 TIMER_DELETE Delete a timer CALLING SEQUENCE rtems_status_code rtems timer delete rtems id id DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL timer deleted successfully RTEMS_INVALID_ID invalid timer id DESCRIPTION This directive deletes the timer specified by id If the timer is running it is automatically canceled The TMCB for the deleted timer is reclaimed by RTEMS NOTES This directive will not cause the running task to be preempted A timer can be deleted by a task other than the task which created the timer 92 RTEMS C User s Guide 8 4 5 TIMER_FIRE_AFTER Fire timer after interval CALLING SEQUENCE rtems_status_code rtems timer fire after rtems id id rtems interval ticks rtems timer service routine entry routine void user data DIRECTIVE STATUS CODES RTEMS SUCCESSFUL timer initiated successfully RTEMS INVALID ADDRESS routine is NULL RTEMS
27. Creating a BartleEissouussbe Eve She hen Gee tee RE 218 20 3 2 Obtaining Barrier IDs ssseeeseseeeeeeeseee 218 20 3 8 Waiting at a Barrier 0 ccc cece eee eee 218 20 3 4 Releasing a Barrier 0 00 cece cece eens 218 20 3 5 Deleting a Barner oinen erra Ra 219 20 4 Directives cessa e Ree e Dem ERR REG ed a ct 219 20 4 1 BARRIER CREATE Create a barrier 220 20 4 2 BARRIER_IDENT Get ID of a barrier 221 20 4 3 BARRIER DELETE Delete a barrier 222 20 4 4 BARRIER OBTAIN Acquire a barrier 223 20 4 5 BARRIER RELEASE Release a barrier 224 21 Board Support Packages 225 21 1 Introd ctiomn sisse ab eres bI E Renee PRO E A 225 21 2 Reset and Initialization 00 cece eee eee 225 21 2 1 Interrupt Stack Requirements eee eee eee 226 21 2 2 Processors with a Separate Interrupt Stack 226 21 2 3 Processors Without a Separate Interrupt Stack 226 21 3 Device IDTIVETS eaa vi ocesovete beet tn eee DEA ae edis 227 21 3 1 Clock Tick Device Driver 0000 cc cece nee 227 21 4 User Extensions 0 e eens 227 21 5 Multiprocessor Communications Interface MPCI 228 21 5 1 Tightly Coupled Systems 0 00 c cece eee 228 21 5 2 Loosely Coupled Systems 000 e ee eee eee 228 21 5 8 Systems with Mixed Coupling
28. Fs More information regarding the construction and operation of device drivers is provided in the I O Manager chapter 23 9 User Extensions Table The User Extensions Table is used to inform RTEMS of the optional user supplied static extension set This table contains one entry for each possible extension The entries are called at critical times in the life of the system and individual tasks The application may create dynamic extensions in addition to this single static set The format of each entry in the User Extensions Table is defined in the following C structure typedef void rtems_extension typedef rtems_extension rtems_task_create_extension Thread_Control executing Thread_Control created 3 typedef rtems_extension rtems_task_delete_extension Thread_Control executing Thread_Control deleted 3 typedef rtems_extension rtems_task_start_extension Thread_Control executing 262 RTEMS C User s Guide Thread_Control started typedef rtems_extension rtems_task_restart_extension Thread_Control executing Thread_Control restarted typedef rtems_extension rtems_task_switch_extension Thread_Control executing Thread_Control heir typedef rtems_extension rtems_task_begin_extension Thread_Control beginning i typedef rtems extension rtems task exitted extension Thread Control exiting
29. If this field is zero then the User_driver_address_table entry should be NULL When using the rtems confdefs h mechanism for configuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE NUMBER OF INITIAL EXTENSIONS which is set au tomatically by rtems confdefs h based on the size of the User Ex tensions Table is the address of the User Extension Table This table contains the entry points for the static set of optional user extensions If no user extensions are configured then this entry should be NULL The format of this table will be discussed below When using the 254 RTEMS C User s Guide rtems confdefs h mechanism for configuring an RTEMS applica tion the User Extensions Table is named Configuration_Initial_ Extensions and defined in confdefs h It is initialized based on the following macros e CONFIGURE_INITIAL_EXTENSIONS e STACK_CHECKER_EXTENSION The application may configure one or more initial user extension sets by setting the CONFIGURE_INITIAL_EXTENSIONS macro By defining the STACK_CHECKER_EXTENSION macro the task stack bounds check ing user extension set is automatically included in the application User_multiprocessing_table is the address of the Multiprocessor Configuration Table This table contains information needed by RTEMS only when used in a multiprocessor configuration This field must be NULL when RTEMS is used in a single processor configuration
30. The task id is Oxffffffff and its name is INTR This is not actually a task it is the interrupt stack 25 3 4 When a Task Overflows the Stack When the stack bounds checker determines that a stack overflow has occurred it will attempt to print a message using printk identifying the task and then shut the system down If the stack overflow has caused corruption then it is possible that the message can not be printed The following is an example of the output generated Chapter 25 Stack Bounds Checker 281 BLOWN STACK Offending task 0x3eb360 id 0x08010002 name 0x54413120 stack covers range 0x003e5750 0x003e7b57 9224 bytes Damaged pattern begins at 0x003e5758 and is 128 bytes long The above includes the task id and a pointer to the task control block as well as enough information so one can look at the task s stack and see what was happening 25 4 Routines This section details the stack bounds checker s routines A subsection is dedicated to each of routines and describes the calling sequence related constants usage and status codes 282 RTEMS C User s Guide 25 4 1 STACK_CHECKER_IS_BLOWN Has Current Task Blown Its Stack CALLING SEQUENCE bool rtems stack checker is blown void STATUS CODES TRUE Stack is operating within its stack limits FALSE Current stack pointer is outside allocated area DESCRIPTION This method is used to determine if the current stack pointer of the currently executin
31. buffer structure are all range checked and an error is returned if any one is out of its valid range NOTES Years before 1988 are invalid The system date and time are based on the configured tick rate number of microseconds in a tick Setting the time forward may cause a higher priority task blocked waiting on a specific time to be made ready In this case the calling task will be preempted after the next clock tick Re initializing RTEMS causes the system date and time to be reset to an uninitialized state Another call to rtems clock set is required to re initialize the system date and time to application specific specifications Chapter 7 Clock Manager 75 7 4 2 CLOCK_GET Get date and time information CALLING SEQUENCE rtems status code rtems clock get rtems clock get options option void time buffer 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL current time obtained successfully RTEMS NOT DEFINED system date and time is not set RTEMS INVALID ADDRESS time buffer is NULL DESCRIPTION This directive obtains the system date and time If the caller is attempting to obtain the date and time i e option is set to either RTEMS CLOCK GET SECONDS SINCE EPOCH RTEMS CLOCK GET TOD or RTEMS CLOCK GET TIME VALUE and the date and time has not been set with a previous call to rtems clock set then the RTEMS NOT DEFINED status code is returned The caller can always obtain the number of ticks per s
32. rtems task set note sesss 53 rtems task set priority sess 50 rtems task start eee 44 rtems task start extension 21 233 rtems_task_suspend 000 AT rtems_task_switch_extension 21 234 rtems task variable add DT rtems task variable delete 59 rtems task variable get ss 58 rtems task wake after 54 rtems task wake when ss 55 TSM SiC Dead astenia dure EN e E E 21 rtems time of day 16 21 71 rtems timer cancel ess 90 rtems timer create ves o 88 rtems timer delete 2 ase ns 91 rtems timer fire after 92 rtems timer fire when 93 rtems timer ident lvo EL Y ves 89 rtems timer initiate server 94 rtems timer reset eee ees 97 rtems timer server fire after 95 rtems timer server fire when 96 rtems timer service routine 21 86 rtems timer service routine entry 21 350 RTEMS C User s Guide rtems vector number 22 61 U uintli6 E i 2229 9 e vkrerbeiepoxe r ue pes 22 S udnt39 Ee pUPEG eu aAA Ea iE ud 22 uint64 t i 115c e X PR EER POM see aoe eae NG 22 STACK_CHECKER_ON 0 eee eee eee 243 WINS coe deme DOR Iesu ADIRI 22
33. rtems_chain_prepend 00 330 rtems_chain_prepend_unprotected 331 rtems chain tail cians eas base nea ews dees SIT rtems Clock Bet el ces end ee REALE T5 rtems_clock_get_options 19 5 rtems clock get seconds since epoch 78 rtems_clock_get_ticks_per_second 79 rtems_clock_get_ticks_since_boot 80 rtems clock get tod ee tees 76 RTEMS C User s Guide rtems_clock_get_tod_timeval T rtems clock get uptime esee 81 rtems Clock Set sss IG gg RU RES TA rtems_clock_set_nanoseconds_extension 82 rtems Clock ti6k 2 l aas e em REND 83 rtems configuration table 250 rtems context ish e ap Ge dea edad S 19 rtems context fp vcoe e n pen 19 rtems device driver s 19 rtems device driver entry 19 rtems device major number 19 172 rtems device minor number 19 172 rtems double ig n se etr gw x E Ib eR 19 rtems driver address table 260 rtems event receive sess 133 rtems event send eese 192 rtems event Seto dud esati IV aes 19 129 rtems extension esee 19 233 rtems extension create 238 rtems extension delete 240 rtems extension ident 239 rtems extensions table 231 rtems fatal error occur
34. rtems_name name size t Stack size rtems task priority initial priority rtems attribute attribute set rtems task entry entry point rtems mode mode set rtems task argument argument rtems initialization tasks table name is the name of this initialization task 260 RTEMS C User s Guide stack_size is the size of the stack for this initialization task initial_priority is the priority of this initialization task attribute_set is the attribute set used during creation of this initialization task entry point is the address of the entry point of this initialization task mode set is the initial execution mode of this initialization task argument is the initial argument for this initialization task A typical declaration for an Initialization Task Table might appear as follows rtems initialization tasks table Initialization tasks 2 INIT 1 NAME 1024 1 DEFAULT ATTRIBUTES Init 1 DEFAULT MODES 1 Fs INIT 2 NAME 1024 250 FLOATING POINT Init 2 NO_PREEMPT a F 23 8 Driver Address Table The Device Driver Table is used to inform the I O Manager of the set of entry points for each device driver configured in the system The table contains one entry for each device driver required by the application The number of entries is defined in the num ber_of_device_drivers entry in the Configuration Table This table is copied to the Device Drive Table during the IO Manager
35. the results are of reduced value and may even be considered useless or harmful A peripheral used by the application that requires special operation software See also device driver Control software for special peripheral devices used by the applica tion RTEMS provided routines that provide support mechanisms for real time applications The act of loading a task s context onto the CPU and transferring control of the CPU to that task The state entered by a task after it is created and before it has been started A table which contains the entry points for each of the configured device drivers A term used to describe memory which can be accessed at two dif ferent addresses An application that is delivered as a hidden part of a larger system For example the software in a fuel injection control system is an embedded application found in many late model automobiles A buffer provided by the MPCI layer to RTEMS which is used to pass messages between nodes in a multiprocessor system It typically Chapter 31 Glossary 339 contains routing information needed by the MPCI The contents of an envelope are referred to as a packet entry point The address at which a function or task begins to execute In C the entry point of a function is the function s name events A method for task communication and synchronization The direc tives provided by the event manager are used to service events exception A synonym for
36. time in RTEMS e rtems timer service routine is the return type for an RTEMS Timer Service Routine 22 RTEMS C User s Guide rtems_timer_service_routine_entry is the address of the entry point to an RTEMS TSR It is equivalent to the entry point of the function implementing the TSR rtems_vector_number is the data type used to manage and manipulate interrupt vector numbers uint8_t is the C99 data type that corresponds to unsigned eight bit integers This data type is defined by RTEMS in a manner that ensures it is portable across different target processors uint16_t is the C99 data type that corresponds to unsigned sixteen bit integers This data type is defined by RTEMS in a manner that ensures it is portable across different target processors uint32_t is the C99 data type that corresponds to unsigned thirty two bit integers This data type is defined by RTEMS in a manner that ensures it is portable across different target processors uint64_t is the C99 data type that corresponds to unsigned sixty four bit integers This data type is defined by RTEMS in a manner that ensures it is portable across different target processors uintptr_t is the C99 data type that corresponds to the unsigned integer type that is of sufficient size to represent addresses as unsigned integers This data type is defined by RTEMS in a manner that ensures it is portable across different target processors Chapter 4 Initialization Manager 23 4
37. too many regions created RTEMS INVALID SIZE invalid page size DESCRIPTION This directive creates a region from a physically contiguous memory space which starts at starting address and is length bytes long Segments allocated from the region will be a multiple of page size bytes in length The assigned region id is returned in id This region id is used as an argument to other region related directives to access the region For control and maintenance of the region RTEMS allocates and initializes an RNCB from the RNCB free pool Thus memory from the region is not used to store the RNCB However some overhead within the region is required by RTEMS each time a segment is constructed in the region Specifying RTEMS PRIORITY in attribute set causes tasks waiting for a segment to be serviced according to task priority Specifying RTEMS_FIFO in attribute set or selecting RTEMS DEFAULT ATTRIBUTES will cause waiting tasks to be serviced in First In First Out order The starting address parameter must be aligned on a four byte boundary The page size parameter must be a multiple of four greater than or equal to eight NOTES This directive will not cause the calling task to be preempted The following region attribute constants are defined by RTEMS e RTEMS_FIFO tasks wait by FIFO default e RTEMS PRIORITY tasks wait by priority 154 RTEMS C User s Guide 14 4 2 REGION_IDENT Get ID of a region CALLING SEQUENCE
38. 000 319 chain is node null uueeesuss 315 chain is node the first 00e eee 320 chain is node the head 000000 323 chain is node the last susessss 321 chain is node the tail essuuuss 324 chair i6erab s iiiessisc ERE GR RR RE 311 Chain only one nodes oisscer RIED ETE berini 322 Ghaingossscssseme str ark Shere are Pee 309 chare are nodes equal seesssssese 318 Clock urelceIlexs e e Re e seer siee Sites 71 clock get Uptimessi di kassweeed gosh daveibie ite 81 clock set nanoseconds extension 82 clock ticks o2el2lilei Rle Rebel eR AEN 83 close a device essei RPR ES RR ORE ERA 181 communication and synchronization 15 conclude current period 0005 211 condes D 3 nebat uto ends 241 Configuration Table sesssessse 250 351 convert external to internal address 168 convert internal to external address 169 counting semaphores 0 0000e 99 CPU Dependent Information Table 259 create a barBlep 222 lx eR be Ere 220 create a message queue sse 117 create a partition nse cs ainada RR dI 143 create a period sie nel pru RR RARI ERG 207 Greate amp POLE isses mI rU Rn weil Doe sue 165 create 8 Telo lee c dae ic heteER ER RARRON 153 create a semaphore 2c eee eee eee 105 create a tasks daisies pep Te Na 40 Create a Lim
39. 19 4 TntroductOng sisena ea s turre cha t ie icm LO A 195 19 2 Background ecce rete nnd hrec Rege dx aur rac 195 19 2 1 Rate Monotonic Manager Required Support 195 19 2 2 Period Statistics 0 0 ior ee ene eee eee nee 195 19 2 3 Rate Monotonic Manager Definitions 196 19 2 4 Rate Monotonic Scheduling Algorithm 197 19 2 5 Schedulability Analysis sese 198 19 2 5 1 Assumptions 000 cece eee e 198 19 2 5 2 Processor Utilization Rule 0 2200 0 198 19 2 5 3 Processor Utilization Rule Example 198 19 2 5 4 First Deadline Rule sees 199 19 2 5 5 First Deadline Rule Example 199 19 2 5 6 Relaxation of Assumptions 005 200 19 2 5 7 Further Reading 0 e eee eee eee eee 200 19 3 Operations aice e Ree tiron beiee a EE E EEDE RE 201 19 3 1 Creating a Rate Monotonic Period 06 201 19 3 2 Manipulating a Period 0 eee eee eee 201 19 3 8 Obtaining the Status of a Period 005 201 19 3 4 Canceling a Period cece eee eee 202 19 3 5 Deleting a Rate Monotonic Period 005 202 19 3 6 Example8 en RRRRRRRPRUO Ene Y ER 202 19 3 7 Simple Periodic Task 0 0 eee eee eee eee 202 19 3 8 Task with Multiple Periods 0000 e eee 203 TOA JDUuP ctlVeSunoinenen e RUE E E E E mee
40. 2 Real time Application Systems Real time application systems are a special class of computer applications They have a complex set of characteristics that distinguish them from other software problems Gen erally they must adhere to more rigorous requirements The correctness of the system depends not only on the results of computations but also on the time at which the results are produced The most important and complex characteristic of real time application sys tems is that they must receive and respond to a set of external stimuli within rigid and critical time constraints referred to as deadlines Systems can be buried by an avalanche of interdependent asynchronous or cyclical event streams Deadlines can be further characterized as either hard or soft based upon the value of the results when produced after the deadline has passed A deadline is hard if the results have no value or if their use will result in a catastrophic event In contrast results which are produced after a soft deadline may have some value Another distinguishing requirement of real time application systems is the ability to coor dinate or manage a large number of concurrent activities Since software is a synchronous entity this presents special problems One instruction follows another in a repeating syn chronous cycle Even though mechanisms have been developed to allow for the processing of external asynchronous events the software design efforts required to pr
41. 20 posix_api_configuration_table 254 posix initialization threads table 257 R rtems extensions table index 232 rtems addresSg orere eae a e i A 19 rtems_api_configuration_table 254 Items aSf oerte e ERU E 19 137 rtens asr entry ec WEer eR dae 19 rtems attrib te ol ae E VERPVRTE 19 rtems barrier create 220 rtems barrier delete s s 222 rtems barrier ident sss 221 rtems barrier release s 224 rtems barrier wait sss 223 rtems boolean csse 19 rtems bulld 1d reb der re Ries 300 rtems build name 13 292 293 rtems chain append sseesess 328 rtems chain append unprotected 329 rtems chain are nodes equal 318 rtems chain extract esses 925 rtems chain get ug pc p e EG 326 rtems chain has only one node 322 rtems chain head iioouus dee rd ees 316 rtems chain initialize 313 rtems chain initialize empty 314 rtems chain inS ft icil cv 9 TE Pul IA 327 rtems chain is empty see ee 319 rtems chain is first eee 320 rtems chain is head 323 rtems chain is last 321 rtems chain is null node 315 rtems chain is tail 324
42. 2005 229 21 5 4 Heterogeneous Systems 0 0 c eee eee eee eens 229 22 User Extensions Manager 231 221 SIntroductiOl ee a meee eee euni oer e E E EE EE 231 22 2 Backgrounds eror eure PGs ea ee cafe 231 22 2 1 Extension Sets sess 231 22 2 2 TCB Extension Area ccc cece cc eee 232 22 2 9 XUCNSIONS 2cc4ednntaeiereapr aes Prem C eF VT Mee EI Rd 233 22 2 8 TASK CREATE Extension 0000005 233 22 2 8 2 TASK START Extension 00 00 eee ee 233 22 2 8 80 TASK RESTART Extension 000 234 22 2 3 4 TASK DELETE Extension 0005 234 22 2 8 55 TASK SWITCH Extension 000005 234 22 2 8 TASK BEGIN Extension 00 0c cece eee 235 22 2 3 7 TASK_EXITTED Extension 4 235 22 2 8 8 FATAL Error Extension esee 235 22 2 4 Order of Invocation lesse 236 22 3 OPCratiOns eesriie M Ead PR Ir beens tates ade NR eds 236 22 3 1 Creating an Extension Set 0 cece eee eens 236 22 3 2 Obtaining Extension Set IDs 00 000 236 22 3 3 Deleting an Extension Set 0c cee eee eee eee 237 22 4 DireetiveSceseset doscubpt tisesstirtennentbmeeb RE ques areas 237 22 4 1 EXTENSION CREATE Create a extension set 238 22 4 5 EXTENSION IDENT Get ID of a extension set 239 22 4 53 EXTENSION DELETE Delete a extension set 240 23 Configuring a S
43. 28 4 12 Is this Node the Chain Tail 324 28 4 13 Extract a Node ccc ce e 325 28 4 14 Get the First Node 0 cee cee 326 xiv RTEMS C User s Guide 28 4 15 Insert Node cce er tekert TI ds 321 28 4 16 Append a Node 0c cece eect aii 328 28 4 17 Append a Node unprotected eee eee 329 28 4 18 Prepend a Node cece ene eens 330 28 4 19 Prepend a Node unprotected seusuue 331 29 Directive Status Codes 333 30 Example Application 335 SL Glossary eed eb media st cad d Ran et Rd 337 Command and Variable Index 347 Concept INdex ois ceex ues ann ean whale eed cance ees 351 Preface 1 Preface In recent years the cost required to develop a software product has increased significantly while the target hardware costs have decreased Now a larger portion of money is expended in developing using and maintaining software The trend in computing costs is the com plete dominance of software over hardware costs Because of this it is necessary that formal disciplines be established to increase the probability that software is characterized by a high degree of correctness maintainability and portability In addition these disciplines must promote practices that aid in the consistent and orderly development of a software system within schedule and budgetary constraints To be effective the
44. 8 CLOCK GET UPTIME Get the time since boot 8l 7 4 9 CLOCK SET NANOSECONDS EXTENSION Install the nanoseconds since last tick handler suuuuuuue 82 7 4 10 CLOCK TICK Announce a clock tick 83 8 Timer MaiHlager i sees ne ee ERES 85 Bl TnbrOGdWUCblOD escensenlsr aeta dert NO ate nae ed at ede eet bet ets 85 8 2 Backerouiid ssi resis er borea a Lae SAT x RII 85 8 2 1 Required Support ssssssssesseesee eee eens 85 82 2 TIME Se errioa EeR er ER dG PUR CS CS 85 8 23 Timer Serverucc c ebbe teer heub edere te 85 8 2 4 Timer Service Routines 0 ccc ccc cece eee 86 8 3 Operatlong H e bene oh GO EE RU EGRE NU e CCP EK RRRen 86 8 3 1 Creating a Timer aereo der kernels 86 8 3 2 Obtaming Timer IDs 0 RR RE ERIT ex 86 8 3 3 Initiating an Interval Timer ssseseeeeeesess 86 8 3 4 Initiating a Time of Day Timer seeessssse 86 8 3 9 Canceling Timer etr oue Re DRE 87 9 0 Resetting Timer oi seats e dL iesu id de onreca eut in Rhea RB 87 8 3 7 Initiating the Timer Server 0 0 c eee eee eee 87 8 3 8 Deleting a Timer 0 cece nes 87 SA iDireetivesucasesesexeekreta e e A bx aano ar b RE Sa uelis 87 8 4 1 TIMER CREATE Create a timer 0 0000 ee 88 8 4 2 TIMER IDENT Get ID of a timer 89 8 4 8 TIMER CANCEL Cancel a timer 90 8 4 4 TIMER DELETE Delete a
45. API condition variables that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_POSIX_KEYS is the maximum number of POSIX API keys that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_POSIX_TIMERS is the maximum number of POSIX API timers that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS is the maximum number of POSIX API queued signals that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES is the maximum number of POSIX API message queues that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_POSIX_SEMAPHORES is the maximum number of POSIX API semaphores that can be concurrently active The default is 0 23 2 9 POSIX Initialization Threads Table Configuration The rtems confdefs h configuration system can automatically generate a POSIX Initial ization Threads Table named POSIX Initialization threads with a single entry The following parameters control the generation of that table CONFIGURE POSIX INIT THREAD TABLE is defined if the user wishes to use a POSIX API Initialization Threads Table The application may choose to use the initializa tion tasks or threads table from another API By default this field is not defined as the user MUST select their own API for initialization tasks Chapter 23 Configuring a System 249 CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE is defined if the user wishes to de fine the
46. BASE FILESYSTEM is defined if the application wishes to use the full functionality IMFS By default the mini I MFS is used The miniIMFS is a minimal functionality subset of the In Memory FileSystem IMFS The miniIMFS Chapter 23 Configuring a System 243 is comparable in functionality to the pseudo filesystem name space provided before RTEMS release 4 5 0 The miniIMFS supports only directories and device nodes and is smaller in executable code size than the full IMFS STACK_CHECKER_ON is defined when the application wishes to enable run time stack bounds checking This increases the time required to create tasks as well as adding overhead to each context switch By default this is not defined and thus stack checking is disabled 23 2 2 Basic System Information This section defines the general system configuration parameters supported by rtems confdefs h CONFIGURE HAS OWN CONFIGURATION TABLE should only be defined if the applica tion is providing their own complete set of configuration tables CONFIGURE EXECUTIVE RAM WORK AREA is the base address of the RTEMS RAM Workspace By default this value is NULL indicating that the BSP is to determine the location of the RTEMS RAM Workspace CONFIGURE MICROSECONDS PER TICK is the length of time between clock ticks By default this is set to 10000 microseconds CONFIGURE TICKS PER TIMESLICE is the length of the timeslice quantum in ticks for each task By default this is 50
47. C 408 aed 289 2 1 Introduction sn est eriie e qa paa bre ET RP delevi eyes 289 21 2 Backeroud sgcameceetra ia eese dated ain A E EN dened e esti 289 212 4 APISzi Rete c E ERR npa 289 2022 Object Classes ncsaitdadenseneetuaes edocet Oca eh bone 289 21 2 3 Object Names x obere ud ed ect paaa a e i eds 290 27 3 Operatiols creen epp SERIPLUCERI ORG ER GA RH RETE ES 290 27 3 1 Decomposing and Recomposing an Object Id 290 27 32 Printing an Object Id case ads rere eare teh eis 291 2E Directives re io cscineienkiue psp neri ru E Ret E Rates e dieses 291 xii 27 4 1 BUILD NAME Build object name from characters 292 27 4 OBJECT GET CLASSIC NAME Lookup name from id err CL ENNMIPHT 293 27 4 5 OBJECT GET NAME Obtain object name as string 294 27 4 4 OBJECT SET NAME Set object name 295 27 4 5 OBJECT ID GET API Obtain API from Id 296 27 46 OBJECT ID GET CLASS Obtain Class from Id 297 27 4 7 OBJECT_ID_GET_NODE Obtain Node from Id 298 27 4 8 OBJECT ID GET INDEX Obtain Index from Id 299 27 4 9 BUILD ID Build Object Id From Components 300 27 4 10 OBJECT ID API MINIMUM Obtain Minimum API pole LCD ees 301 27 4 11 OBJECT ID API MAXIMUM Obtain Maximum API Malueiercmcsederutbl tun rU ML pue UAE cue ge 302 27 412 OBJECT API MINIMUM CLASS Obtain Minimum Class Value scere ach an ic evar mnoetieiy sis 303 27 413 OBJECT API MAXIMUM CL
48. Data Structures page 71 Obviously the directives which use intervals or wall time cannot operate without some ex ternal mechanism which provides a periodic clock tick This clock tick is typically provided by a real time clock or counter timer device 2 5 Memory Management RTEMS memory management facilities can be grouped into two classes dynamic memory allocation and address translation Dynamic memory allocation is required by applications whose memory requirements vary through the application s course of execution Address translation is needed by applications which share memory with another CPU or an intelli gent Input Output processor The following RTEMS managers provide facilities to manage memory e Region e Partition e Dual Ported Memory RT EMS memory management features allow an application to create simple memory pools of fixed size buffers and or more complex memory pools of variable size segments The partition manager provides directives to manage and maintain pools of fixed size entities such as resource control blocks Alternatively the region manager provides a more general purpose memory allocation scheme that supports variable size blocks of memory which are dynamically obtained and freed by the application The dual ported memory manager Chapter 2 Key Concepts 17 provides executive support for address translation between internal and external dual ported RAM address space Chapter 3 RTEMS Data Types 19
49. Deleting a Semaphore 0 eee eee es 103 QA Directives es seco cee teens EERERF REQUE us e ey ee SEE DO 104 9 4 1 SEMAPHORE CREATE Create a semaphore 105 9 4 2 SEMAPHORE IDENT Get ID of a semaphore 107 9 4 3 SEMAPHORE DELETE Delete a semaphore 108 9 4 5 SEMAPHORE_OBTAIN Acquire a semaphore 109 9 4 5 SEMAPHORE RELEASE Release a semaphore T 9 4 5 SEMAPHORE FLUSH Unblock all tasks waiting on a semapliore 2st sem REA UD gei prese RR Aa anes 112 10 Message Manager ssuese 113 10 4 Introduction erse rnanan rtt hr ED rat eene le hh a eee 113 10 2 Background ipi RUE eil E EPDPEER T EIER ERE L5 10 21 Messages cs scien Rx nce pite aes ln sich dened alan asses 113 10 2 2 Message Queues 2 0 c cece eee ee 113 10 2 3 Building a Message Queue Attribute Set 113 10 2 4 Building a MESSAGE_QUEUE_RECEIVE Option Set 114 10 3 Operations sm 9e ES epe RE R EE ES 114 10 3 1 Creating a Message Queue ssessessseeeseesee 114 10 3 2 Obtaining Message Queue IDs 0 0002s 114 10 8 8 Receiving a Message cece cece eee 115 10 3 4 Sending a Message ccc eee eee eee eee ee 115 10 3 5 Broadcasting a Message 0 ccc eee e eee 115 10 3 6 Deleting a Message Queue 0 0 e cece eee eee 115 10 4 Directivescesosee ek eR RE 4e bees tenes seaeger ONERE TES 116 10 4 1 MESSAGE QUEUE CREATE Crea
50. INVALID ID invalid timer id RTEMS INVALID NUMBER invalid interval DESCRIPTION This directive initiates the timer specified by id If the timer is running it is automatically canceled before being initiated The timer is scheduled to fire after an interval ticks clock ticks has passed When the timer fires the timer service routine routine will be invoked with the argument user data NOTES This directive will not cause the running task to be preempted Chapter 8 Timer Manager 93 8 4 6 TIMER FIRE WHEN Fire timer when specified CALLING SEQUENCE rtems status code rtems timer fire when rtems id id rtems time of day wall time rtems timer service routine entry routine void user data DIRECTIVE STATUS CODES RTEMS SUCCESSFUL timer initiated successfully RTEMS INVALID ADDRESS routine is NULL RTEMS INVALID ADDRESS wall time is NULL RTEMS INVALID ID invalid timer id RTEMS NOT DEFINED system date and time is not set RTEMS INVALID CLOCK invalid time of day DESCRIPTION This directive initiates the timer specified by id If the timer is running it is automatically canceled before being initiated The timer is scheduled to fire at the time of day specified by wall time When the timer fires the timer service routine routine will be invoked with the argument user data NOTES This directive will not cause the running task to be preempted 94 RTEMS C User s Guide 8 4 7
51. If the MPCI layer cannot be success fully initialized the fatal error manager should be invoked by this routine One of the primary functions of the MPCI layer is to provide the executive with packet buffers The INITIALIZATION routine must create and initialize a pool of packet buffers There must be enough packet buffers so RTEMS can obtain one whenever needed 24 3 2 GET PACKET The GET PACKET component of the user provided MPCI layer is called when RTEMS must obtain a packet buffer to send or broadcast a message This component should be adhere to the following prototype rtems_mpci_entry user_mpci_get_packet rtems_packet_prefix packet 25 where packet is the address of a pointer to a packet This routine always succeeds and upon return packet will contain the address of a packet If for any reason a packet cannot be successfully obtained then the fatal error manager should be invoked RTEMS has been optimized to avoid the need for obtaining a packet each time a message is sent or broadcast For example RTEMS sends response messages RR back to the originator in the same packet in which the request message RQ arrived 24 3 3 RETURN_PACKET The RETURN PACKET component of the user provided MPCI layer is called when RTEMS needs to release a packet to the free packet buffer pool This component should be adhere to the following prototype rtems mpci entry user mpci return packet rtems packet prefix packet wher
52. Initialization Manager 4 1 Introduction The Initialization Manager is responsible for initiating and shutting down RTEMS Ini tiating RTEMS involves creating and starting all configured initialization tasks and for invoking the initialization routine for each user supplied device driver In a multiprocessor configuration this manager also initializes the interprocessor communications layer The directives provided by the Initialization Manager are e rtems_initialize_data_structures Initialize RTEMS Data Structures e rtems_initialize_before_drivers Perform Initialization Before Device Drivers e rtems_initialize_device_drivers Initialize Device Drivers e rtems_initialize_start_multitasking Complete Initialization and Start Mul titasking e rtems_shutdown_executive Shutdown RTEMS 4 2 Background 4 2 1 Initialization Tasks Initialization task s are the mechanism by which RTEMS transfers initial control to the user s application Initialization tasks differ from other application tasks in that they are defined in the User Initialization Tasks Table and automatically created and started by RTEMS as part of its initialization sequence Since the initialization tasks are scheduled using the same algorithm as all other RTEMS tasks they must be configured at a priority and mode which will ensure that they will complete execution before other application tasks execute Although there is no upper limit on the number of initialization t
53. MAXIMUM NODES If not defined by the application then the CONFIGURE MP MAXIMUM NODES macro defaults to the value 2 maximum global objects is the maximum number of global objects which can exist at any given moment in the entire system If this parameter is not the same on all nodes in the system then a fatal error is generated to inform the user that the system is inconsistent When using the Chapter 23 Configuring a System 265 maximum proxies rtems confdefs h mechanism for configuring an RTEMS applica tion the value for this field corresponds to the setting of the macro CONFIGURE MP MAXIMUM GLOBAL OBJECTS If not defined by the ap plication then the CONFIGURE MP MAXIMUM GLOBAL OBJECTS macro defaults to the value 32 is the maximum number of proxies which can exist at any given mo ment on this particular node A proxy is a substitute task control block which represent a task residing on a remote node when that task blocks on a remote object Proxies are used in situations in which delayed interaction is required with a remote node When using the rtems confdefs h mechanism for configuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE MP MAXIMUM PROXIES If not defined by the ap plication then the CONFIGURE MP MAXIMUM PROXIES macro defaults to the value 32 extra mpci receive server stack User mpci table is the extra stack space allocated for the RTEMS MPCI
54. Many definitions of a task have been proposed in computer literature Unfortunately none of these definitions encompasses all facets of the concept in a manner which is operating system independent Several of the more common definitions are provided to enable each user to select a definition which best matches their own experience and understanding of the task concept e a dispatchable unit e an entity to which the processor is allocated e an atomic unit of a real time multiprocessor system e single threads of execution which concurrently compete for resources e a sequence of closely related computations which can execute concurrently with other computational sequences 32 RTEMS C User s Guide From RTEMS perspective a task is the smallest thread of execution which can compete on its own for system resources A task is manifested by the existence of a task control block TCB 5 2 2 Task Control Block The Task Control Block TCB is an RTEMS defined data structure which contains all the information that is pertinent to the execution of a task During system initialization RTEMS reserves a TCB for each task configured A TCB is allocated upon creation of the task and is returned to the TCB free list upon deletion of the task The TCB s elements are modified as a result of system calls made by the application in response to external and internal stimuli TCBs are the only RTEMS internal data structure that can be accessed
55. RTEMS Each language inter face provided by RTEMS includes a file containing the standard set of constants data types and structure definitions which can be incorporated into the user appli cation e A number of type definitions are provided by RTEMS and can be found in rtems h e The characters 0x preceding a number indicates that the number is in hexadecimal format Any other numbers are assumed to be in decimal format 1 11 Manual Organization This first chapter has presented the introductory and background material for the RTEMS executive The remaining chapters of this manual present a detailed description of RTEMS and the environment including run time behavior it creates for the user A chapter is dedicated to each manager and provides a detailed discussion of each RTEMS manager and the directives which it provides The presentation format for each directive includes the following sections 10 RTEMS C User s Guide Calling sequence Directive status codes e Description e Notes The following provides an overview of the remainder of this manual Chapter 2 Key Concepts presents an introduction to the ideas which are com mon across multiple RTEMS managers Chapter 3 RTEMS Data Types describes the fundamental data types shared by the services in the RTEMS Classic API Chapter 4 Initialization Manager describes the functionality and directives pro vided by the Initialization Manager Chapter 5 Task Manage
56. RTEMS actions when a fatal error occurs may be found Section 17 3 1 Fatal Error Manager Announcing a Fatal Error page 185 4 3 Operations 4 3 1 Initializing RTEMS The Initialization Manager directives are called by the Board Support Package framework as part of its initialization sequence RTEMS assumes that the Board Support Package successfully completed its initialization activities These directives initialize RTEMS by performing the following actions e Initializing internal RTEMS variables Allocating system resources e Creating and starting the Idle Task e Initialize all device drivers e Creating and starting the user initialization task s and Chapter 4 Initialization Manager 25 e Initiating multitasking The initialization directives MUST be called in the proper sequence before any blocking directives may be used The services in this manager should be invoked just once per application and in precisely the following order e rtems_initialize_data_structures e rtems_initialize_before_drivers e rtems_initialize_device_drivers e rtems_initialize_start_multitasking It is recommended that the Board Support Package use the provided framework which will invoke these services as part of the executing the function boot_card in the file c src lib libbsp shared bootcard c This framework will also assist in allocating memory to the RTEMS Workspace and C Program Heap and initializing the C Library The effect of calli
57. STACK ALLOCATOR may point to a user provided routine to allocate task stacks The default value for this field is NULL which indicates that task stacks will be allocated from the RTEMS Workspace CONFIGURE TASK STACK DEALLOCATOR may point to a user provided routine to free task stacks The default value for this field is NULL which indicates that task stacks will be allocated from the RTEMS Workspace 244 RTEMS C User s Guide e CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY indicates whether RTEMS should zero the RTEMS Workspace and C Program Heap as part of its initialization If set to TRUE the Workspace is zeroed Otherwise it is not Unless overridden by the BSP the default value for this field is FALSE CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE is a helper macro which is used to as sist in computing the total amount of memory required for message buffers Each message queue will have its own configuration with maximum message size and maximum number of pending messages The interface for this macro is as follows CONFIGURE MESSAGE BUFFERS FOR QUEUE max messages size per Where max messages is the maximum number of pending messages and size per is the size in bytes of the user message CONFIGURE MESSAGE BUFFER MEMORY is set to the number of bytes the application requires to be reserved for pending message queue buffers This value should include memory for all buffers across all APIs The default value is 0 The following illustrat
58. The sixteen notepad locations can be accessed using the constants RTEMS_NOTEPAD_O through RTEMS_NOTEPAD_15 Getting a note of a global task which does not reside on the local node will generate a request to the remote node to obtain the notepad entry of the specified task Chapter 5 Task Manager 53 5 4 13 TASK_SET_NOTE Set task notepad entry CALLING SEQUENCE rtems_status_code rtems_task_set_note rtems_id id uint32_t notepad uint32_t note 23 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL task s note set successfully RTEMS INVALID ID invalid task id RTEMS INVALID NUMBER invalid notepad location DESCRIPTION This directive sets the notepad entry for the task specified by id to the value note NOTES If id is set to RTEMS SELF the calling task accesses its own notepad locations This directive will not cause the running task to be preempted The sixteen notepad locations can be accessed using the constants RTEMS NOTEPAD O through RTEMS NOTEPAD 15 Setting a notepad location of a global task which does not reside on the local node will generate a request to the remote node to set the specified notepad entry 54 RTEMS C User s Guide 5 4 14 TASK WAKE AFTER Wake up after interval CALLING SEQUENCE rtems status code rtems task wake after rtems interval ticks 23 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL always successful DESCRIPTION This directive blocks the calling task for the specified number o
59. This section defines the Classic API related system configuration parameters supported by rtems confdefs h Chapter 23 Configuring a System 247 CONFIGURE_MAXIMUM_TASKS is the maximum number of Classic API tasks that can be concurrently active The default for this field is 0 CONFIGURE_DISABLE_CLASSIC_NOTEPADS should be defined if the user does not want to have support for Classic API Notepads in their application By default this is not defined and Classic API Notepads are supported CONFIGURE_MAXIMUM_TIMERS is the maximum number of Classic API timers that can be concurrently active The default for this field is 0 CONFIGURE_MAXIMUM_SEMAPHORES is the maximum number of Classic API semaphores that can be concurrently active The default for this field is 0 CONFIGURE_MAXIMUM_MESSAGE_QUEUES is the maximum number of Classic API mes sage queues that can be concurrently active The default for this field is 0 CONFIGURE_MAXIMUM_PARTITIONS is the maximum number of Classic API partitions that can be concurrently active The default for this field is 0 CONFIGURE_MAXIMUM_REGIONS is the maximum number of Classic API regions that can be concurrently active The default for this field is 0 CONFIGURE_MAXIMUM_PORTS is the maximum number of Classic API ports that can be concurrently active The default for this field is 0 CONFIGURE_MAXIMUM_PERIODS is the maximum number of Classic API rate mono tonic periods that can be concurrently active The
60. a Timer The rtems_timer_reset directive is used to restore an interval timer initiated by a pre vious invocation of rtems_timer_fire_after or rtems_timer_server_fire_after to its original interval length If the timer has not been used or the last usage of this timer was by the rtems_timer_fire_when or rtems_timer_server_fire_when directive then an error is returned The timer service routine is not changed or fired by this directive 8 3 7 Initiating the Timer Server The rtems_timer_initiate_server directive is used to allocate and start the execution of the Timer Server task The application can specify both the stack size and attributes of the Timer Server The Timer Server executes at a priority higher than any application task and thus the user can expect to be preempted as the result of executing the rtems_timer_ initiate_server directive 8 3 8 Deleting a Timer The rtems_timer_delete directive is used to delete a timer If the timer is running and has not expired the timer is automatically canceled The timer s control block is returned to the TMCB free list when it is deleted A timer can be deleted by a task other than the task which created the timer Any subsequent references to the timer s name and ID are invalid 8 4 Directives This section details the timer manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status cod
61. aas Sone anaes 206 19 4 4 RATE MONOTONIC CREATE Create a rate monotonic Denod c idebetoetbunm Goa ese EUER VR Rp EE Pp E 207 19 4 2 RATE MONOTONIC IDENT Get ID of a period 208 19 4 3 RATE MONOTONIC CANCEL Cancel a period 209 19 4 4 RATE MONOTONIC DELETE Delete a rate monotonic POTION sisesselcercke ene DPPRREFOEERAT ua race wes Rare RUD ntes 210 19 4 5 RATE MONOTONIC PERIOD Conclude current Start next period iui ives licei Va under erred a er on P Rod 211 19 46 RATE MONOTONIC GET STATUS Obtain status from ax Derlodzsa inel icon beca tended D E eyes 2 aceon de 212 19 4 7 RATE MONOTONIC GET STATISTICS Obtain statistics from a period 0 cece su sori rieta eens 213 19 4 8 RATE MONOTONIC RESET STATISTICS Reset statistics for a period cece cee eee ee 214 19 4 9 RATE MONOTONIC RESET ALL STATISTICS Reset statistics for all periods 0 eee eee eee eee 215 19 4 10 RATE MONOTONIC REPORT STATISTICS Print period statistics report 0 00 eee eee eens 216 x RTEMS C User s Guide 20 Barrier Manager LL 217 20 1 JT troduGLiOTi s esueor don est e Gate R sdentied e Ses Sui S 217 20 2 Backpround s24acsud ose repetens ba pacer e doe gto iate E baie 21 20 2 1 Automatic Versus Manual Barriers 217 20 2 2 Building a Barrier Attribute Set 2 00 21 20 3 Operations kel eR RPSL EE OH RR RE REEF 218 20 3 1
62. an RR is generated on a destination node e a global object is created e a global object is deleted e a local task blocked on a remote object is deleted e during system initialization to check for system consistency If the target hardware supports it the arrival of a packet at a node may generate an interrupt Otherwise the real time clock ISR can check for the arrival of a packet In any case the rtems multiprocessing announce directive must be called to announce the arrival of a packet After exiting the ISR control will be passed to the Multiprocessing Server to process the packet The Multiprocessing Server will call the get packet entry to obtain a packet buffer and the receive entry entry to copy the message into the buffer obtained 24 3 1 INITIALIZATION The INITIALIZATION component of the user provided MPCI layer is called as part of the rtems initialize executive directive to initialize the MPCI layer and associated hardware It is invoked immediately after all of the device drivers have been initialized This component should be adhere to the following prototype Chapter 24 Multiprocessing Manager 275 rtems_mpci_entry user_mpci_initialization rtems_configuration_table configuration where configuration is the address of the user s Configuration Table Operations on global objects cannot be performed until this component is invoked The INITIALIZATION com ponent is invoked only once in the life of any system
63. array of rtems_ driver_address_table entries named Device_drivers By default this is not defined indicating the rtems confdefs h is providing the device driver table CONFIGURE_MAXIMUM_DRIVERS is defined as the number of device drivers per node By default this is set to 10 CONFIGURE_MAXIMUM_DEVICES is defined to the number of individual devices that may be registered in the system By default this is set to 20 CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER is defined if the application wishes to include the Console Device Driver This device driver is responsible for providing standard input and output using dev console By default this is not defined CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER is defined if the application wishes to include the Clock Device Driver This device driver is responsible for providing a regular interrupt which invokes the rtems_clock_tick directive By default this is not defined CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER is defined if the application wishes to include the Timer Driver This device driver is used to benchmark execution times by the RTEMS Timing Test Suites By default this is not defined CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER is defined when the ap plication does NOT want the Clock Device Driver and is NOT using the Timer Driver The inclusion or exclusion of the Clock Driver must be explicit in typical user applications This is intended to prevent the common user error of using the Hel
64. be concurrently pending in the system When using the rtems confdefs h mech anism for configuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE MAXIMUM POSIX QUEUED SIGNALS If not defined by the application then the CONFIGURE MAXIMUM POSIX QUEUED SIGNALS macro defaults to 0 number of initialization threads is the number of initialization threads configured At least one initialization threads must be configured When using the rtems confdefs h mechanism for configuring an RTEMS appli cation the user must define the CONFIGURE POSIX INIT THREAD TABLE to indicate that there is one or more POSIX initialization thread If the application only has one POSIX initialization thread then the automatically generated POSIX Initialization Thread Ta ble will be sufficient The following macros correspond to the single initialization task Chapter 23 Configuring a System 259 e CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT is the entry point of the thread If this macro is not defined by the ap plication then this defaults to the C routine POSIX_Init e CONFIGURE_POSIX_INIT_TASK_STACK_SIZE is the stack size of the single initialization thread If this macro is not defined by the application then this defaults to twice the configured minimum stack size User initialization threads table is the address of the Initialization Threads Table This table con tains the information needed to
65. be used in the proper sequence and invokved only once in the life of an application This directive must be invoked with interrupts disabled Interrupts should be disabled as early as possible in the initialization sequence and remain disabled until the first context switch Chapter 4 Initialization Manager 29 4 4 4 INITIALIZE_START_MULTITASKING Complete Initialization and Start Multitasking CALLING SEQUENCE void rtems initialize start multitasking void DIRECTIVE STATUS CODES NONE DESCRIPTION This directive is called after the other Initialization Manager directives have successfully completed This directive initiates multitasking and performs a context switch to the first user application task and enables interrupts as a side effect of that context switch NOTES This directive DOES NOT RETURN to the caller until the rtems shutdown executive is invoked This directive causes all nodes in the system to verify that certain configuration parameters are the same as those of the local node If an inconsistency is detected then a fatal error is generated 30 RTEMS C User s Guide 4 4 5 SHUTDOWN EXECUTIVE Shutdown RTEMS CALLING SEQUENCE void rtems shutdown executive uint32 t result 25 DIRECTIVE STATUS CODES NONE DESCRIPTION This directive is called when the application wishes to shutdown RTEMS and return control to the board support package The board support package resumes execution at the code im
66. bit mapped block blocked broadcast BSP Similar to a hardware interrupt except that it is associated with a task and is run in the context of a task The directives provided by the signal manager are used to service signals A term used to describe a task that has been unblocked and may be scheduled to the CPU A data representation scheme in which the bytes composing a numeric value are arranged such that the most significant byte is at the lowest address A data encoding scheme in which each bit in a variable is used to represent something different This makes for compact data repre sentation A physically contiguous area of memory The task state entered by a task which has been previously started and cannot continue execution until the reason for waiting has been satisfied To simultaneously send a message to a logical set of destinations see Board Support Package Board Support Package buffer calling convention A collection of device initialization and control routines specific to a particular type of board or collection of boards A fixed length block of memory allocated from a partition The processor and compiler dependent rules which define the mecha nism used to invoke subroutines in a high level language These rules define the passing of arguments the call and return mechanism and the register set which must be preserved Central Processing Unit chain This term is equivalent to the ter
67. block of objects allocated Here is an example of using rtems_resource_unlimited define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited 5 The user is cautioned that future versions of RTEMS may not have the same memory requirements per object Although the value calculated is suficient for a particular target processor and release of RTEMS memory usage is subject to change across versions and target processors To avoid problems the user should accurately specify each configuration parameter and allow lt rtems confdefs h gt to calculate the memory requirements The memory requirements are likely to change each time one of the following events occurs e aconfiguration parameter is modified e task or interrupt stack requirements change e task floating point attribute is altered e RTEMS is upgraded or the target processor is changed Chapter 23 Configuring a System 269 Failure to provide enough space in the RTEMS RAM Workspace will result in the rtems_fatal_error_occurred directive being invoked with the appropriate error code Chapter 24 Multiprocessing Manager 271 24 Multiprocessing Manager 24 1 Introduction In multiprocessor real time systems new requirements such as sharing data and global resources between processors are introduced This requires an efficient and reliable com munications vehicle which allows all processors to communicate with each other as necessary In addition the ramifications of multiple p
68. by other tasks including those which have not added the variable to their set and are thus accessing the variable as a common location shared among tasks can not be affected by a task once it has added a variable to its local set Changes made to the variable by other tasks will not affect the value seen by a task which has added the variable to its private set This feature can be used when a routine is to be spawned repeatedly as several independent tasks Although each task will have its own stack and thus separate stack variables they will all share the same static and global variables To make a variable not shareable i e a global variable that is specific to a single task the tasks can call rtems_task_variable_ add to make a separate copy of the variable for each task but all at the same physical address Task variables increase the context switch time to and from the tasks that own them so it is desirable to minimize the number of task variables One efficient method is to have a single task variable that is a pointer to a dynamically allocated structure containing the task s private global data A critical point with per task variables is that each task must separately request that the same global variable is per task private 5 2 9 Building a Task Attribute Set In general an attribute set is built by a bitwise OR of the desired components The set of valid task attribute components is listed below e RTEMS_NO_FLOATING_P
69. calling task to be preempted This is dependent on the device driver being invoked Chapter 17 Fatal Error Manager 185 17 Fatal Error Manager 17 1 Introduction The fatal error manager processes all fatal or irrecoverable errors The directive provided by the fatal error manager is e rtems_fatal_error_occurred Invoke the fatal error handler 17 2 Background The fatal error manager is called upon detection of an irrecoverable error condition by either RTEMS or the application software Fatal errors can be detected from three sources e the executive RTEMS e user system code e user application code RTEMS automatically invokes the fatal error manager upon detection of an error it considers to be fatal Similarly the user should invoke the fatal error manager upon detection of a fatal error Each status or dynamic user extension set may include a fatal error handler The fatal error handler in the static extension set can be used to provide access to debuggers and monitors which may be present on the target hardware If any user supplied fatal error handlers are installed the fatal error manager will invoke them If no user handlers are configured or if all the user handler return control to the fatal error manager then the RTEMS default fatal error handler is invoked If the default fatal error handler is invoked then the system state is marked as failed Although the precise behavior of the default fatal error handler is
70. clock ticks it has executed is incremented While the task is executing this number is incremented on each clock tick Otherwise if a task begins and completes execution between successive clock ticks there would be no way to tell that it executed at all Another thing to keep in mind when looking at idle time is that many systems especially during debug have a task providing some type of debug interface It is usually fine to think of the total idle time as being the sum of the IDLE task and a debug task that will not be included in a production build of an application 26 3 2 Reset CPU Usage Statistics Invoking the rtems_cpu_usage_reset routine resets the CPU usage statistics for all tasks in the system 26 4 Directives This section details the CPU usage statistics manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes Chapter 26 CPU Usage Statistics 287 26 4 1 cpu_usage_report Report CPU Usage Statistics CALLING SEQUENCE void rtems_cpu_usage_report void STATUS CODES NONE DESCRIPTION This routine prints out a table detailing the CPU usage statistics for all tasks in the system NOTES The table is printed using the printk routine 288 RTEMS C User s Guide 26 4 2 cpu_usage_reset Reset CPU Usage Statistics CALLING SEQUENCE void rtems_cpu_usage_reset void STATUS CODES NONE DES
71. code These critical features are essential in order for data to be shared between processors However these drawbacks do have workarounds which are sometimes awkward and defeat the intent of software maintainability and portability goals Another conclusion drawn from the analysis was that the run time executives being de livered with the Ada compilers were too slow and inefficient to be used in modern missile systems A run time executive is the core part of the run time system code or operat ing system code that controls task scheduling input output management and memory management Traditionally whenever efficient executive also known as kernel code was required by the application the user developed in house software This software was usually written in assembly language for optimization Because of this shortcoming in the Ada programming language software developers in research and development and contractors for project managed systems are mandated by technology to purchase and utilize off the shelf third party kernel code The contractor and eventually the Government must pay a licensing fee for every copy of the kernel code used in an embedded system The main drawback to this development environment is that the Government does not own nor has the right to modify code contained within the kernel V amp V techniques in this situation are more difficult than if the complete source code were available Responsibility for system f
72. confdefs h file ensures that at least one application tasks or thread is configured and that at least one of the initialization task thread tables is configured The rtems confdefs h file estimates the amount of memory required for the RTEMS Executive Workspace This estimate is only as accurate as the information given to 242 RTEMS C User s Guide rtems confdefs h and may be either too high or too low for a variety of reasons Some of the reasons that rtems confdefs h may reserve too much memory for RTEMS are e All tasks threads are assumed to be floating point Conversely there are many more reasons the resource estimate could be too low e Task thread stacks greater than minimum size must be accounted for explicitly by developer e Memory for messages is not included e Device driver requirements are not included e Network stack requirements are not included e Requirements for add on libraries are not included In general rtems confdefs h is very accurate when given enough information However it is quite easy to use a library and not account for its resources The following subsection list all of the constants which can be set by the user 23 2 1 Library Support Definitions This section defines the file system and IO library related configuration parameters sup ported by rtems confdefs h e CONFIGURE MALLOC STATISTICS is defined when the application wishes to enable the gathering of more detailed statistics on
73. consequently is the same on every node Since each node must maintain an identical copy of the global object table the maximum number of entries in each copy of the table must be the same The maximum number of entries in each copy is determined by the maximum global objects parameter in the Multi processor Configuration Table This parameter as well as the maximum nodes parameter is required to be the same on all nodes To maintain consistency among the table copies every node in the system must be informed of the creation or deletion of a global object 24 2 4 Remote Operations When an application performs an operation on a remote global object RTEMS must gener ate a Remote Request RQ message and send it to the appropriate node After completing the requested operation the remote node will build a Remote Response RR message and send it to the originating node Messages generated as a side effect of a directive such as deleting a global task are known as Remote Processes RP and do not require the receiving node to respond Other than taking slightly longer to execute directives on remote objects the application is unaware of the location of the objects it acts upon The exact amount of overhead required for a remote operation is dependent on the media connecting the nodes and to a lesser degree on the efficiency of the user provided MPCI routines The following shows the typical transaction sequence during a remote applicati
74. controllers These controllers typically utilize the DPMA for high performance data transfers 15 3 Operations 15 3 1 Creating a Port The rtems_port_create directive creates a port into a DPMA with the user defined name The user specifies the association between internal and external representations for the port being created RTEMS allocates a Dual Ported Memory Control Block DPCB from the DPCB free list to maintain the newly created DPMA RTEMS also generates a unique dual ported memory port ID which is returned to the calling task RTEMS does not initialize the dual ported memory area or access any memory within it 15 3 2 Obtaining Port IDs When a port is created RTEMS generates a unique port ID and assigns it to the created port until it is deleted The port ID may be obtained by either of two methods First as the result of an invocation of the rtems_port_create directive the task ID is stored in a user provided location Second the port ID may be obtained later using the rtems_port_ident directive The port ID is used by other dual ported memory manager directives to access this port 164 RTEMS C User s Guide 15 3 3 Converting an Address The rtems_port_external_to_internal directive is used to convert an address from ex ternal to internal representation for the specified port The rtems_port_internal_to_ external directive is used to convert an address from internal to external representation for the specified port If
75. create delete and manipulate a set of predefined object types These types include tasks message queues semaphores memory regions memory partitions timers ports and rate monotonic periods The object oriented nature of RTEMS encourages the creation of modular applications built upon re usable building block routines All objects are created on the local node as required by the application and have an RTEMS assigned ID All objects have a user assigned name Although a relationship exists between an object s name and its RTEMS assigned ID the name and ID are not identical Object names are completely arbitrary and selected by the user as a meaningful tag which may commonly reflect the object s use in the application Conversely object IDs are designed to facilitate efficient object manipulation by the executive 2 2 1 Object Names An object name is an unsigned thirty two bit entity associated with the object by the user The data type rtems_name is used to store object names Although not required by RTEMS object names are often composed of four ASCII char acters which help identify that object For example a task which causes a light to blink might be called LITE The rtems_build_name routine is provided to build an object name from four ASCII characters The following example illustrates this rtems_object_name my_name my name rtems build name L I T E However it is not required that the a
76. creation e Task initiation e Task reinitiation e Task deletion e Task context switch e Post task context switch e Task begin e Task exits e Fatal error detection 228 RTEMS C User s Guide User extensions can be used to implement a wide variety of functions including execution profiling non standard coprocessor support debug support and error detection and recov ery For example the context of a non standard numeric coprocessor may be maintained via the user extensions In this example the task creation and deletion extensions are respon sible for allocating and deallocating the context area the task initiation and reinitiation extensions would be responsible for priming the context area and the task context switch extension would save and restore the context of the device For more information on user extensions refer to the Chapter 22 User Extensions Manager page 231 chapter 21 5 Multiprocessor Communications Interface MPCI RTEMS requires that an MPCI layer be provided when a multiple node application is devel oped This MPCI layer must provide an efficient and reliable communications mechanism between the multiple nodes Tasks on different nodes communicate and synchronize with one another via the MPCI Each MPCI layer must be tailored to support the architecture of the target platform For more information on the MPCI refer to the Multiprocessing Manager chapter 21 5 1 Tightly Coupled Systems A tightl
77. default for this field is 0 CONFIGURE MAXIMUM USER EXTENSIONS is the maximum number of Classic API user extensions that can be concurrently active The default for this field is 0 23 2 7 Classic API Initialization Tasks Table Configuration The rtems confdefs h configuration system can automatically generate an Initialization Tasks Table named Initialization_tasks with a single entry The following parameters control the generation of that table CONFIGURE_RTEMS_INIT_TASKS_TABLE is defined if the user wishes to use a Classic RTEMS API Initialization Task Table The application may choose to use the initialization tasks or threads table from another API By default this field is not defined as the user MUST select their own API for initialization tasks CONFIGURE_HAS_OWN_INIT_TASK_TABLE is defined if the user wishes to define their own Classic API Initialization Tasks Table This table should be named Initialization_tasks By default this is not defined CONFIGURE_INIT_TASK_NAME is the name of the single initialization task defined by the Classic API Initialization Tasks Table By default the value is rtems_build_ name U TET vq 2 gt CONFIGURE_INIT_TASK_STACK_SIZE is the stack size of the single initialization task defined by the Classic API Initialization Tasks Table By default value is the con figured minimum stack size CONFIGURE_INIT_TASK_PRIORITY is the initial priority of the single initialization task def
78. e rtems_chain_control Chain control node e rtems_chain_initialize initialize the chain with nodes e rtems_chain_initialize_empty initialize the chain as empty e rtems chain is null node Is the node NULL e rtems chain head Return the chain s head e rtems chain tail Return the chain s tail e rtems chain are nodes equal Are the node s equal e rtems chain is empty Is the chain empty e rtems chain is first Is the Node the first in the chain e rtems chain is last Is the Node the last in the chain e rtems chain has only one node Does the node have one node e rtems chain is head Is the node the head e rtems chain is tail Is the node the tail e rtems chain extract Extract the node from the chain e rtems chain get Return the first node on the chain e rtems chain insert Insert the node into the chain e rtems chain append Append the node to chain e rtems chain append unprotected Append the node to chain unprotected e rtems chain prepend Prepend the node to the end of the chain e rtems chain prepend unprotected Prepend the node to chain unprotected 28 2 Background The Chains API maps to the Super Core Chains API Chains are implemented as a double linked list of nodes anchored to a control node The list starts at the control node and is terminated at the control node A node has previous and next pointers Being a double linked list nodes can be inserted and removed with
79. each proxy used by RTEMS to manage that proxy PTCB An acronym for Partition Control Block PXCB An acronym for Proxy Control Block quantum The application defined unit of time in which the processor is allo cated queue Alternate term for message queue QCB An acronym for Message Queue Control Block ready A task occupies this state when it is available to be given control of the CPU real time A term used to describe systems which are characterized by requiring deterministic response times to external stimuli The external stimuli require that the response occur at a precise time or the response is incorrect reentrant A term used to describe routines which do not modify themselves or global variables region An RTEMS object which is used to allocate and deallocate variable size blocks of memory from a dynamically specified area of memory Region Control Block A data structure associated with each region used by RTEMS to manage that region registers Registers are locations physically located within a component typi cally used for device control or general purpose storage remote Any object that does not reside on the local node remote operation The manipulation of an object which does not reside on the same node as the calling task return code Also known as error code or return value resource A hardware or software entity to which access must be controlled resume Removing a task from the suspend state If the tas
80. eee nes 6 1 4 RTEMS Application Architecture 0 00 cece eee eee 6 1 5 RTEMS Internal Architecture 0 2 c cee eee eens f 1 6 User Customization and Extensibility 0 2000 8 l Portability scicctec tae whe e etie iere iota ce db DD dI s esate 8 18 Memory Requirements ssssseseeeeeeee enne 8 139r Ande eus acta te cl ESEE musicus dismi do soon dut eeu 9 1 10 Conventions ber Lee Hr ebRhrb RR RES FICVOLEP3 C KE RR Edda 9 111 Manual Organization osseebpres hx RE ERE ERE I Peri Res 9 2 Key ConDCODIUS cese oer rcx rere Fx ee EX RR 13 2 1 Introduction ripe tacitis si CEP ER RR I EP REP IRR 13 22 OPJECTS METIDO 13 2 2 1 Object Na Sessessdssst me REESE IR OEE EPE 13 2 2 2 Object IDS i cR rioth RE Na E REDEE 14 2 3 Communication and Synchronization 0 0000 15 244 Dini sia epi tbid ume nA UnEP RN ACUMEN DTE LE LAE dle 15 2 5 Memory Management iani eag cece eere 16 3 RTEMS Data Types 19 3l IntroduetiQu eec eer yerse badene ann sewed ead E ees 19 2 2 Listor Data Types scc eeu ier esce Rolle ele RO e sta 19 4 Initialization Manager 23 Al Introdu ctionnszsiisie is ree E ein cr dere a oat ne i diua Reis 23 4 2 Backgrounds oe fepe p ORA easton do ee pede ee Lir 25 4 2 1 Initialization Tasks 00 nee 23 4 2 2 System Initialization seeren araneon ea 23 42 3 Whe dle Vask occ saes nse ox
81. event in is set to RTEMS PENDING EVENTS then the current pending events are returned in event out and left pending The RTEMS WAIT and RTEMS NO WAIT options in the option set parameter are used to specify whether or not the task is willing to wait for the event condition to be satisfied RTEMS EVENT ANY and RTEMS EVENT ALL are used in the option set parameter are used to specify whether a single event or the complete event set is necessary to satisfy the event condition The event out parameter is returned to the calling task with the value that corresponds to the events in event in that were satisfied If pending events satisfy the event condition then event out is set to the satisfied events and the pending events in the event condition are cleared If the event condition is not satisfied and RTEMS NO WAIT is specified then event_out is set to the currently satisfied events If the calling task chooses to wait then it will block waiting for the event condition If the calling task must wait for the event condition to be satisfied then the timeout parameter is used to specify the maximum interval to wait If it is set to RTEMS NO TIMEOUT then the calling task will wait forever NOTES This directive only affects the events specified in event in Any pending events that do not correspond to any of the events specified in event in will be left pending The following event receive option constants are defined by RTEMS e
82. for dynamic addition and removal of entries It is not statically limited to a particular size A data representation scheme in which the bytes composing a numeric value are arranged such that the least significant byte is at the lowest address An object which was created with the LOCAL attribute and is ac cessible only on the node it was created and resides upon In a single processor configuration all objects are local The manipulation of an object which resides on the same node as the calling task An address used by an application In a system without memory management logical addresses will equal physical addresses A multiprocessor configuration where shared memory is not used for communication The index of a device driver in the Device Driver Table A group of related RTEMS directives which provide access and con trol over resources Used interchangeably with heap A sixteen byte entity used to communicate between tasks Messages are sent to message queues and stored in message buffers Chapter 31 Glossary 341 message buffer A block of memory used to store messages message queue An RTEMS object used to synchronize and communicate between tasks by transporting messages between sending and receiving tasks Message Queue Control Block A data structure associated with each message queue used by RTEMS to manage that message queue minor number A numeric value passed to a device driver the exact usage of wh
83. function returns true if the left node and the right node are equal and false otherwise Chapter 28 Chains 28 4 7 Is the Chain Empty CALLING SEQUENCE bool rtems_chain_is_empty rtems_chain_control the_chain 25 RETURNS This function returns true if there a no nodes on the chain and false otherwise DESCRIPTION This function returns true if there a no nodes on the chain and false otherwise 319 320 RTEMS C User s Guide 28 4 8 Is this the First Node on the Chain CALLING SEQUENCE bool rtems_chain_is_first const rtems_chain_node the_node 25 RETURNS This function returns true if the node is the first node on a chain and false otherwise DESCRIPTION This function returns true if the node is the first node on a chain and false otherwise Chapter 28 Chains 321 28 4 9 Is this the Last Node on the Chain CALLING SEQUENCE bool rtems chain is last const rtems chain node the node 25 RETURNS This function returns true if the node is the last node on a chain and false otherwise DESCRIPTION This function returns true if the node is the last node on a chain and false otherwise 322 RTEMS C User s Guide 28 4 10 Does this Chain have only One Node CALLING SEQUENCE bool rtems_chain_has_only_one_node const rtems_chain_control the_chain 25 RETURNS This function returns true if there is only one node on the chain and false otherwise DESCRIPTION This function returns t
84. if the driver blocks the invoking task blocks e The device driver is free to change the modes of the invoking task although the driver should restore them to their original values e Device drivers may be invoked from ISRs e Only local device drivers are accessible through the I O manager e A device driver routine may invoke all other RTEMS directives including I O di rectives on both local and global objects Although the RTEMS I O manager provides a framework for device drivers it makes no assumptions regarding the construction or operation of a device driver 16 2 5 Runtime Driver Registration Board support package and application developers can select wether a device driver is statically entered into the default device table or registered at runtime Dynamic registration helps applications where 1 The BSP and kernel libraries are common to a range of applications for a specific target platform An application may be built upon a common library with all drivers The application selects and registers the drivers Uniform driver name lookup protects the application 2 The type and range of drivers may vary as the application probes a bus during initialization 3 Support for hot swap bus system such as Compact PCI 4 Support for runtime loadable driver modules Chapter 16 I O Manager 173 16 2 6 Device Driver Interface When an application invokes an I O manager directive RTEMS determines which device driver entr
85. interrupt executing The task state entered by a task after it has been given control of the CPU executive In this document this term is used to referred to RTEMS Com monly an executive is a small real time operating system used in embedded systems exported An object known by all nodes in a multiprocessor system An object created with the GLOBAL attribute will be exported external address The address used to access dual ported memory by all the nodes in a system which do not own the memory FIFO An acronym for First In First Out First In First Out A discipline for manipulating entries in a data structure floating point coprocessor A component used in computer systems to enhance performance in mathematically intensive situations It is typically viewed as a logical extension of the primary processor freed A resource that has been released by the application to RTEMS global An object that has been created with the GLOBAL attribute and exported to all nodes in a multiprocessor system handler The equivalent of a manager except that it is internal to RTEMS and forms part of the core A handler is a collection of routines which provide a related set of functions For example there is a handler used by RTEMS to manage all objects hard real time system A real time system in which a missed deadline causes the worked performed to have no value or to result in a catastrophic effect on the integrity of the system heap A d
86. invoking the extension sets in this order extensions can be built upon one another At the following system events the extensions are invoked in forward order e Task creation e Task initiation e Task reinitiation e Task deletion e Task context switch e Post task context switch Task begins to execute At the following system events the extensions are invoked in reverse order e Task deletion e Fatal error detection At these system events the extensions are invoked in reverse order to insure that if an extension set is built upon another the more complicated extension is invoked before the extension set it is built upon For example by invoking the static extension set last it is known that the system fatal error extension will be the last fatal error extension executed Another example is use of the task delete extension by the Standard C Library Extension sets which are installed after the Standard C Library will operate correctly even if they utilize the C Library because the C Library s TASK DELETE extension is invoked after that of the other extensions 22 3 Operations 22 3 1 Creating an Extension Set The rtems extension create directive creates and installs an extension set by allocating a Extension Set Control Block ESCB assigning the extension set a user specified name and assigning it an extension set ID Newly created extension sets are immediately installed and are invoked upon the next system even supp
87. is not valid 1 is returned If successful this service returns the maximum valid for the class portion of an object Id for the specified api DESCRIPTION This service returns the maximum valid for the class portion of an object Id for the specified api NOTES This directive is strictly local and does not impact task scheduling Chapter 27 Object Services 305 27 4 14 OBJECT_GET_API_NAME Obtain API Name CALLING SEQUENCE const char rtems object get api name uint32 t api 3 DIRECTIVE STATUS CODES If api is not valid the string BAD API is returned If successful this service returns a pointer to a string containing the name of the specified api DESCRIPTION This service returns the name of the specified api NOTES This directive is strictly local and does not impact task scheduling The string returned is from constant space Do not modify or free it 306 RTEMS C User s Guide 27 4 15 OBJECT GET API CLASS NAME Obtain Class Name CALLING SEQUENCE const char rtems object get api class name uint32 t the api uint32 t the class DIRECTIVE STATUS CODES If the api is not valid the string BAD API is returned If the class is not valid the string BAD CLASS is returned If successful this service returns a pointer to a string containing the name of the specified the api the class pair DESCRIPTION This service returns the name of the object class indicated by the
88. is one which must be executed at a regular interval The interval between successive iterations of the task is referred to as its period Periodic tasks can be character ized by the length of their period and execution time The period and execution time of a task can be used to determine the processor utilization for that task Processor utilization is the percentage of processor time used and can be calculated on a per task or system wide basis Typically the task s worst case execution time will be less than its period For example a periodic task s requirements may state that it should execute for 10 millisec onds every 100 milliseconds Although the execution time may be the average worst or best case the worst case execution time is more appropriate for use when analyzing system behavior under transient overload conditions In contrast an aperiodic task executes at irregular intervals and has only a soft deadline In other words the deadlines for aperiodic tasks are not rigid but adequate response times are desirable For example an aperiodic task may process user input from a terminal Finally a sporadic task is an aperiodic task with a hard deadline and minimum interarrival time The minimum interarrival time is the minimum period of time which exists between Chapter 19 Rate Monotonic Manager 197 successive iterations of the task For example a sporadic task could be used to process the pressing of a fire button on a joystick
89. is usually provided as an interrupt from a counter timer or a real time clock device When a counter timer is used to provide the clock tick the device is typically programmed to operate in continuous mode This mode selection causes the device to automatically reload the initial count and continue the countdown without programmer intervention This reduces the overhead required to manipulate the counter timer in the clock tick ISR and increases the accuracy of tick occurrences The initial count can be based on the microseconds_per_tick field in the RTEMS Configuration Table An alternate approach is to set the initial count for a fixed time period such as one millisecond and have the ISR invoke rtems clock tick on the configured microseconds per tick boundaries Obviously this can induce some error if the configured microseconds per tick is not evenly divisible by the chosen clock interrupt quantum It is important to note that the interval between clock ticks directly impacts the granularity of RTEMS timing operations In addition the frequency of clock ticks is an important factor in the overall level of system overhead A high clock tick frequency results in less processor time being available for task execution due to the increased number of clock tick ISRs 21 4 User Extensions RTEMS allows the application developer to augment selected features by invoking user supplied extension routines when the following system events occur e Task
90. manager are e rtems_semaphore_create Create a semaphore e rtems semaphore ident Get ID of a semaphore e rtems semaphore delete Delete a semaphore e rtems semaphore obtain Acquire a semaphore e rtems semaphore release Release a semaphore e rtems semaphore flush Unblock all tasks waiting on a semaphore 9 2 Background A semaphore can be viewed as a protected variable whose value can be modified only with the rtems semaphore create rtems semaphore obtain and rtems_semaphore_ release directives RTEMS supports both binary and counting semaphores A binary semaphore is restricted to values of zero or one while a counting semaphore can assume any non negative integer value A binary semaphore can be used to control access to a single resource In particular it can be used to enforce mutual exclusion for a critical section in user code In this instance the semaphore would be created with an initial count of one to indicate that no task is executing the critical section of code Upon entry to the critical section a task must issue the rtems semaphore obtain directive to prevent other tasks from entering the critical section Upon exit from the critical section the task must issue the rtems_semaphore_ release directive to allow another task to execute the critical section A counting semaphore can be used to control access to a pool of two or more resources For example access to three printers could be administered by a semap
91. rd onum PRSE 242 347 CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK 242 CONFIGURE_MALLOC_STATISTICS 242 CONFIGURE_MAXIMUM_ADA_TASKS 250 CONFIGURE_MAXIMUM_DEVICES 245 CONFIGURE MAXIMUM DRIVERS 245 CONFIGURE MAXIMUM FAKE ADA TASKS 250 CONFIGURE MAXIMUM ITRON EVENTFLAGS 249 CONFIGURE MAXIMUM ITRON FIXED MEMORY POOLS sieben E E S peu edere ires 249 CONFIGURE MAXIMUM ITRON MAILBOXES 249 CONFIGURE MAXIMUM ITRON MEMORY POOLS 249 CONFIGURE MAXIMUM ITRON MESSAGE BUFFERS seule oir A det aa wads se Gnd E ice E 249 CONFIGURE_MAXIMUM_ITRON_PORTS 249 CONFIGURE MAXIMUM ITRON SEMAPHORES 249 CONFIGURE MAXIMUM ITRON TASKS 249 CONFIGURE MAXIMUM MESSAGE QUEUES 247 CONFIGURE MAXIMUM PARTITIONS 247 CONFIGURE_MAXIMUM_PERIODS 247 CONFIGURE MAXIMUM PORTS 247 CONFIGURE MAXIMUM POSIX CONDITION VARIABLES METERS 248 CONFIGURE MAXIMUM POSIX KEYS 248 CONFIGURE MAXIMUM POSIX MESSAGE QUEUES 248 CONFIGURE MAXIMUM POSIX MUTEXES 248 CONFIGURE MAXIMUM POSIX QUEUED SIGNALS 248 CONFIGURE MAXIMUM POSIX SEMAPHORES 248 CONFIGURE MAXIMUM POSIX THREADS 248 CONFIGURE MAXIMUM POSIX TIMERS 248 CONFIGURE MAXIMUM PRIORITY s 243 CONFIGURE MAXIMUM REGIONS
92. real time systems the services provided by the rate monotonic manager may be used by any application which requires periodic tasks 19 2 1 Rate Monotonic Manager Required Support A clock tick is required to support the functionality provided by this manager 19 2 2 Period Statistics This manager maintains a set of statistics on each period These statistics are reset implictly at period creation time and may be reset or obtained at any time by the application The following is a list of the information kept e owner is the id of the thread that owns this period e count is the total number of periods executed e missed_count is the number of periods that were missed e min_cpu_time is the minimum amount of CPU execution time consumed on any execution of the periodic loop e max_cpu_time is the maximum amount of CPU execution time consumed on any execution of the periodic loop 196 RTEMS C User s Guide e total_cpu_time is the total amount of CPU execution time consumed by executions of the periodic loop e min_wall_time is the minimum amount of wall time that passed on any execution of the periodic loop e max_wall_time is the maximum amount of wall time that passed on any execution of the periodic loop e total wall time is the total amount of wall time that passed during executions of the periodic loop The period statistics information is inexpensive to maintain and can provide very useful insights into the execution characterist
93. rective NOTES This directive will not cause the running task to be preempted Chapter 19 Rate Monotonic Manager 213 19 4 7 RATE_MONOTONIC_GET_STATISTICS Obtain statistics from a period CALLING SEQUENCE rtems status code rtems_rate_monotonic_get_statistics rtems id id rtems rate monotonic period statistics statistics 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL period initiated successfully RTEMS INVALID ID invalid rate monotonic period id RTEMS INVALID ADDRESS invalid address of statistics DESCRIPTION This directive returns statistics information associated with the rate monotonic period id in the following data structure typedef struct uint32_t count uint32_t missed_count ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS struct timespec min_cpu_time struct timespec max_cpu_time struct timespec total_cpu_time else uint32_t min_cpu_time uint32_t max_cpu_time uint32 t total_cpu_time endif ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS struct timespec min_wall_time struct timespec max_wall_time struct timespec total_wall_time else uint32_t min_wall_time uint32_t max_wall_time uint32 t total wall time endif rtems rate monotonic period statistics This directive returns the current statistics information for the period instance assocaited with id The information returned is indicated by the structure above NOTES This directive will not ca
94. returned DESCRIPTION This function removes the first node from the chain and returns a pointer to that node If the chain is empty then NULL is returned NOTES Interrupts are disabled while obtaining the node to ensure the atomicity of the operation Chapter 28 Chains 28 4 15 Insert a Node CALLING SEQUENCE void rtems_chain_insert rtems_chain_node after_node rtems_chain_node the_node 2s RETURNS Returns nothing DESCRIPTION This routine inserts a node on a chain immediately following the specified node NOTES Interrupts are disabled during the insert to ensure the atomicity of the operation 327 328 RTEMS C User s Guide 28 4 16 Append a Node CALLING SEQUENCE void rtems chain append rtems chain control the chain rtems chain node the node 2s RETURNS Returns nothing DESCRIPTION This routine appends a node to the end of a chain NOTES Interrupts are disabled during the append to ensure the atomicity of the operation Chapter 28 Chains 329 28 4 17 Append a Node unprotected CALLING SEQUENCE void rtems_chain_append_unprotected rtems_chain_control the_chain rtems_chain_node the_node 2s RETURNS Returns nothing DESCRIPTION This routine appends a node to the end of a chain NOTES Interrupts are NOT disabled during the append to ensure the atomicity of the operation 330 RTEMS C User s Guide 28 4 18 Prepend a Node CALLING SEQUENCE
95. rtems status code rtems task resume rtems id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL task restarted successfully RTEMS INVALID ID task id invalid RTEMS INCORRECT STATE task not suspended DESCRIPTION This directive removes the task specified by id from the suspended state If the task is in the ready state after the suspension is removed then it will be scheduled to run If the task is still in a blocked state after the suspension is removed then it will remain in that blocked state NOTES The running task may be preempted if its preemption mode is enabled and the local task being resumed has a higher priority Resuming a global task which does not reside on the local node will generate a request to the remote node to resume the specified task If the task specified by id is not suspended then the RTEMS INCORRECT STATE status code is returned Chapter 5 Task Manager 49 5 4 9 TASK IS SUSPENDED Determine if a task is Suspended CALLING SEQUENCE rtems status code rtems task is suspended rtems id id DIRECTIVE STATUS CODES RTEMS SUCCESSFUL task is NOT suspended RTEMS ALREADY SUSPENDED task is currently suspended RTEMS INVALID ID task id invalid RTEMS ILLEGAL ON REMOTE OBJECT not supported on remote tasks DESCRIPTION This directive returns a status code indicating whether or not the specified task is currently suspended NOTES This operation is not currently s
96. rtems status code rtems region ident rtems name name rtems id id DIRECTIVE STATUS CODES RTEMS SUCCESSFUL region identified successfully RTEMS INVALID ADDRESS id is NULL RTEMS INVALID NAME region name not found DESCRIPTION This directive obtains the region id associated with the region name to be acquired If the region name is not unique then the region id will match one of the regions with that name However this region id is not guaranteed to correspond to the desired region The region id is used to access this region in other region manager directives NOTES This directive will not cause the running task to be preempted Chapter 14 Region Manager 155 14 4 3 REGION DELETE Delete a region CALLING SEQUENCE rtems status code rtems region delete rtems id id 93 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL region deleted successfully RTEMS INVALID ID invalid region id RTEMS RESOURCE IN USE segments still in use DESCRIPTION This directive deletes the region specified by id The region cannot be deleted if any of its segments are still allocated The RNCB for the deleted region is reclaimed by RTEMS NOTES This directive will not cause the calling task to be preempted The calling task does not have to be the task that created the region Any local task that knows the region id can delete the region 156 RTEMS C User s Guide 14 4 4 REGION_EXTEND Add memory to a region CALLING SE
97. segment fails then the application may want to allocate a new segment of the desired size copy the contents of the original segment to the new larger segment and then return the original segment Chapter 15 Dual Ported Memory Manager 163 15 Dual Ported Memory Manager 15 1 Introduction The dual ported memory manager provides a mechanism for converting addresses between internal and external representations for multiple dual ported memory areas DPMA The directives provided by the dual ported memory manager are e rtems_port_create Create a port e rtems_port_ident Get ID of a port e rtems_port_delete Delete a port e rtems_port_external_to_internal Convert external to internal address e rtems_port_internal_to_external Convert internal to external address 15 2 Background A dual ported memory area DPMA is an contiguous block of RAM owned by a particular processor but which can be accessed by other processors in the system The owner accesses the memory using internal addresses while other processors must use external addresses RTEMS defines a port as a particular mapping of internal and external addresses There are two system configurations in which dual ported memory is commonly found The first is tightly coupled multiprocessor computer systems where the dual ported memory is shared between all nodes and is used for inter node communication The second configura tion is computer systems with intelligent peripheral
98. sseeseseeeee 191 LaskStaleS iic na Dip e tees inact msase pleim E errare 32 task definitlon scires rr ER RE RR 31 GASKS M 31 TCB extensi atea 604 emere 232 nin EMIT 15 UUM COMES oie a coder ca pens been aaa enemas bed 72 DITS l4 exe ED REIP aces Ree Gave os EET 85 limesliclug iecit deren RES 33 72 190 RTEMS C User s Guide U unblock all tasks waiting on a semaphore 112 unlock a semaphore cece eee eee 111 unregister a device driver 176 UPME oe cease nrsadags Pe ave TEE EREE 81 User extensions p Meee ean eee ieee 231 User Extensions Table 205 261 W wait at a Daffler 25e eer rrr RR 224 wake up after an interval esses 54 wake up at a wall time ueessseeese 55 write to a device 0 kee leere 183
99. task mode constants are defined by RTEMS e RTEMS_PREEMPT enable preemption default e RTEMS_NO_PREEMPT disable preemption e RTEMS_NO_TIMESLICE disable timeslicing default e RTEMS_TIMESLICE enable timeslicing e RTEMS_ASR enable ASR processing default e RTEMS NO ASR disable ASR processing e RTEMS INTERRUPT LEVEL O0 enable all interrupts default e RTEMS INTERRUPT LEVEL n execute at interrupt level n The interrupt level portion of the task execution mode supports a maximum of 256 interrupt levels These levels are mapped onto the interrupt levels actually supported by the target processor in a processor dependent fashion Tasks should not be made global unless remote tasks must interact with them This avoids the system overhead incurred by the creation of a global task When a global task is created the task s name and id must be transmitted to every node in the system for insertion in the local copy of the global object table The total number of global objects including tasks is limited by the maxi mum global objects field in the Configuration Table 42 RTEMS C User s Guide 5 4 2 TASK_IDENT Get ID of a task CALLING SEQUENCE rtems_status_code rtems_task_ident rtems_name name uint32_t node rtems_id id Jz DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL task identified successfully RTEMS_INVALID_ADDRESS id is NULL RTEMS_INVALID_NAME invalid task name RTEMS_INVALID_NODE i
100. terminology for context switch Taking control of the pro cessor from one task and given to another An acronym for Task Control Block The basic unit of time used by RTEMS It is a user configurable number of microseconds The current tick expires when the rtems_clock_tick directive is invoked A multiprocessor configuration system which communicates via shared memory An argument provided to a number of directives which determines the maximum length of time an application task is willing to wait to acquire the resource if it is not immediately available An RTEMS object used to invoke subprograms at a later time A data structure associated with each timer used by RTEMS to manage that timer A task scheduling discipline in which tasks of equal priority are exe cuted for a specific period of time before being preempted by another task The application defined unit of time in which the processor is allo cated An acronym for Timer Control Block A temporary rise in system activity which may cause deadlines to be missed Rate Monotonic Scheduling can be used to determine if all deadlines will be met under transient overload Software routines provided by the application to enhance the func tionality of RTEMS A table which contains the entry points for each user extensions User Initialization Tasks Table user provided user supplied vector wait queue yield A table which contains the information needed t
101. the specified message queue If at least one message is in the queue then the message is removed from the queue copied to the caller s message buffer and returned immediately along with the length of the message When messages are unavailable one of the following situations applies e By default the calling task will wait forever for the message to arrive e Specifying the RTEMS_NO_WAIT option forces an immediate return with an error status code e Specifying a timeout limits the period the task will wait before returning with an error status If the task waits for a message then it is placed in the message queue s task wait queue in either FIFO or task priority order All tasks waiting on a message queue are returned an error code when the message queue is deleted 10 3 4 Sending a Message Messages can be sent to a queue with the rtems_message_queue_send and rtems_message_ queue_urgent directives These directives work identically when tasks are waiting to receive a message A task is removed from the task waiting queue unblocked and the message is copied to a waiting task s message buffer When no tasks are waiting at the queue rtems_message_queue_send places the message at the rear of the message queue while rtems_message_queue_urgent places the message at the front of the queue The message is copied to a message buffer from this message queue s buffer pool and then placed in the message queue Neither directive can su
102. the packet for each node in the system Many MPCI layers use the packet_length field of the rtems_packet_prefix portion of the packet to avoid sending unnecessary data This is especially useful if the media connecting the nodes is relatively slow The to_convert field of the MP_packet_prefix portion of the packet indicates how much of the packet in uint32_t s may require conversion in a heterogeneous system 24 3 6 Supporting Heterogeneous Environments Developing an MPCI layer for a heterogeneous system requires a thorough understanding of the differences between the processors which comprise the system One difficult problem is the varying data representation schemes used by different processor types The most pervasive data representation problem is the order of the bytes which compose a data entity Processors which place the least significant byte at the smallest address are classified as little endian processors Little endian byte ordering is shown below Byte 3 Byte 2 Byte 1 Byte 0 Conversely processors which place the most significant byte at the smallest address are classified as big endian processors Big endian byte ordering is shown below Chapter 24 Multiprocessing Manager 277 Unfortunately sharing a data structure between big endian and little endian processors requires translation into a common endian format An application designer typically chooses the common endian format to m
103. the pending message count for the specified message queue Chapter 10 Message Manager 127 10 4 9 MESSAGE QUEUE FLUSH Flush all messages on a queue CALLING SEQUENCE rtems status code rtems message queue flush rtems id id uint32 t count DIRECTIVE STATUS CODES RTEMS SUCCESSFUL message queue flushed successfully RTEMS INVALID ADDRESS count is NULL RTEMS INVALID ID invalid queue id DESCRIPTION This directive removes all pending messages from the specified queue id The number of messages removed is returned in count If no messages are present on the queue count is set to zero NOTES Flushing all messages on a global message queue which does not reside on the local node will generate a request to the remote node to actually flush the specified message queue Chapter 11 Event Manager 129 11 Event Manager 11 1 Introduction The event manager provides a high performance method of intertask communication and synchronization The directives provided by the event manager are e rtems_event_send Send event set to a task e rtems_event_receive Receive event condition 11 2 Background 11 2 1 Event Sets An event flag is used by a task or ISR to inform another task of the occurrence of a significant situation Thirty two event flags are associated with each task A collection of one or more event flags is referred to as an event set The data type rtems_event_set is used to manage event sets
104. the timer specified by id and specifies that when it fires it will be executed by the Timer Server If the timer is running it is automatically canceled before being initiated The timer is scheduled to fire after an interval ticks clock ticks has passed When the timer fires the timer service routine routine will be invoked with the argument user data NOTES This directive will not cause the running task to be preempted 96 RTEMS C User s Guide 8 4 9 TIMER_SERVER_FIRE_WHEN Fire task based timer when specified CALLING SEQUENCE rtems status code rtems timer server fire when rtems id id rtems time of day wall time rtems timer service routine entry routine void user data DIRECTIVE STATUS CODES RTEMS SUCCESSFUL timer initiated successfully RTEMS INVALID ADDRESS routine is NULL RTEMS INVALID ADDRESS wall time is NULL RTEMS INVALID ID invalid timer id RTEMS NOT DEFINED system date and time is not set RTEMS INVALID CLOCK invalid time of day RTEMS INCORRECT STATE Timer Server not initiated DESCRIPTION This directive initiates the timer specified by id and specifies that when it fires it will be executed by the Timer Server If the timer is running it is automatically canceled before being initiated The timer is scheduled to fire at the time of day specified by wall_time When the timer fires the timer service routine routine will be invoked with the argument user dat
105. to establish an ASR which executes at interrupt level three and is non preemptible The mode should be set to RTEMS_INTERRUPT_LEVEL 3 RTEMS NO PREEMPT to indicate the desired processor mode and interrupt level 12 3 Operations 12 3 1 Establishing an ASR The rtems signal catch directive establishes an ASR for the calling task The address of the ASR and its execution mode are specified to this directive The ASR s mode is distinct from the task s mode For example the task may allow preemption while that task s ASR may have preemption disabled Until a task calls rtems signal catch the first time its ASR is invalid and no signal sets can be sent to the task A task may invalidate its ASR and discard all pending signals by calling rtems signal catch with a value of NULL for the ASR s address When a task s ASR is invalid new signal sets sent to this task are discarded A task may disable ASR processing RTEMS NO ASR via the task mode directive When a task s ASR is disabled the signals sent to it are left pending to be processed later when the ASR is enabled Chapter 12 Signal Manager 137 Any directive that can be called from a task can also be called from an ASR A task is only allowed one active ASR Thus each call to rtems_signal_catch replaces the previous one Normally signal processing is disabled for the ASR s execution mode but if signal processing is enabled for the ASR the ASR must be reentrant
106. to associate the API and Class portions of an Object Id with strings This allows the application developer to provide more information about an object in diagnostic messages In the following C language example an Id is decomposed into its constituent parts and pretty printed void prettyPrintObjectId rtems_id id i uint32_t tmpAPI tmpClass tmpAPI rtems_object_id_get_api id tmpClass rtems_object_id_get_class id printf API s Class s Node d Index d n rtems object get api name tmpAPI rtems object get api class name tmpAPI tmpClass rtems object id get node id rtems object id get index id 27 4 Directives 292 RTEMS C User s Guide 27 4 1 BUILD_NAME Build object name from characters CALLING SEQUENCE rtems_name rtems_build_name uint8_t cl uint8_t c2 uint8_t c3 uint8_t c4 DIRECTIVE STATUS CODES Returns a name constructed from the four characters DESCRIPTION This service takes the four characters provided as arguments and constructs a thirty two bit object name with c1 in the most significant byte and c4 in the least significant byte NOTES This directive is strictly local and does not impact task scheduling Chapter 27 Object Services 293 27 4 2 OBJECT_GET_CLASSIC_NAME Lookup name from id CALLING SEQUENCE rtems status code rtems_object_get_classic_name rtems id Xd rtems name name 3 DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL name looked up success
107. unblocked If no tasks are waiting on the queue then the message is copied to a message buffer which is obtained from this message queue s message buffer pool The message buffer is then placed at the front of the queue NOTES The calling task will be preempted if it has preemption enabled and a higher priority task is unblocked as the result of this directive Sending a message to a global message queue which does not reside on the local node will generate a request telling the remote node to post the message on the specified message queue If the task to be unblocked resides on a different node from the message queue then the message is forwarded to the appropriate node the waiting task is unblocked and the proxy used to represent the task is reclaimed Chapter 10 Message Manager 123 10 4 6 MESSAGE QUEUE BROADCAST Broadcast N messages to a queue CALLING SEQUENCE rtems status code rtems message queue broadcast rtems id id const void buffer size t size uint32 t count DIRECTIVE STATUS CODES RTEMS SUCCESSFUL message broadcasted successfully RTEMS INVALID ID invalid queue id RTEMS INVALID ADDRESS buffer is NULL RTEMS INVALID ADDRESS count is NULL RTEMS INVALID SIZE invalid message size DESCRIPTION This directive causes all tasks that are waiting at the queue specified by id to be unblocked and sent the message contained in buffer Before a task is unblocked the message buffe
108. 0 1 0 99 0 0 0 00 0x42010002 TA2 502 0 0 1 0 99 0 0 0 00 0x42010003 TA3 501 0 0 1 0 99 0 0 0 00 0x42010004 TA4 501 0 0 1 0 99 0 0 0 00 0x42010005 TA5 10 0 0 1 0 90 0 0 0 00 NOTES This directive will not cause the running task to be preempted Chapter 20 Barrier Manager 217 20 Barrier Manager 20 1 Introduction The barrier manager provides a unique synchronization capability which can be used to have a set of tasks block and be unblocked as a set The directives provided by the barrier manager are e rtems_barrier_create Create a barrier e rtems_barrier_ident Get ID of a barrier e rtems_barrier_delete Delete a barrier e rtems_barrier_wait Wait at a barrier e rtems_barrier_release Release a barrier 20 2 Background A barrier can be viewed as a gate at which tasks wait until the gate is opened This has many analogies in the real world Horses and other farm animals may approach a closed gate and gather in front of it waiting for someone to open the gate so they may proceed Similarly cticket holders gather at the gates of arenas before concerts or sporting events waiting for the arena personnel to open the gates so they may enter Barriers are useful during application initialization Each application task can perform its local initialization before waiting for the application as a whole to be initialized Once all tasks have completed their independent initializations the application ready barrier can be rele
109. 00 58 obtain seconds since epoch 78 79 obtain statistics of period 004 213 obtain status of period 2 000s 212 obtain task mode 2 052060 ee eee eens re ol obtain task priority cc0c eee eget 50 obtain the ID of a timer 20 89 obtain the time of day on TO f obtain ticks since boot eee eee eee 80 obtaining class from object ID 14 obtaining index from object ID 14 obtaining node from object ID 14 open a deviye uses uexm e re dM TEUER ER 180 P partition attribute set building 141 partition definition 0 eee eee 141 partitions 454 5154 eee cea HIRES eee 141 per task variables cc cece eee eee eee 35 per task variable 0 eee eee eee eee 57 59 period initiation eee eee eee 211 period statistics report eee eee ee ee 216 periodic task definition 204 196 periodic tasks eee e eee eee eee ee 195 DOE residint ednini dea Reta Ted a d EP ERES 163 POSIX API Configuration Table 257 preemptiion iicseiesumedeRsceedech e ERE 33 190 prepend node seseeesseesees 330 331 print period statistics report 216 priority CASK aces iue hex tr decre posee ipn be 32 proxy defniblon ev Rr REIR IRR 213 put message at front of queue
110. 20 rtems_message_queue_flush T27 rtems_message_queue_get_number_pending 126 rtems_message_queue_ident 119 rtems_message_queue_receive 124 Command and Variable Index rtems_message_queue_send 121 rtems message queue urgent 122 ptems mode bis Ged einai poe aspe aia np braun 20 rtems mp packet classes sess 20 rtems mpci entry cesses 20 274 rtems mpci get packet entry 20 rtems mpci initialization entry 20 rtems mpci receive packet entry 20 rtems mpci return packet entry 20 rtems mpci send packet entry 20 rtens mpci table va pr eR es 20 rtems multiprocessing announce 278 rtems name 6g Rad Nae eae Ma aed 20 rtems object api maximum class 304 rtems object api minimum class 303 rtems object get api class name 306 rtems object get api name 305 rtems object get class information 307 rtems_object_get_name 13 294 rtems_object_id_api_maximum 302 rtems_object_id_api_minimum 301 rtems object id get api 14 296 rtems object id get class 14 297 rtems object id get index 14 299 rtems object id get node 14 298 rtems object name dll lp iiinis 13 rtems object set name
111. 23 3 Configuration Table The RTEMS Configuration Table is used to tailor an application for its specific needs For example the user can configure the number of device drivers or which APIs may be used THe address of the user defined Configuration Table is passed as an argument to the rtems_ initialize executive directive which MUST be the first RTEMS directive called The RTEMS Configuration Table is defined in the following C structure Chapter 23 Configuring a System 251 typedef struct void work_space_start uint32_t work_space_size uint32_t maximum_extensions uint32_t microseconds_per_tick uint32_t ticks_per_timeslice void idle_task void uint32_t idle_task_stack_size uint32 t interrupt stack size void x stack allocate hook uint32 t void stack free hook void bool do zero of workspace uint32 t maximum drivers uint32 t number of device drivers rtems driver address table Device driver table uint32 t number of initial extensions rtems extensions table User extension table if defined RTEMS MULTIPROCESSING rtems multiprocessing table User multiprocessing table endif rtems_api_configuration_table RTEMS api configuration posix api configuration table POSIX api configuration itron api configuration ITRON api configuration rtems configuration table work space start work space size microseconds per tick is the address of the RTEMS RAM Workspace This area
112. 5 Stack Bounds Checker 279 25 Stack Bounds Checker 25 1 Introduction The stack bounds checker is an RTEMS support component that determines if a task has overrun its run time stack The routines provided by the stack bounds checker manager are e rtems_stack_checker_is_blown Has the Current Task Blown its Stack e rtems_stack_checker_report_usage Report Task Stack Usage 25 2 Background 25 2 1 Task Stack Each task in a system has a fixed size stack associated with it This stack is allocated when the task is created As the task executes the stack is used to contain parameters return addresses saved registers and local variables The amount of stack space required by a task is dependent on the exact set of routines used The peak stack usage reflects the worst case of subroutine pushing information on the stack For example if a subroutine allocates a local buffer of 1024 bytes then this data must be accounted for in the stack of every task that invokes that routine Recursive routines make calculating peak stack usage difficult if not impossible Each call to the recursive routine consumes n bytes of stack space If the routine recursives 1000 times then 1000 n bytes of stack space are required 25 2 2 Execution The stack bounds checker operates as a set of task extensions At task creation time the task s stack is filled with a pattern to indicate the stack is unused As the task executes it will overwrite this pat
113. AME invalid semaphore name RTEMS INVALID ADDRESS id is NULL RTEMS TOO MANY too many semaphores created RTEMS NOT DEFINED invalid attribute set RTEMS INVALID NUMBER invalid starting count for binary semaphore RTEMS MP NOT CONFIGURED multiprocessing not configured RTEMS TOO MANY too many global objects DESCRIPTION This directive creates a semaphore which resides on the local node The created semaphore has the user defined name specified in name and the initial count specified in count For control and maintenance of the semaphore RTEMS allocates and initializes a SMCB The RTEMS assigned semaphore id is returned in id This semaphore id is used with other semaphore related directives to access the semaphore Specifying PRIORITY in attribute_set causes tasks waiting for a semaphore to be serviced according to task priority When FIFO is selected tasks are serviced in First In First Out order NOTES This directive will not cause the calling task to be preempted The priority inheritance and priority ceiling algorithms are only supported for local binary semaphores that use the priority task wait queue blocking discipline The following semaphore attribute constants are defined by RTEMS e RTEMS_FIFO tasks wait by FIFO default e RTEMS_PRIORITY tasks wait by priority e RTEMS_BINARY_SEMAPHORE restrict values to 0 and 1 e RTEMS_COUNTING_SEMAPHORE no restriction on values default e RTE
114. ASS Obtain Maximum Class Value eee bero Eier RE en Deed 304 27 4 14 OBJECT GET API NAME Obtain API Name 305 27 415 OBJECT GET API CLASS NAME Obtain Class Name TET 306 27 4 16 OBJECT GET CLASS INFORMATION Obtain Class Information 00 ccc RR RI n 307 28 Chains eiee e proie dA dures 309 28 1 IntrOducilOBs2zce eser A A edu eese once 309 28 2 Background susce e yeu shea PEREFPER RE 4 quaere s 309 28 2 1 Nodes esses ua Ree a meses de ho e me hera 310 20 2 2 CS ODUEOISU iens pietre Dome e dp 310 28 39 Operations soles saat Odean EE REVUE aD RU REIR ere dus 310 28 3 0 Multi threading ies esee beg otto m 310 28 3 2 Creating a Chain 0 cece eee eens ould 28 3 3 Iterating a Chain 0 0 eee een eens 311 28 4 DITeCUVeScaeieeerev reinos RAE v dne erpPPRP E EE DII Renee 312 28 4 1 Initialize Chain With Nodes sese 313 28 4 2 Initialize Empty echo xit teens 314 28 4 3 Is Null Node scele le eer PEERS 315 28447 Head os ss esatta re ts doreetend detente ape ctl Guat nei E 316 20 5 rad es secuti eee D e des oT 28 4 6 Are Two Nodes Equal 0 cece eens 318 284 7 Is the Chain Emptly licenter ehe n ben etn 319 28 4 8 Is this the First Node on the Chain 320 28 4 9 Is this the Last Node on the Chain 321 28 4 10 Does this Chain have only One Node 322 28 4 11 Is this Node the Chain Head 0 323
115. CB from the PCB free list This data structure is used by RTEMS to manage the newly created rate monotonic period RTEMS returns a unique period ID to the application which is used by other rate monotonic manager directives to access this rate monotonic period 19 3 2 Manipulating a Period The rtems_rate_monotonic_period directive is used to establish and maintain periodic execution utilizing a previously created rate monotonic period Once initiated by the rtems_rate_monotonic_period directive the period is said to run until it either expires or is reinitiated The state of the rate monotonic period results in one of the following scenarios e If the rate monotonic period is running the calling task will be blocked for the remainder of the outstanding period and upon completion of that period the period will be reinitiated with the specified period e If the rate monotonic period is not currently running and has not expired it is initiated with a length of period ticks and the calling task returns immediately e If the rate monotonic period has expired before the task invokes the rtems_rate_ monotonic_period directive the period will be initiated with a length of period ticks and the calling task returns immediately with a timeout error status 19 3 3 Obtaining the Status of a Period If the rtems_rate_monotonic_period directive is invoked with a period of RTEMS_PERIOD_ STATUS ticks the current state of the specified rate monotonic peri
116. CRIPTION This routine re initializes the CPU usage statistics for all tasks in the system to their initial state The initial state is that a task has not executed and thus has consumed no CPU time default state which is when zero period executions have occurred NOTES NONE Chapter 27 Object Services 289 27 Object Services 27 1 Introduction RTEMS provides a collection of services to assist in the management and usage of the objects created and utilized via other managers These services assist in the manipulation of RTEMS objects independent of the API used to create them The object related services provided by RTEMS are e rtems build name build object name from characters e rtems object get classic name lookup name from Id e rtems object get name obtain object name as string e rtems object set name set object name e rtems object id get api obtain API from Id e rtems object id get class obtain class from Id e rtems object id get node obtain node from Id e rtems object id get index obtain index from Id e rtems build id build object id from components e rtems object id api minimum obtain minimum API value e rtems object id api maximum obtain maximum API value e rtems object id api minimum class obtain minimum class value e rtems object id api maximum class obtain maximum class value e rtems object get api name obtain API name e rtems object get api class name obtain class nam
117. EMS OBJECT WAS DELETED queue deleted while waiting DESCRIPTION This directive receives a message from the message queue specified in id The RTEMS WAIT and RTEMS NO WAIT options of the options parameter allow the calling task to specify whether to wait for a message to become available or return immediately For either option if there is at least one message in the queue then it is copied to buffer size is set to return the length of the message in bytes and this directive returns immediately with a successful return code The buffer has to be big enough to receive a message of the maximum length with respect to this message queue If the calling task chooses to return immediately and the queue is empty then a status code indicating this condition is returned If the calling task chooses to wait at the message queue and the queue is empty then the calling task is placed on the message wait queue and blocked If the queue was created with the RTEMS PRIORITY option specified then the calling task is inserted into the wait queue according to its priority But if the queue was created with the RTEMS_FIFO option specified then the calling task is placed at the rear of the wait queue A task choosing to wait at the queue can optionally specify a timeout value in the timeout parameter The timeout parameter specifies the maximum interval to wait before the calling task desires to be unblocked If it is set to RTEMS_NO_TIMEOUT then t
118. EMS C User s Guide from the PTCB free list This data structure is used by RTEMS to manage the newly created partition The number of buffers in the partition is calculated based upon the spec ified partition length and buffer size and returned to the calling task along with a unique partition ID 13 3 2 Obtaining Partition IDs When a partition is created RTEMS generates a unique partition ID and assigned it to the created partition until it is deleted The partition ID may be obtained by either of two methods First as the result of an invocation of the rtems_partition_create directive the partition ID is stored in a user provided location Second the partition ID may be obtained later using the rtems_partition_ident directive The partition ID is used by other partition manager directives to access this partition 13 3 3 Acquiring a Buffer A buffer can be obtained by calling the rtems_partition_get_buffer directive If a buffer is available then it is returned immediately with a successful return code Otherwise an unsuccessful return code is returned immediately to the caller Tasks cannot block to wait for a buffer to become available 13 3 4 Releasing a Buffer Buffers are returned to a partition s free buffer chain with the rtems_partition_return_ buffer directive This directive returns an error status code if the returned buffer was not previously allocated from this partition 13 3 5 Deleting a Partition The rtems_pa
119. EMS allows the Idle Task body to be replaced by a CPU specific implementation a BSP specific implementation or an application specific implementation The Idle Task is preemptible and WILL be preempted when any other task is made ready to execute This characteristic is critical to the overall behavior of any application 4 2 4 Initialization Manager Failure The rtems_fatal_error_occurred directive will be invoked from rtems_initialize_ executive for any of the following reasons e If either the Configuration Table or the CPU Dependent Information Table is not provided e If the starting address of the RTEMS RAM Workspace supplied by the application in the Configuration Table is NULL or is not aligned on a four byte boundary e If the size of the RTEMS RAM Workspace is not large enough to initialize and configure the system e If the interrupt stack size specified is too small e If multiprocessing is configured and the node entry in the Multiprocessor Configu ration Table is not between one and the maximum nodes entry e If a multiprocessor system is being configured and no Multiprocessor Communica tions Interface is specified e If no user initialization tasks are configured At least one initialization task must be configured to allow RTEMS to pass control to the application at the end of the executive initialization sequence e If any of the user initialization tasks cannot be created or started successfully A discussion of
120. ESSFUL as the executive s and zero 0 as the device driver s return code for these device driver entry points Applications can register and unregister drivers with the RTEMS I O manager avoiding the need to have all drivers statically defined and linked into this table The confdefs h entry CONFIGURE MAXIMUM DRIVERS configures the number of driver slots available to the application 172 RTEMS C User s Guide 16 2 2 Major and Minor Device Numbers Each call to the I O manager must provide a device s major and minor numbers as argu ments The major number is the index of the requested driver s entry points in the Device Driver Table and is used to select a specific device driver The exact usage of the minor number is driver specific but is commonly used to distinguish between a number of devices controlled by the same driver The data types rtems_device_major_number and rtems_device_minor_number are used to manipulate device major and minor numbers respectively 16 2 3 Device Names The I O Manager provides facilities to associate a name with a particular device Directives are provided to register the name of a device and to look up the major minor number pair associated with a device name 16 2 4 Device Driver Environment Application developers as well as device driver developers must be aware of the following regarding the RTEMS I O Manager e A device driver routine executes in the context of the invoking task Thus
121. EVENT_ALL RTEMS_NO_WAIT or RTEMS_NO_WAIT The option parameter can be set to RTEMS_NO_WAIT because RTEMS_EVENT_ALL is the default condition for rtems_event_receive 11 3 Operations 11 3 1 Sending an Event Set The rtems_event_send directive allows a task or an ISR to direct an event set to a target task Based upon the state of the target task one of the following situations applies e Target Task is Blocked Waiting for Events Ifthe waiting task s input event condition is satisfied then the task is made ready for execution Ifthe waiting task s input event condition is not satisfied then the event set is posted but left pending and the task remains blocked e Target Task is Not Waiting for Events The event set is posted and left pending 11 3 2 Receiving an Event Set The rtems_event_receive directive is used by tasks to accept a specific input event con dition The task also specifies whether the request is satisfied when all requested events are available or any single requested event is available If the requested event condition is satisfied by pending events then a successful return code and the satisfying event set are returned immediately If the condition is not satisfied then one of the following situations applies e By default the calling task will wait forever for the event condition to be satisfied e Specifying the RTEMS_NO_WAIT option forces an immediate return with an error status code Chapter 11 Eve
122. FLOATING POINT tasks If the supported processor type does not have hardware floating capabilities or a standard numeric coprocessor RTEMS will not provide built in support for hardware floating point on that processor In this case all tasks are considered RTEMS NO FLOATING POINT whether Chapter 5 Task Manager 35 created as RTEMS_FLOATING_POINT or RTEMS_NO_FLOATING_POINT tasks A floating point emulation software library must be utilized for floating point operations On some processors it is possible to disable the floating point unit dynamically If this capability is supported by the target processor then RTEMS will utilize this capability to enable the floating point unit only for tasks which are created with the RTEMS_FLOATING_ POINT attribute The consequence of a RTEMS_NO_FLOATING_POINT task attempting to access the floating point unit is CPU dependent but will generally result in an exception condition 5 2 8 Per Task Variables Per task variables are used to support global variables whose value may be unique to a task After indicating that a variable should be treated as private i e per task the task can access and modify the variable but the modifications will not appear to other tasks and other tasks modifications to that variable will not affect the value seen by the task This is accomplished by saving and restoring the variable s value each time a task switch occurs to or from the calling task The value seen
123. ING SEQUENCE void rtems_interrupt_enable rtems_interrupt_level level 3 DIRECTIVE STATUS CODES NONE DESCRIPTION This directive enables maskable interrupts to the level which was returned by a previous call to rtems_interrupt_disable Immediately prior to invoking this directive maskable interrupts should be disabled by a call to rtems_interrupt_disable and will be enabled when this directive returns to the caller NOTES This directive will not cause the calling task to be preempted 68 RTEMS C User s Guide 6 4 4 INTERRUPT_FLASH Flash Interrupts CALLING SEQUENCE void rtems_interrupt_flash rtems_interrupt_level level 3 DIRECTIVE STATUS CODES NONE DESCRIPTION This directive temporarily enables maskable interrupts to the level which was returned by a previous call to rtems_interrupt_disable Immediately prior to invoking this directive maskable interrupts should be disabled by a call to rtems_interrupt_disable and will be redisabled when this directive returns to the caller NOTES This directive will not cause the calling task to be preempted Chapter 6 Interrupt Manager 69 6 4 5 INTERRUPT IS IN PROGRESS Is an ISR in Progress CALLING SEQUENCE bool rtems interrupt is in progress void DIRECTIVE STATUS CODES NONE DESCRIPTION This directive returns TRUE if the processor is currently servicing an interrupt and FALSE otherwise A return value of TRUE indicates that the caller is an interru
124. INT task because of the relatively large amount of time required for the numeric coprocessor to save or restore its computational state Since RTEMS was designed specifically for embedded military applications which are float ing point intensive the executive is optimized to avoid unnecessarily saving and restoring the state of the numeric coprocessor The state of the numeric coprocessor is only saved when a RTEMS FLOATING POINT task is dispatched and that task was not the last task to utilize the coprocessor In a system with only one RTEMS FLOATING POINT task the state of the numeric coprocessor will never be saved or restored Although the overhead imposed by RTEMS FLOATING POINT tasks is minimal some applica tions may wish to completely avoid the overhead associated with RTEMS FLOATING POINT tasks and still utilize a numeric coprocessor By preventing a task from being preempted while performing a sequence of floating point operations a RTEMS NO FLOATING POINT task can utilize the numeric coprocessor without incurring the overhead of a RTEMS FLOATING POINT context switch This approach also avoids the allocation of a floating point context area However if this approach is taken by the application designer NO tasks should be created as RTEMS FLOATING POINT tasks Otherwise the floating point context will not be correctly maintained because RTEMS assumes that the state of the numeric coprocessor will not be altered by RTEMS NO
125. Interface Layer The Multiprocessor Communications Interface Layer MPCI is a set of user provided proce dures which enable the nodes in a multiprocessor system to communicate with one another These routines are invoked by RTEMS at various times in the preparation and processing of remote requests Interrupts are enabled when an MPCI procedure is invoked It is assumed that if the execution mode and or interrupt level are altered by the MPCI layer that they will be restored prior to returning to RTEMS The MPCI layer is responsible for managing a pool of buffers called packets and for sending these packets between system nodes Packet buffers contain the messages sent between the nodes Typically the MPCI layer will encapsulate the packet within an envelope which contains the information needed by the MPCI layer The number of packets available is dependent on the MPCI layer implementation The entry points to the routines in the user s MPCI layer should be placed in the Multi processor Communications Interface Table The user must provide entry points for each of the following table entries in a multiprocessor system e initialization initialize the MPCI e get packet obtain a packet buffer e return packet return a packet buffer e send packet send a packet to another node e receive packet called to get an arrived packet A packet is sent by RTEMS in each of the following situations e an RQ is generated on an originating node e
126. Iterate Over Tasks CALLING SEQUENCE typedef void rtems_per_thread_routine Thread_Control the_thread E void rtems iterate over all threads rtems per thread routine routine 25 DIRECTIVE STATUS CODES NONE DESCRIPTION This directive iterates over all of the existant threads in the system and invokes routine on each of them The user should be careful in accessing the contents of the thread This routine is intended for use in diagnostic utilities and is not intented for routine use in an operational system NOTES There is NO protection while this routine is called Thus it is possible that the thread could be deleted while this is operating By not having protection the user is free to invoke support routines from the C Library which require semaphores for data structures Chapter 5 Task Manager 57 5 4 17 TASK VARIABLE ADD Associate per task variable CALLING SEQUENCE rtems status code rtems task variable add rtems id tid void task variable void dtor void Mg DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL per task variable added successfully RTEMS_INVALID_ADDRESS task_variable is NULL RTEMS_INVALID_ID invalid task id RTEMS_NO_MEMORY invalid task id RTEMS_ILLEGAL_ON_REMOTE_OBJECT not supported on remote tasks DESCRIPTION This directive adds the memory location specified by the ptr argument to the context of the given task The variable will then be private to the task The task
127. LID_ADDRESS error code The file lt rtems confdefs h gt will calculate the value that is specified as the work_space_ size parameter of the Configuration Table There are many parameters the application developer can specify to help rtems confdefs h in its calculations Correctly specifying the application requirements via parameters such as CONFIGURE_EXTRA_TASK_STACKS and CONFIGURE_MAXIMUM_TASKS is critical The allocation of objects can operate in two modes The default mode has an object number ceiling No more than the specified number of objects can be allocated from the RTEMS RAM Workspace The number of objects specified in the particular API Configuration table fields are allocated at initialisation The second mode allows the number of objects to grow to use the available free memory in the RTEMS RAM Workspace The auto extending mode can be enabled individually for each object type by using the macro rtems_resource_unlimited This takes a value as a parameter and is used to set the object maximum number field in an API Configuration table The value is an allocation unit size When RTEMS is required to grow the object table it is grown by this size The kernel will return the object memory back to the RTEMS RAM Workspace when an object is destroyed The kernel will only return an allocated block of objects to the RTEMS RAM Workspace if at least half the allocation size of free objects remain allocated RTEMS always keeps one allocation
128. LOCAL 102 RTEMS C User s Guide RTEMS_PRIORITY The attribute_set parameter can be set to RTEMS_PRIORITY because RTEMS_LOCAL is the default for all created tasks If a similar semaphore were to be known globally then the attribute_set parameter would be RTEMS_GLOBAL RTEMS_PRIORITY 9 2 6 Building a SEMAPHORE_OBTAIN Option Set In general an option is built by a bitwise OR of the desired option components The set of valid options for the rtems_semaphore_obtain directive are listed in the following table e RTEMS_WAIT task will wait for semaphore default e RTEMS_NO_WAIT task should not wait Option values are specifically designed to be mutually exclusive therefore bitwise OR and addition operations are equivalent as long as each attribute appears exactly once in the component list An option listed as a default is not required to appear in the list although it is a good programming practice to specify default options If all defaults are desired the option RTEMS_DEFAULT_OPTIONS should be specified on this call This example demonstrates the option parameter needed to poll for a semaphore The option parameter passed to the rtems_semaphore_obtain directive should be RTEMS_NO_ WAIT 9 3 Operations 9 3 1 Creating a Semaphore The rtems_semaphore_create directive creates a binary or counting semaphore with a user specified name as well as an initial count If a binary semaphore is created with a count of zero 0 to indicate t
129. MS_SIMPLE_BINARY_SEMAPHORE restrict values to 0 and 1 block on nested ac cess allow deletion of locked semaphore e RTEMS_NO_INHERIT_PRIORITY do not use priority inheritance default 106 RTEMS C User s Guide RTEMS_INHERIT_PRIORITY use priority inheritance RTEMS_PRIORITY_CEILING use priority ceiling RTEMS_NO_PRIORITY_CEILING do not use priority ceiling default RTEMS_LOCAL local task default RTEMS_GLOBAL global task Semaphores should not be made global unless remote tasks must interact with the created semaphore This is to avoid the system overhead incurred by the creation of a global semaphore When a global semaphore is created the semaphore s name and id must be transmitted to every node in the system for insertion in the local copy of the global object table The total number of global objects including semaphores is limited by the maxi mum global objects field in the Configuration Table Chapter 9 Semaphore Manager 107 9 4 2 SEMAPHORE_IDENT Get ID of a semaphore CALLING SEQUENCE rtems_status_code rtems_semaphore_ident rtems_name name uint32_t node rtems id id Jz DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL semaphore identified successfully RTEMS_INVALID_NAME semaphore name not found RTEMS_INVALID_NODE invalid node id DESCRIPTION This directive obtains the semaphore id associated with the semaphore name If the semaphore name is not unique then the semaph
130. NTERRUPT ENABLE Enable Interrupts 67 6 4 8 INTERRUPT FLASH Flash Interrupts 68 6 4 5 INTERRUPT IS IN PROGRESS Is an ISR in Progress nem 69 7 Clock NIGNOEOED 454 645 ot er n obo uon oi 71 T l Introduction nee emere rete Late ees OEE EEE ri 1 2 Backgrounds secco Gees Senne Re ver PER E desea ral 7 2 1 Required Support essees eiiean bu Sedna easing Rte enia fa 7 2 2 Time and Date Data Structures 00 0 2 ee eee ra 7 2 3 Clock Tick and Timeslicing 0 02 eee eee eee 72 BJ HET 72 14 2 5 TimneoulsSiiicireneseeee e ER od dad taeda aeeetarasesddn wud 72 Ta Operations dake yaaaduaasaweetilevsdidadudnnenans dd ioci dul 2 1 9 1 Announcing a Tick sweet e 12 1 9 2 Setting the Time suu ee Rr Race ORE IUS T3 1 9 8 Obtaining the Time 62 iisice tr erem REDI trae 73 LA loni P T3 7 4 1 CLOCK_SET Set date and time 000 74 7 4 2 CLOCK GET Get date and time information ri 7 4 3 CLOCK GET TOD Get date and time in TOD format 76 7 4 4 CLOCK GET TOD TIMEVAL Get date and time in timeval formiab te RERDPPEPUU LUC a ac dunes Th 7 4 5 CLOCK_GET_SECONDS_SINCE_EPOCH Get seconds SCE Epo hesusei estes REPE P RA UL a CORE PR DER dedu 78 7 46 CLOCK_GET_TICKS_PER_SECOND Get ticks per second rrr 79 iv RTEMS C User s Guide 7 4 7 CLOCK_GET_TICKS_SINCE_BOOT Get ticks since boot 80 7 4
131. N_PORTS is the maximum number of ITRON API ports that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_ITRON_MEMORY_POOLS is the maximum number of ITRON API memory pools that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_ITRON_FIXED_MEMORY_POOLS is the maximum number of ITRON API fixed memory pools that can be concurrently active The default is 0 23 2 11 ITRON Initialization Task Table Configuration The rtems confdefs h configuration system can automatically generate an ITRON Ini tialization Tasks Table named ITRON_Initialization_tasks with a single entry The following parameters control the generation of that table CONFIGURE_ITRON_INIT_TASK_TABLE is defined if the user wishes to use a ITRON API Initialization Tasks Table The application may choose to use the initialization tasks or threads table from another API By default this field is not defined as the user MUST select their own API for initialization tasks CONFIGURE_ITRON_HAS_OWN_INIT_TASK_TABLE is defined if the user wishes to define their own ITRON API Initialization Tasks Table This table should be named ITRON_Initialization_tasks By default this is not defined 250 RTEMS C User s Guide CONFIGURE_ITRON_INIT_TASK_ENTRY_POINT is the entry point a k a function name of the single initialization task defined by the ITRON API Initialization Tasks Table By default the value is ITRON_Init CONFIGURE_ITRON_INIT_TASK_ATTRIBU
132. OINT does not use coprocessor default e RTEMS_FLOATING_POINT uses numeric coprocessor e RTEMS_LOCAL local task default e RTEMS_GLOBAL global task Attribute values are specifically designed to be mutually exclusive therefore bitwise OR and addition operations are equivalent as long as each attribute appears exactly once in 36 RTEMS C User s Guide the component list A component listed as a default is not required to appear in the component list although it is a good programming practice to specify default components If all defaults are desired then RTEMS_DEFAULT_ATTRIBUTES should be used This example demonstrates the attribute_set parameter needed to create a local task which utilizes the numeric coprocessor The attribute_set parameter could be RTEMS_FLOATING_ POINT or RTEMS_LOCAL RTEMS_FLOATING_POINT The attribute_set parameter can be set to RTEMS_FLOATING_POINT because RTEMS_LOCAL is the default for all created tasks If the task were global and used the numeric coprocessor then the attribute_set parameter would be RTEMS_GLOBAL RTEMS_FLOATING_POINT 5 2 10 Building a Mode and Mask In general a mode and its corresponding mask is built by a bitwise OR of the desired components The set of valid mode constants and each mode s corresponding mask constant is listed below e RTEMS_PREEMPT is masked by RTEMS_PREEMPT_MASK and enables preemption e RTEMS_NO_PREEMPT is masked by RTEMS_PREEMPT_MASK and disables preempti
133. ONFIGURE_IDLE_TASK_BODY is set to the method name corresponding to the ap plication specific IDLE thread body If not specified the BSP or RTEMS default IDLE thread body will be used The default value is NULL CONFIGURE_IDLE_TASK_STACK_SIZE is set to the desired stack size for the IDLE task If not specified the IDLE task will have a stack of minimum size The default value is the configured minimum stack size CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION is set to indicate that the user has configured NO user initialization tasks or threads and that the user provided IDLE task will perform application initialization and then transform itself into an IDLE task If you use this option be careful the user IDLE task CANNOT block at all during the initialization sequence Further once application initialization is complete it must make itself preemptible and enter an IDLE body loop By default this is not the mode of operation and the user is assumed to provide one or more initialization tasks 23 2 4 Device Driver Table This section defines the configuration parameters related to the automatic generation of a Device Driver Table As rtems confdefs h only is aware of a small set of standard device drivers the generated Device Driver Table is suitable for simple applications with no custom device drivers CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE is defined if the application wishes to provide their own Device Driver Table The table generated is an
134. ONVERT thirty two 32 quantities of the packet e The RTEMS data component of the packet must be in native endian format Endian conversion may be performed by either the sending or receiving MPCI layer e RTEMS makes no assumptions regarding the application data component of the packet 24 4 Operations 24 4 1 Announcing a Packet The rtems multiprocessing announce directive is called by the MPCI layer to inform RTEMS that a packet has arrived from another node This directive can be called from an interrupt service routine or from within a polling routine 24 5 Directives This section details the additional directives required to support RTEMS in a multiprocessor configuration A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes 278 RTEMS C User s Guide 24 5 1 MULTIPROCESSING_ANNOUNCE Announce the arrival of a packet CALLING SEQUENCE void rtems_multiprocessing_announce void DIRECTIVE STATUS CODES NONE DESCRIPTION This directive informs RTEMS that a multiprocessing communications packet has arrived from another node This directive is called by the user provided MPCI and is only used in multiprocessor configurations NOTES This directive is typically called from an ISR This directive will almost certainly cause the calling task to be preempted This directive does not generate activity on remote nodes Chapter 2
135. QUENCE rtems_status_code rtems_region_extend rtems_id id void starting_address uint32_t length DIRECTIVE STATUS CODES RTEMS SUCCESSFUL region extended successfully RTEMS INVALID ADDRESS starting address is NULL RTEMS INVALID ID invalid region id RTEMS INVALID ADDRESS invalid address of area to add DESCRIPTION This directive adds the memory which starts at starting address for length bytes to the region specified by id NOTES This directive will not cause the calling task to be preempted The calling task does not have to be the task that created the region Any local task that knows the region id can extend the region Chapter 14 Region Manager 157 14 4 5 REGION_GET_SEGMENT Get segment from a region CALLING SEQUENCE rtems status code rtems region get segment rtems id id uint32 t size rtems option option set rtems interval timeout void segment DIRECTIVE STATUS CODES RTEMS SUCCESSFUL segment obtained successfully RTEMS INVALID ADDRESS segment is NULL RTEMS INVALID ID invalid region id RTEMS INVALID SIZE request is for zero bytes or exceeds the size of maximum segment which is possible for this region RTEMS UNSATISFIED segment of requested size not available RTEMS TIMEOUT timed out waiting for segment RTEMS OBJECT WAS DELETED semaphore deleted while waiting DESCRIPTION This directive obtains a variable size segment from
136. QUISITE_DRIVERS TERETE eae un Rd tales eae ease 246 CONFIGURE_BSP_PREREQUISITE_DRIVERS 246 CONFIGURE_DISABLE_CLASSIC_NOTEPADS 247 CONFIGURE EXECUTIVE RAM WORK AREA 243 CONFIGURE_EXTRA_TASK_STACKS 244 CONFIGURE GNAT RTEMS 00 250 CONFIGURE HAS OWN CONFIGURATION TABLE 243 CONFIGURE HAS OWN DEVICE DRIVER TABLE 245 CONFIGURE HAS OWN INIT TASK TABLE 247 CONFIGURE_HAS_OWN_MOUNT_TABLE 242 CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE E EE AE ee ee ee ee are 246 CONFIGURE_IDLE_TASK_BODY 245 CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION nr 245 CONFIGURE IDLE TASK STACK SIZE 245 CONFIGURE INIT TASK ARGUMENTS 248 CONFIGURE INIT TASK ATTRIBUTES 247 CONFIGURE_INIT_TASK_ENTRY_POINT 248 CONFIGURE_INIT_TASK_INITIAL_MODES 248 CONFIGURE_INIT_TASK_NAME 247 CONFIGURE_INIT_TASK_PRIORITY 247 CONFIGURE INIT TASK STACK SIZE 247 CONFIGURE INTERRUPT STACK SIZE 243 CONFIGURE ITRON HAS OWN INIT TASK TABLE acl Gebel Blea E E a tee maha a bue emet 249 CONFIGURE_ITRON_INIT_TASK_ATTRIBUTES 250 CONFIGURE_ITRON_INIT_TASK_ENTRY_POINT 249 CONFIGURE_ITRON_INIT_TASK_PRIORITY 250 CONFIGURE_ITRON_INIT_TASK_STACK_SIZE 250 CONFIGURE_ITRON_INIT_TASK_TABLE 249 CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS EE aphid pcd
137. RESS invalid driver table RTEMS_INVALID_NUMBER invalid major device number RTEMS_TOO_MANY no available major device table slot RTEMS_RESOURCE_IN_USE major device number entry in use DESCRIPTION This directive attempts to add a new device driver to the Device Driver Table The user can specify a specific major device number via the directive s major parameter or let the registration routine find the next available major device number by specifing a major number of 0 The selected major device number is returned via the registered_major directive parameter The directive automatically allocation major device numbers from the highest value down This directive automatically invokes the IO_INITIALIZE directive if the driver address table has an initialization and open entry The directive returns RTEMS TOO MANY if Device Driver Table is full and RTEMS RESOURCE IN USE if a specific major device number is requested and it is al ready in use NOTES The Device Driver Table size is specified in the Configuration Table condiguration This needs to be set to maximum size the application requires 176 RTEMS C User s Guide 16 4 2 IO UNREGISTER DRIVER Unregister a device driver CALLING SEQUENCE rtems status code rtems io unregister driver rtems device major number major 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL successfully registered RTEMS INVALID NUMBER invalid major device number DESCRIPTION Thi
138. RIPTION This directive looks up the private value of a task variable for a specified task and stores that value in the location pointed to by the result argument The specified task is usually not the calling task which can get its private value by directly accessing the variable NOTES If you change memory which task_variable_value points to remember to declare that memory as volatile so that the compiler will optimize it correctly In this case both the pointer task_variable_value and data referenced by task_variable_value should be considered volatile Chapter 5 Task Manager 59 5 4 19 TASK VARIABLE DELETE Remove per task variable CALLING SEQUENCE rtems status code rtems task variable delete rtems id id void task variable DIRECTIVE STATUS CODES RTEMS SUCCESSFUL per task variable added successfully RTEMS INVALID ID invalid task id RTEMS NO MEMORY invalid task id RTEMS INVALID ADDRESS task variable is NULL RTEMS ILLEGAL ON REMOTE OBJECT not supported on remote tasks DESCRIPTION This directive removes the given location from a task s context NOTES NONE Chapter 6 Interrupt Manager 61 6 Interrupt Manager 6 1 Introduction Any real time executive must provide a mechanism for quick response to externally gen erated interrupts to satisfy the critical time constraints of the application The interrupt manager provides this mechanism for RTEMS This manager permits quick inter
139. RITY is the initial priority of the single initialization task If this macro is not defined by the application then this defaults to 1 e CONFIGURE_INIT_TASK_ATTRIBUTES is the attributes of the single initialization task If this macro is not defined by the application then this defaults to RTEMS_DEFAULT_ ATTRIBUTES e CONFIGURE_INIT_TASK_ENTRY_POINT is the entry point of the single initialization task If this macro is not defined by the application then this defaults to the C language routine Init e CONFIGURE_INIT_TASK_INITIAL_MODES is the initial execu tion modes of the single initialization task If this macro is not defined by the application then this defaults to RTEMS_ NO_PREEMPT Chapter 23 Configuring a System 257 e CONFIGURE_INIT_TASK_ARGUMENTS is the argument passed to the of the single initialization task If this macro is not defined by the application then this defaults to 0 has the option to have value for this field corresponds to the setting of the macro User initialization tasks table is the address of the Initialization Task Table This table contains the information needed to create and start each of the initialization tasks The format of this table will be discussed below When using the rtems confdefs h mechanism for configuring an RT EMS appli cation the value for this field corresponds to the setting of the macro CONFIGURE EXECUTIVE RAM WORK AREA 23 5 POSIX API Configuration Tab
140. RTEMS e RTEMS_PREEMPT is masked by RTEMS PREEMPT MASK and enables preemption e RTEMS NO PREEMPT is masked by RTEMS_PREEMPT_MASK and disables preemption e RTEMS NO TIMESLICE is masked by RTEMS TIMESLICE MASK and disables timeslicing e RTEMS TIMESLICE is masked by RTEMS TIMESLICE MASK and enables timeslicing e RTEMS ASR is masked by RTEMS_ASR_MASK and enables ASR processing e RTEMS NO ASR is masked by RTEMS_ASR_MASK and disables ASR processing e RTEMS INTERRUPT LEVEL O is masked by RTEMS INTERRUPT MASK and enables all interrupts e RTEMS INTERRUPT LEVEL n is masked by RTEMS_INTERRUPT_MASK and sets inter rupts level n Chapter 12 Signal Manager 139 12 4 2 SIGNAL_SEND Send signal set to a task CALLING SEQUENCE rtems_status_code rtems_signal_send rtems_id id rtems_signal_set signal_set DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL signal sent successfully RTEMS_INVALID_ID task id invalid RTEMS_INVALID_NUMBER empty signal set RTEMS_NOT_DEFINED ASR invalid DESCRIPTION This directive sends a signal set to the task specified in id The signal_set parameter contains the signal set to be sent to the task If a caller sends a signal set to a task with an invalid ASR then an error code is returned to the caller If a caller sends a signal set to a task whose ASR is valid but disabled then the signal set will be caught and left pending for the ASR to process when it is enabled If a caller sends a s
141. RTEMS C User s Guide Edition 4 9 2 for RTEMS 4 9 2 12 March 2009 On Line Applications Research Corporation On Line Applications Research Corporation TEXinfo 2007 12 02 17 COPYRIGHT 1988 2008 On Line Applications Research Corporation OAR 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 http www rtems com Any inquiries concerning RTEMS its related support components its documentation or any custom services for RTEMS should be directed to the contacts listed on that site A current list of RTEMS Support Providers is at http www rtems com support html Table of Contents lc ee ee ee ee eee er ee eee ere 1 1 Overview oc yee eu a aoa a cR ui 8 ie AR RR o a oes 9 1 1 Introduetionz nieve nre r RR E ERES rt REPRE 5 1 2 Real time Application Systems 0 0 cece eee eee eee 5 1 3 Real time Executive 0 ccc cece cece nee
142. RTEMS WAIT task will wait for event default e RTEMS NO WAIT task should not wait e RTEMS EVENT ALL return after all events default e RTEMS EVENT ANY return after any events A clock tick is required to support the functionality of this directive Chapter 12 Signal Manager 135 12 Signal Manager 12 1 Introduction The signal manager provides the capabilities required for asynchronous communication The directives provided by the signal manager are e rtems_signal_catch Establish an ASR e rtems_signal_send Send signal set to a task 12 2 Background 12 2 1 Signal Manager Definitions The signal manager allows a task to optionally define an asynchronous signal routine ASR An ASR is to a task what an ISR is to an application s set of tasks When the processor is interrupted the execution of an application is also interrupted and an ISR is given control Similarly when a signal is sent to a task that task s execution path will be interrupted by the ASR Sending a signal to a task has no effect on the receiving task s current execution state A signal flag is used by a task or ISR to inform another task of the occurrence of a significant situation Thirty two signal flags are associated with each task A collection of one or more signals is referred to as a signal set The data type rtems_signal_set is used to manipulate signal sets A signal set is posted when it is directed or sent to a task A pending sign
143. RTEMS may reuse the task ID for another task which is created later in the application Unexpired delay timers i e those used by rtems_task_wake_after and rtems_task_ wake_when and timeout timers associated with the task are automatically deleted how ever other resources dynamically allocated by the task are NOT automatically returned to RTEMS Therefore before a task is deleted all of its dynamically allocated resources should be deallocated by the user This may be accomplished by instructing the task to Chapter 5 Task Manager 39 delete itself rather than directly deleting the task Other tasks may instruct a task to delete itself by sending a delete self message event or signal or by restarting the task with special arguments which instruct the task to delete itself 5 4 Directives This section details the task manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes 40 RTEMS C User s Guide 5 4 1 TASK_CREATE Create a task CALLING SEQUENCE rtems_status_code rtems_task_create rtems_name name rtems_task_priority initial_priority size_t stack_size rtems_mode initial_modes rtems_attribute attribute_set rtems_id id Js DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL task created successfully RTEMS_INVALID_ADDRESS id is NULL RTEMS_INVALID_NAME invalid task name RTEMS_INVALID_PRIORITY invali
144. RTEMS_SIGNAL_15 RTEMS_SIGNAL_31 12 2 4 Building an ASR Mode In general an ASR s mode is built by a bitwise OR of the desired mode components The set of valid mode components is the same as those allowed with the task_create and task_mode directives A complete list of mode options is provided in the following table e RTEMS_PREEMPT is masked by RTEMS_PREEMPT_MASK and enables preemption e RTEMS_NO_PREEMPT is masked by RTEMS_PREEMPT_MASK and disables preemption e RTEMS_NO_TIMESLICE is masked by RTEMS_TIMESLICE_MASK and disables timeslicing e RTEMS_TIMESLICE is masked by RTEMS_TIMESLICE_MASK and enables timeslicing e RTEMS_ASR is masked by RTEMS_ASR_MASK and enables ASR processing e RTEMS_NO_ASR is masked by RTEMS_ASR_MASK and disables ASR processing e RTEMS_INTERRUPT_LEVEL 0 is masked by RTEMS_INTERRUPT_MASK and enables all interrupts e RTEMS_INTERRUPT_LEVEL n is masked by RTEMS_INTERRUPT_MASK and sets inter rupts level n Mode values are specifically designed to be mutually exclusive therefore bitwise OR and addition operations are equivalent as long as each mode appears exactly once in the compo nent list A mode component listed as a default is not required to appear in the mode list although it is a good programming practice to specify default components If all defaults are desired the mode DEFAULT MODES should be specified on this call This example demonstrates the mode parameter used with the rtems signal catch
145. TES is the attribute set of the single initial ization task defined by the ITRON API Initialization Tasks Table By default the value is TA_HLNG CONFIGURE_ITRON_INIT_TASK_PRIORITY is the initial priority of the single initial ization task defined by the ITRON API Initialization Tasks Table By default the value is 1 which is the highest priority in the ITRON API CONFIGURE ITRON INIT TASK STACK SIZE is the stack size of the single initializa tion task defined by the ITRON API Initialization Tasks Table By default value is the configured minimum stack size 23 2 12 Ada Tasks This section defines the system configuration parameters supported by rtems confdefs h related to configuring RTEMS to support a task using Ada tasking with GNAT e CONFIGURE GNAT RTEMS is defined to inform RTEMS that the GNAT Ada run time is to be used by the application This configuration parameter is critical as it makes rtems confdefs h configure the resources mutexes and keys used implicitly by the GNAT run time By default this parameter is not defined CONFIGURE MAXIMUM ADA TASKS is the number of Ada tasks that can be concur rently active in the system By default when CONFIGURE GNAT RTEMS is defined this is set to 20 CONFIGURE MAXIMUM FAKE ADA TASKS is the number of fake Ada tasks that can be concurrently active in the system A fake Ada task is a non Ada task that makes calls back into Ada code and thus implicitly uses the Ada run time
146. TIMER INITIATE SERVER Initiate server for task based timers CALLING SEQUENCE rtems status code rtems timer initiate server uint32 t priority uint32 t Stack size rtems attribute attribute set 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL Timer Server initiated successfully RTEMS TOO MANY too many tasks created DESCRIPTION This directive initiates the Timer Server task This task is responsible for executing all timers initiated via the rtems timer server fire after or rtems timer server fire when directives NOTES This directive could cause the calling task to be preempted The Timer Server task is created using the rtems task create service and must be ac counted for when configuring the system Even through this directive invokes the rtems task create and rtems task start direc tives it should only fail due to resource allocation problems Chapter 8 Timer Manager 95 8 4 8 TIMER SERVER FIRE AFTER Fire task based timer after interval CALLING SEQUENCE rtems status code rtems timer server fire after rtems id id rtems interval ticks rtems timer service routine entry routine void user data DIRECTIVE STATUS CODES RTEMS SUCCESSFUL timer initiated successfully RTEMS INVALID ADDRESS routine is NULL RTEMS INVALID ID invalid timer id RTEMS INVALID NUMBER invalid interval RTEMS INCORRECT STATE Timer Server not initiated DESCRIPTION This directive initiates
147. The barrier id is used by other barrier related directives to access the barrier NOTES This directive will not cause the running task to be preempted 222 RTEMS C User s Guide 20 4 3 BARRIER_DELETE Delete a barrier CALLING SEQUENCE rtems_status_code rtems_barrier_delete rtems_id id DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL barrier deleted successfully RTEMS_INVALID_ID invalid barrier id DESCRIPTION This directive deletes the barrier specified by id All tasks blocked waiting for the barrier to be released will be readied and returned a status code which indicates that the barrier was deleted The BCB for this barrier is reclaimed by RTEMS NOTES The calling task will be preempted if it is enabled by the task s execution mode and a higher priority local task is waiting on the deleted barrier The calling task will NOT be preempted if all of the tasks that are waiting on the barrier are remote tasks The calling task does not have to be the task that created the barrier Any local task that knows the barrier id can delete the barrier Chapter 20 Barrier Manager 223 20 4 4 BARRIER_OBTAIN Acquire a barrier CALLING SEQUENCE rtems_status_code rtems_barrier_wait rtems_id id rtems_interval timeout DIRECTIVE STATUS CODES RTEMS SUCCESSFUL barrier obtained successfully RTEMS UNSATISFIED barrier not available RTEMS TIMEOUT timed out waiting for barrier RTEMS OBJECT WAS DELETED
148. The calling task does not have to be the task that created the port Any local task that knows the port id can delete the port 168 RTEMS C User s Guide 15 4 4 PORT_EXTERNAL_TO_INTERNAL Convert external to internal address CALLING SEQUENCE rtems_status_code rtems_port_external_to_internal rtems_id id void external void internal i DIRECTIVE STATUS CODES RTEMS INVALID ADDRESS internal is NULL RTEMS SUCCESSFUL successful conversion DESCRIPTION This directive converts a dual ported memory address from external to internal represen tation for the specified port If the given external address is invalid for the specified port then the internal address is set to the given external address NOTES This directive is callable from an ISR This directive will not cause the calling task to be preempted Chapter 15 Dual Ported Memory Manager 169 15 4 5 PORT_INTERNAL_TO_EXTERNAL Convert internal to external address CALLING SEQUENCE rtems_status_code rtems_port_internal_to_external rtems_id id void internal void external PE DIRECTIVE STATUS CODES RTEMS INVALID ADDRESS external is NULL RTEMS SUCCESSFUL successful conversion DESCRIPTION This directive converts a dual ported memory address from internal to external represen tation so that it can be passed to owner of the DPMA represented by the specified port If the given internal address is an invalid dual ported address then the ex
149. The mechanical action of the fire button ensures a minimum time period between successive activations but the missile must be launched by a hard deadline 19 2 4 Rate Monotonic Scheduling Algorithm The Rate Monotonic Scheduling Algorithm RMS is important to real time systems de signers because it allows one to guarantee that a set of tasks is schedulable A set of tasks is said to be schedulable if all of the tasks can meet their deadlines RMS provides a set of rules which can be used to perform a guaranteed schedulability analysis for a task set This analysis determines whether a task set is schedulable under worst case conditions and emphasizes the predictability of the system s behavior It has been proven that RMS is an optimal static priority algorithm for scheduling independent pre emptible periodic tasks on a single processor RMS is optimal in the sense that if a set of tasks can be scheduled by any static priority algorithm then RMS will be able to schedule that task set RMS bases it schedulability analysis on the processor utilization level below which all deadlines can be met RMS calls for the static assignment of task priorities based upon their period The shorter a task s period the higher its priority For example a task with a 1 millisecond period has higher priority than a task with a 100 millisecond period If two tasks have the same period then RMS does not distinguish between the tasks However RTEMS specifi
150. This directive associates name with the specified major minor number pair NOTES This directive will not cause the calling task to be preempted Chapter 16 I O Manager 179 16 4 5 IO LOOKUP NAME Lookup a device CALLING SEQUENCE rtems status code rtems io lookup name const char name rtems driver name t device info Jj DIRECTIVE STATUS CODES RTEMS SUCCESSFUL successfully initialized RTEMS UNSATISFIED name not registered DESCRIPTION This directive returns the major minor number pair associated with the given device name in device info NOTES This directive will not cause the calling task to be preempted 180 RTEMS C User s Guide 16 4 6 IO OPEN Open a device CALLING SEQUENCE rtems status code rtems io open rtems device major number major rtems device minor number minor void argument 3 DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL successfully initialized RTEMS_INVALID_NUMBER invalid major device number DESCRIPTION This directive calls the device driver open routine specified in the Device Driver Table for this major number The open entry point is commonly used by device drivers to provide exclusive access to a device NOTES This directive may or may not cause the calling task to be preempted This is dependent on the device driver being invoked Chapter 16 I O Manager 181 16 4 7 IO_CLOSE Close a device CALLING SEQUENCE rtems_status_code rtems_io_close rtems_device_major
151. This is because the region with one segment requires only the overhead for one segment while the other region requires the overhead for two segments Due to automatic coalescing the number of segments in the region dynamically changes Therefore the total overhead required by RTEMS dynamically changes 14 3 2 Obtaining Region IDs When a region is created RTEMS generates a unique region ID and assigns it to the created region until it is deleted The region ID may be obtained by either of two methods First as the result of an invocation of the rtems region create directive the region ID is stored in a user provided location Second the region ID may be obtained later using the rtems region ident directive The region ID is used by other region manager directives to access this region Chapter 14 Region Manager 151 14 3 3 Adding Memory to a Region The rtems_region_extend directive may be used to add memory to an existing region The caller specifies the size in bytes and starting address of the memory being added NOTE Please see the release notes or RTEMS source code for information regarding re strictions on the location of the memory being added in relation to memory already in the region 14 3 4 Acquiring a Segment The rtems_region_get_segment directive attempts to acquire a segment from a specified region If the region has enough available free memory then a segment is returned success fully to the caller When the se
152. When us ing the rtems confdefs h mechanism for configuring an RTEMS application the Multiprocessor Configuration Table is automati cally generated when the CONFIGURE_MP_APPLICATION is defined If CONFIGURE_MP_APPLICATION is not defined the this entry is set to NULL The generated table has the name Multiprocessing_ configuration RTEMS_api_configuration is the address of the RTEMS API Configuration Table This table contains information needed by the RTEMS API This field should be NULL if the RTEMS API is not used NOTE Currently the RTEMS API is required to support support components such as BSPs and libraries which use this API This table is built auto matically and this entry filled in if using the rtems confdefs h application configuration mechanism The generated table has the name Configuration RTEMS API POSIX api configuration is the address of the POSIX API Configuration Table This table contains information needed by the POSIX API This field should be NULL if the POSIX API is not used This table is built au tomatically and this entry filled in if using the rtems confdefs h application configuration mechanism The rtems confdefs h ap plication mechanism will fill this field in with the address of the Configuration POSIX API table of POSIX API is configured and NULL if the POSIX API is not configured 23 4 RTEMS API Configuration Table The RTEMS API Configuration Table is used to configure the managers which con
153. _UNSATISFIED all buffers are allocated DESCRIPTION This directive allows a buffer to be obtained from the partition specified in id The address of the allocated buffer is returned in buffer NOTES This directive will not cause the running task to be preempted All buffers begin on a four byte boundary A task cannot wait on a buffer to become available Getting a buffer from a global partition which does not reside on the local node will generate a request telling the remote node to allocate a buffer from the specified partition 148 RTEMS C User s Guide 13 4 5 PARTITION_RETURN_BUFFER Return buffer toa partition CALLING SEQUENCE rtems status code rtems partition return buffer rtems id id void buffer i DIRECTIVE STATUS CODES RTEMS SUCCESSFUL buffer returned successfully RTEMS INVALID ADDRESS buffer is NULL RTEMS INVALID ID invalid partition id RTEMS INVALID ADDRESS buffer address not in partition DESCRIPTION This directive returns the buffer specified by buffer to the partition specified by id NOTES This directive will not cause the running task to be preempted Returning a buffer to a global partition which does not reside on the local node will generate a request telling the remote node to return the buffer to the specified partition Chapter 14 Region Manager 149 14 Region Manager 14 1 Introduction The region manager provides facilities to dynamically allocate memory in variab
154. _number major rtems_device_minor_number minor void argument DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL successfully initialized RTEMS_INVALID_NUMBER invalid major device number DESCRIPTION This directive calls the device driver close routine specified in the Device Driver Table for this major number The close entry point is commonly used by device drivers to relinquish exclusive access to a device NOTES This directive may or may not cause the calling task to be preempted This is dependent on the device driver being invoked 182 RTEMS C User s Guide 16 4 8 IO_READ Read from a device CALLING SEQUENCE rtems_status_code rtems_io_read rtems_device_major_number major rtems_device_minor_number minor void argument DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL successfully initialized RTEMS_INVALID_NUMBER invalid major device number DESCRIPTION This directive calls the device driver read routine specified in the Device Driver Table for this major number Read operations typically require a buffer address as part of the argument parameter block The contents of this buffer will be replaced with data from the device NOTES This directive may or may not cause the calling task to be preempted This is dependent on the device driver being invoked Chapter 16 I O Manager 183 16 4 9 IO_WRITE Write to a device CALLING SEQUENCE rtems_status_code rtems_io_write rtems_device_major_number major rtems_
155. a NOTES This directive will not cause the running task to be preempted Chapter 8 Timer Manager 97 8 4 10 TIMER_RESET Reset an interval timer CALLING SEQUENCE rtems_status_code rtems_timer_reset rtems_id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL timer reset successfully RTEMS INVALID ID invalid timer id RTEMS NOT DEFINED attempted to reset a when or newly created timer DESCRIPTION This directive resets the timer associated with id This timer must have been previously ini tiated with either the rtems timer fire after or rtems timer server fire after di rective If active the timer is canceled after which the timer is reinitiated using the same in terval and timer service routine which the original rtems timer fire after rtems timer server fire after directive used NOTES If the timer has not been used or the last usage of this timer was by a rtems timer fire when or rtems timer server fire when directive then the RTEMS NOT DEFINED error is returned Restarting a cancelled after timer results in the timer being reinitiated with its previous timer service routine and interval This directive will not cause the running task to be preempted Chapter 9 Semaphore Manager 99 9 Semaphore Manager 9 1 Introduction The semaphore manager utilizes standard Dijkstra counting semaphores to provide syn chronization and mutual exclusion capabilities The directives provided by the semaphore
156. accuracy the time reported will probably be different on every call NOTES This directive may be called from an ISR 82 RTEMS C User s Guide 7 4 9 CLOCK SET NANOSECONDS EXTENSION Install the nanoseconds since last tick handler CALLING SEQUENCE rtems status code rtems clock set nanoseconds extension rtems nanoseconds extension routine routine 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL clock tick processed successfully RTEMS INVALID ADDRESS time buffer is NULL DESCRIPTION This directive is used by the Clock device driver to install the routine which will be invoked by the internal RTEMS method used to obtain a highly accurate time of day It is usually called during the initialization of the driver When the routine is invoked it will determine the number of nanoseconds which have elapsed since the last invocation of the rtems_clock_tick directive It should do this as quickly as possible with as little impact as possible on the device used as a clock source NOTES This directive may be called from an ISR This directive is called as part of every service to obtain the current date and time as well as timestamps Chapter 7 Clock Manager 83 7 4 10 CLOCK_TICK Announce a clock tick CALLING SEQUENCE rtems_status_code rtems_clock_tick void DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL clock tick processed successfully DESCRIPTION This directive announces to RTEMS that a system clock tick has occ
157. ailures due to faulty software is yet another area to be resolved under this environment The Guidance and Control Directorate began a software development effort to address these problems A project to develop an experimental run time kernel was begun that will eliminate the major drawbacks of the Ada programming language mentioned above The Real Time Executive for Multiprocessor Systems RTEMS provides full capabilities for management of tasks interrupts time and multiple processors in addition to those features Preface 3 typical of generic operating systems The code is Government owned so no licensing fees are necessary RTEMS has been implemented in both the Ada and C programming languages It has been ported to the following processor families e Intel i386 and above e Motorola MC68xxx e Motorola MC683xx e Motorola ColdFire e ARM e MIPS e PowerPC e SPARC e Hitachi SH e Hitachi H8 300 e OpenCores OR32 e UNIX Support for other processor families including RISC CISC and DSP is planned Since almost all of RTEMS is written in a high level language ports to additional processor families require minimal effort RTEMS multiprocessor support is capable of handling either homogeneous or heterogeneous systems The kernel automatically compensates for architectural differences byte swapping etc between processors This allows a much easier transition from one processor family to another without a major system redesi
158. ain RTEMS uses two pointers of memory from each buffer as the free buffer chain When a buffer is allocated the entire buffer is available for application use Therefore modifying memory that is outside of an allocated buffer could destroy the free buffer chain or the contents of an adjacent allocated buffer 13 2 2 Building a Partition Attribute Set In general an attribute set is built by a bitwise OR of the desired attribute components The set of valid partition attributes is provided in the following table e RTEMS LOCAL local task default e RTEMS GLOBAL global task Attribute values are specifically designed to be mutually exclusive therefore bitwise OR and addition operations are equivalent as long as each attribute appears exactly once in the component list An attribute listed as a default is not required to appear in the attribute list although it is a good programming practice to specify default attributes If all defaults are desired the attribute RTEMS DEFAULT ATTRIBUTES should be specified on this call The attribute set parameter should be RTEMS GLOBAL to indicate that the partition is to be known globally 13 3 Operations 13 3 1 Creating a Partition The rtems partition create directive creates a partition with a user specified name The partition s name starting address length and buffer size are all specified to the rtems partition create directive RTEMS allocates a Partition Control Block PTCB 142 RT
159. al is a signal that has been sent to a task with a valid ASR but has not been processed by that task s ASR 12 2 2 A Comparison of ASRs and ISRs The format of an ASR is similar to that of an ISR with the following exceptions e ISRs are scheduled by the processor hardware ASRs are scheduled by RTEMS e ISRs do not execute in the context of a task and may invoke only a subset of directives ASRs execute in the context of a task and may execute any directive e When an ISR is invoked it is passed the vector number as its argument When an ASR is invoked it is passed the signal set as its argument e An ASR has a task mode which can be different from that of the task An ISR does not execute as a task and as a result does not have a task mode 12 2 3 Building a Signal Set A signal set is built by a bitwise OR of the desired signals The set of valid signals is RTEMS_SIGNAL_O through RTEMS_SIGNAL_31 If a signal is not explicitly specified in the signal set then it is not present Signal values are specifically designed to be mutually exclusive therefore bitwise OR and addition operations are equivalent as long as each signal appears exactly once in the component list 136 RTEMS C User s Guide This example demonstrates the signal parameter used when sending the signal set consisting of RTEMS_SIGNAL_6 RTEMS_SIGNAL_15 and RTEMS_SIGNAL_31 The signal parameter pro vided to the rtems_signal_send directive should be RTEMS_SIGNAL_6
160. an RTEMS Task e rtems task argument is the data type for the argument passed to each RTEMS task In RT EMS 4 7 and older this is an unsigned thirty two bit integer In RTEMS 4 8 and newer this is based upon the C99 type uintptr t which is guaranteed to be an integer large enough to hold a pointer on the target architecture e rtems task begin extension is the entry point for a task beginning execution user extension handler routine e rtems task create extensionis the entry point for a task creation execution user extension handler routine e rtems task delete extension is the entry point for a task deletion user extension handler routine e rtems task entry is the address of the entry point to an RTEMS ASR It is equiv alent to the entry point of the function implementing the ASR e rtems task exitted extension is the entry point for a task exitted user extension handler routine e rtems task priority is the data type used to manage and manipulate task prior ities e rtems task restart extension is the entry point for a task restart user extension handler routine e rtems task start extension is the entry point for a task start user extension handler routine e rtems task switch extension is the entry point for a task context switch user extension handler routine e rtems tcb is the data structure associated with each task in an RT EMS system e rtems time of day is the data structure used to manage and manipulate calendar
161. an attempt is made to convert an address which lies outside the specified DPMA then the address to be converted will be returned 15 3 4 Deleting a DPMA Port A port can be removed from the system and returned to RTEMS with the rtems_port_ delete directive When a port is deleted its control block is returned to the DPCB free list 15 4 Directives This section details the dual ported memory manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes Chapter 15 Dual Ported Memory Manager 165 15 4 1 PORT_CREATE Create a port CALLING SEQUENCE rtems_status_code rtems_port_create rtems_name name void internal start void external start uint32 t length rtems id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL port created successfully RTEMS INVALID NAME invalid port name RTEMS INVALID ADDRESS address not on four byte boundary RTEMS INVALID ADDRESS id is NULL RTEMS TOO MANY too many DP memory areas created DESCRIPTION This directive creates a port which resides on the local node for the specified DPMA The assigned port id is returned in id This port id is used as an argument to other dual ported memory manager directives to convert addresses within this DPMA For control and maintenance of the port RTEMS allocates and initializes an DPCB from the DPCB free pool T hus memory from th
162. andler and or the RTEMS fatal error handler All fatal error handlers are passed an error code to describe the error detected Occasionally an application requires more sophisticated fatal error processing such as pass ing control to a debugger For these cases a user supplied fatal error handler can be specified in the RTEMS configuration table The User Extension Table field fatal contains the ad dress of the fatal error handler to be executed when the rtems_fatal_error_occurred directive is called If the field is set to NULL or if the configured fatal error handler returns to the executive then the default handler provided by RTEMS is executed This default handler will halt execution on the processor where the error occurred 17 4 Directives This section details the fatal error manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes Chapter 17 Fatal Error Manager 187 17 4 1 FATAL_ERROR_OCCURRED Invoke the fatal error handler CALLING SEQUENCE void volatile rtems fatal error occurred uint32 t the error 25 DIRECTIVE STATUS CODES NONE DESCRIPTION This directive processes fatal errors If the FATAL error extension is defined in the configu ration table then the user defined error extension is called If configured and the provided FATAL error extension returns then the RTEMS default error handler is invoked Th
163. ased 20 2 1 Automatic Versus Manual Barriers Just as with a real world gate barriers may be configured to be manually opened or au tomatically opened All tasks calling the rtems_barrier_wait directive will block until a controlling task invokes the rtems_barrier_release directive Automatic barriers are created with a limit to the number of tasks which may simultaneously block at the barrier Once this limit is reached all of the tasks are released For example if the automatic limit is ten tasks then the first nine tasks calling the rtems_barrier_wait directive will block When the tenth task calls the rtems_barrier_wait directive the nine blocked tasks will be released and the tenth task returns to the caller without blocking 20 2 2 Building a Barrier Attribute Set In general an attribute set is built by a bitwise OR of the desired attribute components The following table lists the set of valid barrier attributes e RTEMS_BARRIER_AUTOMATIC_RELEASE automatically release the barrier when the configured number of tasks are blocked e RTEMS_BARRIER_MANUAL_RELEASE only release the barrier when the application invokes the rtems barrier release directive default 218 RTEMS C User s Guide NOTE Barriers only support FIFO blocking order because all waiting tasks are released as a set Thus the released tasks will all become ready to execute at the same time and compete for the processor based upon their priority Attribute
164. ask is made ready If preemption is enabled RTEMS_PREEMPT and a higher priority task is made ready then the processor will be taken away from the current task immediately and given to the higher priority task The timeslicing component is used by the RTEMS scheduler to determine how the processor is allocated to tasks of equal priority If timeslicing is enabled RTEMS_TIMESLICE then RTEMS will limit the amount of time the task can execute before the processor is allocated to another ready task of equal priority The length of the timeslice is application dependent and specified in the Configuration Table If timeslicing is disabled RTEMS_NO_TIMESLICE then the task will be allowed to execute until a task of higher priority is made ready If RTEMS_NO_PREEMPT is selected then the timeslicing component is ignored by the scheduler The asynchronous signal processing component is used to determine when received signals are to be processed by the task If signal processing is enabled RTEMS_ASR then signals sent to the task will be processed the next time the task executes If signal processing is disabled RTEMS_NO_ASR then all signals received by the task will remain posted until signal processing is enabled This component affects only tasks which have established a routine to process asynchronous signals The interrupt level component is used to determine which interrupts will be enabled when the task is executing RTEMS_INTERRUPT_LEVEL n s
165. ask will be scheduled according to its new priority The rtems_task_restart directive resets the priority of a task to its original value 5 3 7 Changing Task Mode The rtems_task_mode directive is used to obtain or change the current execution mode of the calling task A task s execution mode is used to enable preemption timeslicing ASR processing and to set the task s interrupt level The rtems_task_restart directive resets the mode of a task to its original value 5 3 8 Notepad Locations RTEMS provides sixteen notepad locations for each task Each notepad location may contain a note consisting of four bytes of information RTEMS provides two directives rtems_task_set_note and rtems_task_get_note that enable a user to access and change the notepad locations The rtems_task_set_note directive enables the user to set a task s notepad entry to a specified note The rtems_task_get_note directive allows the user to obtain the note contained in any one of the sixteen notepads of a specified task 5 3 9 Task Deletion RTEMS provides the rtems_task_delete directive to allow a task to delete itself or any other task This directive removes all RTEMS references to the task frees the task s control block removes it from resource wait queues and deallocates its stack as well as the optional floating point context The task s name and ID become inactive at this time and any subsequent references to either of them is invalid In fact
166. asks The rtems_task_create directive creates a task by allocating a task control block assigning the task a user specified name allocating it a stack and floating point context area setting Chapter 5 Task Manager 37 a user specified initial priority setting a user specified initial mode and assigning it a task ID Newly created tasks are initially placed in the dormant state All RTEMS tasks execute in the most privileged mode of the processor 5 3 2 Obtaining Task IDs When a task is created RTEMS generates a unique task ID and assigns it to the created task until it is deleted The task ID may be obtained by either of two methods First as the result of an invocation of the rtems_task_create directive the task ID is stored in a user provided location Second the task ID may be obtained later using the rtems_task_ident directive The task ID is used by other directives to manipulate this task 5 3 3 Starting and Restarting Tasks The rtems_task_start directive is used to place a dormant task in the ready state This enables the task to compete based on its current priority for the processor and other system resources Any actions such as suspension or change of priority performed on a task prior to starting it are nullified when the task is started With the rtems_task_start directive the user specifies the task s starting address and argument The argument is used to communicate some startup information to the task As part
167. asks an application is required to define at least one A typical initialization task will create and start the static set of application tasks It may also create any other objects used by the application Initialization tasks which only perform initialization should delete themselves upon completion to free resources for other tasks Initialization tasks may transform themselves into a normal application task This transformation typically involves changing priority and execution mode RTEMS does not automatically delete the initialization tasks 4 2 2 System Initialization System Initialization begins with board reset and continues through RTEMS initialization initialization of all device drivers and eventually a context switch to the first user task Remember that interrupts are disabled during initialization and the initialization thread is not a task in any sense and the user should be very careful during initialzation The BSP must ensure that the there is enough stack space reserved for the initialization thread to successfully execute the initialization routines for all device drivers and in multiprocessor configurations the Multiprocessor Communications Interface Layer initial ization routine 24 RTEMS C User s Guide 4 2 3 The Idle Task The Idle Task is the lowest priority task in a system and executes only when no other task is ready to execute This default implementation of this task consists of an infinite loop RT
168. ata structure used to dynamically allocate and deallocate variable sized blocks of memory heterogeneous A multiprocessor computer system composed of dissimilar proces sors homogeneous A multiprocessor computer system composed of a single type of pro cessor 340 ID IDLE task interface internal address interrupt interrupt level RTEMS C User s Guide An RTEMS assigned identification tag used to access an active ob ject A special low priority task which assumes control of the CPU when no other task is able to execute A specification of the methodology used to connect multiple inde pendent subsystems The address used to access dual ported memory by the node which owns the memory A hardware facility that causes the CPU to suspend execution save its status and transfer control to a specific location A mask used to by the CPU to determine which pending interrupts should be serviced If a pending interrupt is below the current inter rupt level then the CPU does not recognize that interrupt Interrupt Service Routine I O ISR kernel list little endian local local operation logical address loosely coupled major number manager memory pool message An ISR is invoked by the CPU to process a pending interrupt An acronym for Input Output An acronym for Interrupt Service Routine In this document this term is used as a synonym for executive A data structure which allows
169. ated directives to access the message queue NOTES This directive will not cause the running task to be preempted If node is RTEMS_SEARCH_ALL_NODES all nodes are searched with the local node being searched first All other nodes are searched with the lowest numbered node searched first If node is a valid node number which does not represent the local node then only the message queues exported by the designated node are searched This directive does not generate activity on remote nodes It accesses only the local copy of the global object table 120 RTEMS C User s Guide 10 4 3 MESSAGE QUEUE DELETE Delete a queue CALLING SEQUENCE rtems status code rtems message queue delete rtems_id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL queue deleted successfully RTEMS INVALID ID invalid queue id RTEMS ILLEGAL ON REMOTE OBJECT cannot delete remote queue DESCRIPTION This directive deletes the message queue specified by id As a result of this directive all tasks blocked waiting to receive a message from this queue will be readied and returned a status code which indicates that the message queue was deleted If no tasks are waiting but the queue contains messages then RTEMS returns these message buffers back to the system message buffer pool The QCB for this queue as well as the memory for the message buffers is reclaimed by RTEMS NOTES The calling task will be preempted if its preemption mode is enab
170. b current task rtems tcb deleted task J where current_task can be used to access the TCB for the currently executing task and deleted_task can be used to access the TCB for the task being deleted This extension is invoked from the task_delete directive after the TCB has been removed from a ready TCB chain but before all its resources including the TCB have been returned to their respective free pools This extension should not call any RTEMS directives if a task is deleting itself current_task is equal to deleted task 22 2 3 5 TASK SWITCH Extension The TASK_SWITCH extension corresponds to a task context switch If this extension is defined in any static or dynamic extension set and a task context switch is in progress then the extension routine will automatically be invoked by RTEMS The extension should have a prototype similar to the following rtems_extension user_task_switch rtems_tcb current_task rtems_tcb heir_task where current_task can be used to access the TCB for the task that is being swapped out and heir_task can be used to access the TCB for the task being swapped in This extension is invoked from RTEMS dispatcher routine after the current task context has been saved but before the heir task context has been restored This extension should not call any RTEMS directives Chapter 22 User Extensions Manager 235 22 2 3 6 TASK BEGIN Extension The TASK_BEGIN extension is invoked when a task begins
171. be disabled and ISRs which execute at this level MUST NEVER issue RTEMS system calls If a directive is invoked unpredictable results may occur due to the inability of RTEMS to protect its critical sections However ISRs that make no system calls may safely execute as non maskable interrupts 6 3 Operations 6 3 1 Establishing an ISR The rtems_interrupt_catch directive establishes an ISR for the system The address of the ISR and its associated CPU vector number are specified to this directive This directive installs the RTEMS interrupt wrapper in the processor s Interrupt Vector Table and the Chapter 6 Interrupt Manager 63 address of the user s ISR in the RTEMS Vector Table This directive returns the previous contents of the specified vector in the RTEMS Vector Table 6 3 2 Directives Allowed from an ISR Using the interrupt manager ensures that RTEMS knows when a directive is being called from an ISR The ISR may then use system calls to synchronize itself with an application task The synchronization may involve messages events or signals being passed by the ISR to the desired task Directives invoked by an ISR must operate only on objects which reside on the local node The following is a list of RTEMS system calls that may be made from an ISR e Task Management Although it is acceptable to operate on the RTEMS SELF task e g the currently executing task while in an ISR this will refer to the interrupted task Most o
172. bility of this task set This rule calls for one to examine each occurrence of deadline until either all tasks have met their deadline or one task failed to meet its first deadline The following table details the time of each deadline occurrence the maximum number of times each task may have run the total execution time and whether all the deadlines have been met 200 RTEMS C User s Guide Deadline Task Task Task Total All Deadlines Time 1 2 3 Execution Time Net 100 1 1 1 25 50 100 175 NO 200 2 1 1 50 50 100 200 YES The key to this analysis is to recognize when each task will execute For example at time 100 task 1 must have met its first deadline but tasks 2 and 3 may also have begun execution In this example at time 100 tasks 1 and 2 have completed execution and thus have met their first deadline Tasks 1 and 2 have used 25 50 75 time units leaving 100 75 25 time units for task 3 to begin Because task 3 takes 100 ticks to execute it will not have completed execution at time 100 Thus at time 100 all of the tasks except task 3 have met their first deadline At time 200 task 1 must have met its second deadline and task 2 its first deadline As a result of the first 200 time units task 1 uses 2 25 50 and task 2 uses 50 leaving 200 100 time units for task 3 Task 3 requires 100 time units to execute thus it will have completed execution at time 200 Thus all of the ta
173. blocks itself through voluntary operations that cause the task to wait The only way a task can block a task other than itself is with the rtems_task_suspend directive A task enters the blocked state due to any of the following conditions e A task issues a rtems_task_suspend directive which blocks either itself or another task in the system e The running task issues a rtems_message_queue_receive directive with the wait option and the message queue is empty e The running task issues an rtems_event_receive directive with the wait option and the currently pending events do not satisfy the request e The running task issues a rtems_semaphore_obtain directive with the wait option and the requested semaphore is unavailable e The running task issues a rtems_task_wake_after directive which blocks the task for the given time interval If the time interval specified is zero the task yields the processor and remains in the ready state e The running task issues a rtems_task_wake_when directive which blocks the task until the requested date and time arrives e The running task issues a rtems_region_get_segment directive with the wait op tion and there is not an available segment large enough to satisfy the task s request e The running task issues a rtems_rate_monotonic_period directive and must wait for the specified rate monotonic period to conclude A blocked task may also be suspended Therefore both the suspension and the blocking co
174. buffers from a physically contiguous memory space which starts at starting address and is length bytes in size Each allocated buffer is to be of buffer size in bytes The assigned partition id is returned in id This partition id is used to access the partition with other partition related directives For control and maintenance of the partition RTEMS allocates a PTCB from the local P TCB free pool and initializes it NOTES This directive will not cause the calling task to be preempted The starting address must be properly aligned for the target architecture The buffer size parameter must be a multiple of the CPU alignment factor Additionally buffer size must be large enough to hold two pointers on the target architecture This is required for RTEMS to manage the buffers when they are free Memory from the partition is not used by RTEMS to store the Partition Control Block The following partition attribute constants are defined by RTEMS e RTEMS LOCAL local task default e RTEMS GLOBAL global task 144 RTEMS C User s Guide The PTCB for a global partition is allocated on the local node The memory space used for the partition must reside in shared memory Partitions should not be made global unless remote tasks must interact with the partition This is to avoid the overhead incurred by the creation of a global partition When a global partition is created the partition s name and id must be transmitted to every node in the
175. by AT amp T s System V Interface Definition and IEEE s POSIX efforts A compliant multiprocessing executive will allow close coupling between UNIX systems and real time executives to provide the many benefits of the UNIX development environment to be applied to real time software development Together they provide the necessary laboratory environment to implement real time distributed embed ded systems using a wide variety of computer architectures A study was completed in 1988 within the Research Development and Engineering Center U S Army Missile Command which compared the various aspects of the Ada programming language as they related to the application of Ada code in distributed and or multiple pro cessing systems Several critical conclusions were derived from the study These conclusions have a major impact on the way the Army develops application software for embedded ap plications These impacts apply to both in house software development and contractor developed software A conclusion of the analysis which has been previously recognized by other agencies at tempting to utilize Ada in a distributed or multiprocessing environment is that the Ada programming language does not adequately support multiprocessing Ada does provide a mechanism for multi tasking however this capability exists only for a single processor sys tem The language also does not have inherent capabilities to access global named variables flags or program
176. by an application via user extension routines The TCB contains a task s name ID current priority current and starting states execution mode set of notepad locations TCB user extension pointer scheduling control structures as well as data required by a blocked task A task s context is stored in the TCB when a task switch occurs When the task regains control of the processor its context is restored from the TCB When a task is restarted the initial state of the task is restored from the starting context area in the task s TCB 5 2 3 Task States A task may exist in one of the following five states e executing Currently scheduled to the CPU e ready May be scheduled to the CPU e blocked Unable to be scheduled to the CPU e dormant Created task that is not started e non existent Uncreated or deleted task An active task may occupy the executing ready blocked or dormant state otherwise the task is considered non existent One or more tasks may be active in the system simulta neously Multiple tasks communicate synchronize and compete for system resources with each other via system calls The multiple tasks appear to execute in parallel but actually each is dispatched to the CPU for periods of time determined by the RTEMS scheduling algorithm The scheduling of a task is based on its current state and priority 5 2 4 Task Priority A task s priority determines its importance in relation to the other tasks executing o
177. by the task s execution mode and a higher priority local task is waiting on the deleted semaphore The calling task will NOT be preempted if all of the tasks that are waiting on the semaphore are remote tasks The calling task does not have to be the task that created the semaphore Any local task that knows the semaphore id can delete the semaphore When a global semaphore is deleted the semaphore id must be transmitted to every node in the system for deletion from the local copy of the global object table The semaphore must reside on the local node even if the semaphore was created with the RTEMS GLOBAL option Proxies used to represent remote tasks are reclaimed when the semaphore is deleted Chapter 9 Semaphore Manager 109 9 4 44 SEMAPHORE_OBTAIN Acquire a semaphore CALLING SEQUENCE rtems_status_code rtems_semaphore_obtain rtems_id id rtems_option option_set rtems_interval timeout DIRECTIVE STATUS CODES RTEMS SUCCESSFUL semaphore obtained successfully RTEMS UNSATISFIED semaphore not available RTEMS TIMEOUT timed out waiting for semaphore RTEMS OBJECT WAS DELETED semaphore deleted while waiting RTEMS INVALID ID invalid semaphore id DESCRIPTION This directive acquires the semaphore specified by id The RTEMS WAIT and RTEMS NO WAIT components of the options parameter indicate whether the calling task wants to wait for the semaphore to become available or return immediately if the se
178. can access and modify the variable but the modifications will not appear to other tasks and other tasks modifications to that variable will not affect the value seen by the task This is accomplished by saving and restoring the variable s value each time a task switch occurs to or from the calling task If the dtor argument is non NULL it specifies the address of a destructor function which will be called when the task is deleted The argument passed to the destructor function is the task s value of the variable NOTES Task variables increase the context switch time to and from the tasks that own them so it is desirable to minimize the number of task variables One efficient method is to have a single task variable that is a pointer to a dynamically allocated structure containing the task s private global data In this case the destructor function could be free 58 RTEMS C User s Guide 5 4 18 TASK VARIABLE GET Obtain value of a per task variable CALLING SEQUENCE rtems status code rtems task variable get rtems id tid void task variable void task variable value X DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL per task variable added successfully RTEMS_INVALID_ADDRESS task_variable is NULL RTEMS_INVALID_ADDRESS task_variable_value is NULL RTEMS_INVALID_ADDRESS task_variable is not found RTEMS_NO_MEMORY invalid task id RTEMS_ILLEGAL_ON_REMOTE_OBJECT not supported on remote tasks DESC
179. cations link has an obvious impact on the maximum MPCI throughput The characteristics of a shared network such as Ethernet lend themselves to supporting an MPCI layer These networks provide both the point to point and broadcast capabilities which are expected by RTEMS Chapter 21 Board Support Packages 229 21 5 3 Systems with Mixed Coupling A mixed coupling system is a multiprocessor configuration in which the processors com municate via both shared memory and communications links A unique characteristic of mixed coupling systems is that a node may not have access to all communication methods There may be multiple shared memory areas and communication links Therefore one of the primary functions of the MPCI layer is to efficiently route RTEMS packets between nodes This routing may be based on numerous algorithms In addition the router may provide alternate communications paths in the event of an overload or a partial failure 21 5 4 Heterogeneous Systems Designing an MPCI layer for a heterogeneous system requires special considerations by the developer RTEMS is designed to eliminate many of the problems associated with sharing data in a heterogeneous environment The MPCI layer need only address the representation of thirty two 32 bit unsigned quantities For more information on supporting a heterogeneous system refer the Supporting Hetero geneous Environments in the Multiprocessing Manager chapter Chapter 22 User Exte
180. ccessfully send a message to a message queue which has a full queue of pending messages 10 3 5 Broadcasting a Message The rtems_message_queue_broadcast directive sends the same message to every task waiting on the specified message queue as an atomic operation The message is copied to each waiting task s message buffer and each task is unblocked The number of tasks which were unblocked is returned to the caller 10 3 6 Deleting a Message Queue The rtems_message_queue_delete directive removes a message queue from the system and frees its control block as well as the memory associated with this message queue s message buffer pool A message queue can be deleted by any local task that knows the message queue s ID As a result of this directive all tasks blocked waiting to receive a message from the message queue will be readied and returned a status code which indicates that the message queue was deleted Any subsequent references to the message queue s name and ID are invalid Any messages waiting at the message queue are also deleted and deallocated 116 RTEMS C User s Guide 10 4 Directives This section details the message manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes Chapter 10 Message Manager 117 10 4 1 MESSAGE QUEUE CREATE Create a queue CALLING SEQUENCE rtems status code rtems message
181. ce ee eee 271 O object ID sic ier REPE Re DAPPRCRPPV RR ROSE 14 object ID composition sssseeeseesss 14 object manipulation sseeseeeeese 289 object name cscceestiser he DH CER EX PEE 13 slum P 13 obtain a barrier cece eee eee eee 223 obtain a semaphore eee eee eee 109 obtain API from id 00 cece eee eee 296 obtain API name 0 e eee eee eee 305 obtain buffer from partition 147 Concept Index obtain class from object id 00 297 obtain class information 00005 307 obtain Class NAME espiren en Er 306 obtain ID of a barrier 0 005 221 obtain ID of a partition 0 145 obtain ID of a period ueulusessus 208 obtain TD of port sol odie ages pps 166 obtain ID of region oce ER 154 obtain ID of a semaphore 6 107 obtain ID of an extension set ssu 239 obtain ID of caller ilie Liebe t ar Ri 43 obtain index from object id 299 obtain maximum API value 302 obtain maximum class value 304 obtain minimum API value 301 obtain minimum class value 303 obtain name from id esee ee eee 293 obtain node from object id 298 obtain object name as string 294 obtain per task variable 0 00
182. ce eee ee eens 35 5 2 9 Building a Task Attribute Set 0 0 35 5 2 10 Building a Mode and Mask 0 cece eee ee 36 5 39 Operations rei bIerq x KE Rae Mab deh UC a i 36 Boel Creating Tasks icc icpcivadheunt bay aret peer RO Roa 36 5 3 2 Obtaming Task IDs ec sncpee ens LR RERIDE RA EN ea a or 5 3 3 Starting and Restarting Tasks 20 eee eee 37 5 3 4 Suspending and Resuming Tasks 0 0000 eee eee 37 5 3 5 Delaying the Currently Executing Task 38 5 3 6 Changing Task Priority 0 000 cece eee eee 38 5 3 7 Changing Task Mode 0 ccc e eee eee eee 38 5 3 8 Notepad Loeations soccer RI debe ng date ingen ces 38 5 9 9 Task Deletions 25 ognescvctaeanttagiaaob asus RR OR ads 38 OA JDirectiveS i cssecete eR RO a eee tee Re RRRERG ORE S EOS ac 39 5 4 4 TASK CREATE Create a task 000 e eee eee 40 5 4 2 TASK_IDENT Get ID of a task 0 00 42 5 4 3 TASK SELF Obtain ID of caller 43 5 4 4 TASK START Start a task 0 0 cece eee 44 5 4 5 TASK RESTART Restart a task 004 45 5 4 6 lTASK DELETE Delete a task 004 46 5 4 7 TASK SUSPEND Suspend a task 000 4T 5 4 8 TASK RESUME Resume a task 2 0000 48 5 4 9 TASK IS SUSPENDED Determine if a task is Suspended nm 49 5 4 10 TASK SET PRIORITY Set task p
183. cessor and resources If the task was blocked as well as suspended this directive clears the suspension and leaves the task in the blocked state Suspending a task which is already suspended or resuming a task which is not suspended is considered an error The rtems_task_is_suspended can be used to determine if a task is currently suspended 38 RTEMS C User s Guide 5 3 5 Delaying the Currently Executing Task The rtems_task_wake_after directive creates a sleep timer which allows a task to go to sleep for a specified interval The task is blocked until the delay interval has elapsed at which time the task is unblocked A task calling the rtems_task_wake_after directive with a delay interval of RTEMS_YIELD_PROCESSOR ticks will yield the processor to any other ready task of equal or greater priority and remain ready to execute The rtems_task_wake_when directive creates a sleep timer which allows a task to go to sleep until a specified date and time The calling task is blocked until the specified date and time has occurred at which time the task is unblocked 5 3 6 Changing Task Priority The rtems_task_set_priority directive is used to obtain or change the current priority of either the calling task or another task If the new priority requested is RTEMS_CURRENT_ PRIORITY or the task s actual priority then the current priority will be returned and the task s priority will remain unchanged If the task s priority is altered then the t
184. contains items such as the various object control blocks TCBs QCBs and task stacks If the address is not aligned on a four word bound ary then RT EMS will invoke the fatal error handler during rtems_ initialize executive When using the rtems confdefs h mech anism for configuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE EXECUTIVE RAM WORK AREA which defaults to NULL Normally this field should be configured as NULL as BSPs will assign memory for the RTEMS RAM Workspace as part of system initialization is the calculated size of the RTEMS RAM Workspace The section Sizing the RTEMS RAM Workspace details how to arrive at this number When using the rtems confdefs h mechanism for con figuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE_EXECUTIVE_RAM_SIZE and is calculated based on the other system configuration settings is number of microseconds per clock tick When using the rtems confdefs h mechanism for configuring an RTEMS applica tion the value for this field corresponds to the setting of the macro CONFIGURE_MICROSECONDS_PER_TICK If not defined by the applica 252 ticks per timeslice idle task idle task stack size interrupt stack size stack allocate hook stack free hook do zero of workspace maximum drivers RTEMS C User s Guide tion then the CONFIGURE MICROSECONDS PER TICK macro defa
185. conventions on the user 22 2 3 1 TASK CREATE Extension The TASK_CREATE extension directly corresponds to the rtems_task_create directive If this extension is defined in any static or dynamic extension set and a task is being created then the extension routine will automatically be invoked by RTEMS The extension should have a prototype similar to the following bool user task create rtems tcb current task rtems tcb new task 25 where current task can be used to access the TCB for the currently executing task and new task can be used to access the TCB for the new task being created This exten sion is invoked from the rtems task create directive after new task has been completely initialized but before it is placed on a ready TCB chain The user extension is expected to return the boolean value true if it successfully executed and false otherwise A task create user extension will frequently attempt to allocate resources If this allocation fails then the extension should return false and the entire task create operation will fail 22 2 3 2 TASK START Extension The TASK START extension directly corresponds to the task start directive If this ex tension is defined in any static or dynamic extension set and a task is being started then the extension routine will automatically be invoked by RTEMS The extension should have a prototype similar to the following rtems extension user task start rtems tcb current task rt
186. create and start each of the initial ization threads The format of each entry in this table is defined in the posix initialization threads table structure When using the rtems confdefs h mechanism for configuring an RTEMS ap plication the value for this field corresponds to the address of the POSIX Initialization threads structure 23 6 CPU Dependent Information Table The CPU Dependent Information Table is used to describe processor dependent information required by RTEMS This table is generally used to supply RTEMS with information only known by the Board Support Package The contents of this table are discussed in the CPU Dependent Information Table chapter of the Applications Supplement document for a specific target processor The rtems confdefs h mechanism does not support generating this table It is normally filled in by the Board Support Package 23 7 Initialization Task Table The Initialization Task Table is used to describe each of the user initialization tasks to the Initialization Manager The table contains one entry for each initialization task the user wishes to create and start The fields of this data structure directly correspond to arguments to the rtems_task_create and rtems_task_start directives The number of entries is found in the number_of_initialization_tasks entry in the Configuration Table The format of each entry in the Initialization Task Table is defined in the following C structure typedef struct
187. ct_id_api_minimum void DIRECTIVE STATUS CODES Returns the minimum valid for the API portion of an object Id DESCRIPTION This service returns the minimum valid for the API portion of an object Id NOTES This directive is strictly local and does not impact task scheduling 302 RTEMS C User s Guide 27 4 11 OBJECT ID API MAXIMUM Obtain Maximum API Value CALLING SEQUENCE uint32 t rtems object id api maximum void DIRECTIVE STATUS CODES Returns the maximum valid for the API portion of an object Id DESCRIPTION This service returns the maximum valid for the API portion of an object Id NOTES This directive is strictly local and does not impact task scheduling Chapter 27 Object Services 303 27 4 12 OBJECT API MINIMUM CLASS Obtain Minimum Class Value CALLING SEQUENCE uint32 t rtems object api minimum class uint32 t api DIRECTIVE STATUS CODES If api is not valid 1 is returned If successful this service returns the minimum valid for the class portion of an object Id for the specified api DESCRIPTION This service returns the minimum valid for the class portion of an object Id for the specified api NOTES This directive is strictly local and does not impact task scheduling 304 RTEMS C User s Guide 27 4 13 OBJECT_API_MAXIMUM_CLASS Obtain Maximum Class Value CALLING SEQUENCE uint32 t rtems object api maximum class uint32 t api DIRECTIVE STATUS CODES If api
188. cutable image However some managers may be explicitly excluded and no attempt to create these instances of these objects will succeed even if they are configured The following Classic API managers may be optionally excluded e signal e region e dual ported memory e event e multiprocessing e partition e timer e semaphore e message e rate monotonic RTEMS is designed to be built and installed as a library that is linked into the application As such much of RTEMS is implemented in such a way that there is a single entry point per source file This avoids having the linker being forced to pull large object files in their entirety into an application when the application references a single symbol In the event you discover an RTEMS method that is included in your executable but never entered please let us know It might be an opportunity to break a dependency and shrink many RTEMS applications RTEMS based applications must somehow provide memory for RTEMS code and data space Although RTEMS data space must be in RAM its code space can be located in either ROM or RAM In addition the user must allocate RAM for the RTEMS RAM Workspace The size of this area is application dependent and can be calculated using the formula provided in the Memory Requirements chapter of the Applications Supplement document for a specific target processor All private RTEMS data variables and routine names used by RTEMS begin with the underscor
189. d if the application has device drivers it needs to include in the Device Driver Table This should be defined to the set of device driver entries that will be placed in the table at the END of the Device Driver Table By default this is not defined 23 2 5 Multiprocessing Configuration This section defines the multiprocessing related system configuration parameters sup ported by rtems confdefs h This class of Configuration Constants are only applicable if CONFIGURE_MP_APPLICATION is defined CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE is defined if the application wishes to provide their own Multiprocessing Configuration Table The generated table is named Multiprocessing_configuration By default this is not defined CONFIGURE_MP_NODE_NUMBER is the node number of this node in a multiprocessor system The default node number is NODE_NUMBER which is set directly in RTEMS test Makefiles CONFIGURE_MP_MAXIMUM_NODES is the maximum number of nodes in a multiproces sor system The default is 2 CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS is the maximum number of concurrently active global objects in a multiprocessor system The default is 32 CONFIGURE_MP_MAXIMUM_PROXIES is the maximum number of concurrently active thread task proxies in a multiprocessor system The default is 32 CONFIGURE_MP_MPCI_TABLE_POINTER is the pointer to the MPCI Configuration Ta ble The default value of this field is amp MPCI table 23 2 6 Classic API Configuration
190. d task priority RTEMS_MP_NOT_CONFIGURED multiprocessing not configured RTEMS_TOO_MANY too many tasks created RTEMS_UNSATISFIED not enough memory for stack FP context RTEMS_TOO_MANY too many global objects DESCRIPTION This directive creates a task which resides on the local node It allocates and initializes a TCB a stack and an optional floating point context area The mode parameter contains values which sets the task s initial execution mode The RTEMS_FLOATING_POINT attribute should be specified if the created task is to use a numeric coprocessor For performance reasons it is recommended that tasks not using the numeric coprocessor should specify the RTEMS_NO_FLOATING_POINT attribute If the RTEMS_GLOBAL attribute is specified the task can be accessed from remote nodes The task id returned in id is used in other task related directives to access the task When created a task is placed in the dormant state and can only be made ready to execute using the directive rtems_task_start NOTES This directive will not cause the calling task to be preempted Valid task priorities range from a high of 1 to a low of 255 If the requested stack size is less than the configured minimum stack size then RTEMS will use the configured minimum as the stack size for this task In addition to being able to specify the task stack size as a integer there are two constants which may be specified e RTEMS_MINIMUM_STACK_SIZE is the mi
191. d timer Most of the time executing floating point instructions from an interrupt service routine is not considered safe However since the Timer Server task is non preemptible only directives allowed from an ISR can be called in the timer service routine The Timer Server is designed to remain blocked until a task based timer fires This reduces the execution overhead of the Timer Server 8 2 4 Timer Service Routines The timer service routine should adhere to C calling conventions and have a prototype similar to the following rtems timer service routine user routine rtems id timer id void user data Where the timer id parameter is the RTEMS object ID of the timer which is being fired and user_data is a pointer to user defined information which may be utilized by the timer service routine The argument user data may be NULL 8 3 Operations 8 3 1 Creating a Timer The rtems timer create directive creates a timer by allocating a Timer Control Block TMCB assigning the timer a user specified name and assigning it a timer ID Newly created timers do not have a timer service routine associated with them and are not active 8 3 2 Obtaining Timer IDs When a timer is created RTEMS generates a unique timer ID and assigns it to the created timer until it is deleted The timer ID may be obtained by either of two methods First as the result of an invocation of the rtems timer create directive the timer ID is stored in a user p
192. device_minor_number minor void argument DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL successfully initialized RTEMS_INVALID_NUMBER invalid major device number DESCRIPTION This directive calls the device driver write routine specified in the Device Driver Table for this major number Write operations typically require a buffer address as part of the argument parameter block The contents of this buffer will be sent to the device NOTES This directive may or may not cause the calling task to be preempted This is dependent on the device driver being invoked 184 RTEMS C User s Guide 16 4 10 IO CONTROL Special device services CALLING SEQUENCE rtems status code rtems io control rtems device major number major rtems device minor number minor void argument X DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL successfully initialized RTEMS_INVALID_NUMBER invalid major device number DESCRIPTION This directive calls the device driver I O control routine specified in the Device Driver Table for this major number The exact functionality of the driver entry called by this directive is driver dependent It should not be assumed that the control entries of two device drivers are compatible For example an RS 232 driver I O control operation may change the baud rate of a serial line while an I O control operation for a floppy disk driver may cause a seek operation NOTES This directive may or may not cause the
193. e character followed by an upper case letter If RTEMS is linked with an application then the application code should NOT contain any symbols which begin with the underscore character and followed by an upper case letter to avoid any naming conflicts All RTEMS directive names should be treated as reserved words 23 13 Sizing the RTEMS RAM Workspace The RTEMS RAM Workspace is a user specified block of memory reserved for use by RTEMS The application should NOT modify this memory This area consists primarily of the RTEMS data structures whose exact size depends upon the values specified in the Con figuration Table In addition task stacks and floating point context areas are dynamically allocated from the RTEMS RAM Workspace 268 RTEMS C User s Guide The rtems confdefs h mechanism calcalutes the size of the RTEMS RAM Workspace automatically It assumes that all tasks are floating point and that all will be allocated the miminum stack space This calculation also automatically includes the memory that will be allocated for internal use by RTEMS The following macros may be set by the application to make the calculation of memory required more accurate e CONFIGURE_MEMORY_OVERHEAD e CONFIGURE_EXTRA_TASK_STACKS The starting address of the RTEMS RAM Workspace must be aligned on a four byte bound ary Failure to properly align the workspace area will result in the rtems_fatal_error_ occurred directive being invoked with the RTEMS_INVA
194. e Utilization maximum tasks 2 1 maximum_tasks 1 As the number of tasks increases the above formula approaches 1n 2 for a worst case uti lization factor of approximately 0 693 Many tasks sets can be scheduled with a greater utilization factor In fact the average processor utilization threshold for a randomly gener ated task set is approximately 0 88 19 2 5 3 Processor Utilization Rule Example This example illustrates the application of the Processor Utilization Rule to an application with three critical periodic tasks The following table details the RMS priority period execution time and processor utilization for each task Chapter 19 Rate Monotonic Manager 199 Task RMS Period Execution Processor Priority Time Utilization 1 High 100 15 0 15 2 Medium 200 50 0 25 3 Low 300 100 0 33 The total processor utilization for this task set is 0 73 which is below the upper bound of 3 2 1 3 1 or 0 779 imposed by the Processor Utilization Rule Therefore this task set is guaranteed to be schedulable using RMS 19 2 5 4 First Deadline Rule If a given set of tasks do exceed the processor utilization upper limit imposed by the Processor Utilization Rule they can still be guaranteed to meet all their deadlines by application of the First Deadline Rule This rule can be stated as follows For a given set of independent periodic tasks if each task meets its first deadline when all tas
195. e e rtems object get class information obtain class information 27 2 Background 27 2 1 APIs RTEMS implements multiple APIs including an Internal API the Classic API the POSIX API and the uITRON API These APIs share the common foundation of SuperCore objects and thus share object management code This includes a common scheme for object Ids and for managing object names whether those names be in the thirty two bit form used by the Classic API or C strings The object Id contains a field indicating the API that an object instance is associated with This field holds a numerically small non zero integer 27 2 2 Object Classes Each API consists of a collection of managers Each manager is responsible for instances of a particular object class Classic API Tasks and POSIX Mutexes example classes The object Id contains a field indicating the class that an object instance is associated with This field holds a numerically small non zero integer In all APIs a class value of one is reserved for tasks or threads 290 RTEMS C User s Guide 27 2 3 Object Names Every RTEMS object which has an Id may also have a name associated with it Depending on the API names may be either thirty two bit integers as in the Classic API or strings as in the POSIX API Some objects have Ids but do not have a defined way to associate a name with them For example POSIX threads have Ids but per POSIX do not have names In RTEMS objects not defin
196. e the semaphore s count is not changed by this directive and thus is zero before and after this directive is executed Tasks which are unblocked as the result of this directive will return from the rtems semaphore obtain directive with a status code of RTEMS_UNSATISFIED to indicate that the semaphore was not obtained This directive may unblock any number of tasks Any of the unblocked tasks may preempt the running task if the running task s preemption mode is enabled and an unblocked task has a higher priority than the running task NOTES The calling task may be preempted if it causes a higher priority task to be made ready for execution If the task to be unblocked resides on a different node from the semaphore then the waiting task is unblocked and the proxy used to represent the task is reclaimed Chapter 10 Message Manager 113 10 Message Manager 10 1 Introduction The message manager provides communication and synchronization capabilities using RTEMS message queues The directives provided by the message manager are e rtems_message_queue_create Create a queue e rtems_message_queue_ident Get ID of a queue e rtems_message_queue_delete Delete a queue e rtems_message_queue_send Put message at rear of a queue e rtems_message_queue_urgent Put message at front of a queue e rtems_message_queue_broadcast Broadcast N messages to a queue e rtems_message_queue_receive Receive message from a queue e rtems_message_
197. e barrier ID may be obtained later using the rtems barrier ident directive The barrier ID is used by other barrier manager directives to access this barrier 20 3 3 Waiting at a Barrier The rtems barrier wait directive is used to wait at the specified barrier Since a barrier is by definition never immediately the task may wait forever for the barrier to be released or it may specify a timeout Specifying a timeout limits the interval the task will wait before returning with an error status code If the barrier is configured as automatic and there are already one less then the maximum number of waiters then the call will unblock all tasks waiting at the barrier and the caller will return immediately When the task does wait to acquire the barrier then it is placed in the barrier s task wait queue in FIFO order All tasks waiting on a barrier are returned an error code when the barrier is deleted 20 3 4 Releasing a Barrier The rtems barrier release directive is used to release the specified barrier When the rtems barrier release is invoked all tasks waiting at the barrier are immediately made ready to execute and begin to compete for the processor to execute Chapter 20 Barrier Manager 219 20 3 5 Deleting a Barrier The rtems_barrier_delete directive removes a barrier from the system and frees its con trol block A barrier can be deleted by any local task that knows the barrier s ID As a result of this directive all ta
198. e by interrupt service routines must be taken into account when designing an application If the processor supports interrupt nesting the stack usage must include the deepest nest level The worst case stack usage must account for the following requirements e Processor s interrupt stack frame e Processor s subroutine call stack frame e RTEMS system calls e Registers saved on stack e Application subroutine calls The size of the interrupt stack must be greater than or equal to the confugured minimum stack size 21 2 2 Processors with a Separate Interrupt Stack Some processors support a separate stack for interrupts When an interrupt is vectored and the interrupt is not nested the processor will automatically switch from the current stack to the interrupt stack The size of this stack is based solely on the worst case stack usage by interrupt service routines The dedicated interrupt stack for the entire application on some architectures is supplied and initialized by the reset and initialization code of the user s Board Support Package Whether allocated and initialized by the BSP or RTEMS since all ISRs use this stack the stack size must take into account the worst case stack usage by any combination of nested ISRs 21 2 3 Processors Without a Separate Interrupt Stack Some processors do not support a separate stack for interrupts In this case without special assistance every task s stack must include enough space to hand
199. e dual ported memory area is not used to store the DPCB NOTES The internal address and external address parameters must be on a four byte boundary This directive will not cause the calling task to be preempted 166 RTEMS C User s Guide 15 4 2 PORT_IDENT Get ID of a port CALLING SEQUENCE rtems status code rtems port ident rtems name name rtems id id DIRECTIVE STATUS CODES RTEMS SUCCESSFUL port identified successfully RTEMS INVALID ADDRESS id is NULL RTEMS INVALID NAME port name not found DESCRIPTION This directive obtains the port id associated with the specified name to be acquired If the port name is not unique then the port id will match one of the DPMAs with that name However this port id is not guaranteed to correspond to the desired DPMA The port id is used to access this DPMA in other dual ported memory area related directives NOTES This directive will not cause the running task to be preempted Chapter 15 Dual Ported Memory Manager 167 15 4 3 PORT_DELETE Delete a port CALLING SEQUENCE rtems_status_code rtems_port_delete rtems_id id DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL port deleted successfully RTEMS_INVALID_ID invalid port id DESCRIPTION This directive deletes the dual ported memory area specified by id The DPCB for the deleted dual ported memory area is reclaimed by RTEMS NOTES This directive will not cause the calling task to be preempted
200. e global object table 146 RTEMS C User s Guide 13 4 3 PARTITION_DELETE Delete a partition CALLING SEQUENCE rtems_status_code rtems partition delete rtems id id 93 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL partition deleted successfully RTEMS INVALID ID invalid partition id RTEMS RESOURCE IN USE buffers still in use RTEMS ILLEGAL ON REMOTE OBJECT cannot delete remote partition DESCRIPTION This directive deletes the partition specified by id T he partition cannot be deleted if any of its buffers are still allocated The P TCB for the deleted partition is reclaimed by RTEMS NOTES This directive will not cause the calling task to be preempted The calling task does not have to be the task that created the partition Any local task that knows the partition id can delete the partition When a global partition is deleted the partition id must be transmitted to every node in the system for deletion from the local copy of the global object table The partition must reside on the local node even if the partition was created with the RTEMS GLOBAL option Chapter 13 Partition Manager 147 13 4 4 PARTITION_GET_BUFFER Get buffer from a partition CALLING SEQUENCE rtems_status_code rtems_partition_get_buffer rtems_id id void buffer i DIRECTIVE STATUS CODES RTEMS SUCCESSFUL buffer obtained successfully RTEMS INVALID ADDRESS buffer is NULL RTEMS INVALID ID invalid partition id RTEMS
201. e memory that must be reserved See Section 23 12 Configuring a System Determining Memory Requirements page 266 for more details RTEMS utilizes memory for both code and data space Although RTEMS data space must be in RAM its code space can be located in either ROM or RAM 1 9 Audience This manual was written for experienced real time software developers Although some background is provided it is assumed that the reader is familiar with the concepts of task management as well as intertask communication and synchronization Since directives user related data structures and examples are presented in C a basic understanding of the C programming language is required to fully understand the material presented However because of the similarity of the Ada and C RTEMS implementations users will find that the use and behavior of the two implementations is very similar A working knowledge of the target processor is helpful in understanding some of RTEMS features A thorough understanding of the executive cannot be obtained without studying the entire manual because many of RTEMS concepts and features are interrelated Experienced RTEMS users will find that the manual organization facilitates its use as a reference document 1 10 Conventions The following conventions are used in this manual e Significant words or phrases as well as all directive names are printed in bold type e Items in bold capital letters are constants defined by
202. e packet is the address of a packet If the packet cannot be successfully returned the fatal error manager should be invoked 24 3 4 RECEIVE PACKET The RECEIVE PACKET component of the user provided MPCI layer is called when RTEMS needs to obtain a packet which has previously arrived This component should be adhere to the following prototype rtems mpci entry user mpci receive packet rtems packet prefix packet 276 RTEMS C User s Guide where packet is a pointer to the address of a packet to place the message from another node If a message is available then packet will contain the address of the message from another node If no messages are available this entry packet should contain NULL 24 3 5 SEND PACKET The SEND PACKET component of the user provided MPCI layer is called when RTEMS needs to send a packet containing a message to another node This component should be adhere to the following prototype rtems mpci entry user mpci send packet uint32 t node rtems packet prefix packet J where node is the node number of the destination and packet is the address of a packet which containing a message If the packet cannot be successfully sent the fatal error manager should be invoked If node is set to zero the packet is to be broadcasted to all other nodes in the system Although some MPCI layers will be built upon hardware which support a broadcast mech anism others may be required to generate a copy of
203. e spread among as many processors as needed to satisfy the application s timing requirements The applica tion tasks can interact using a subset of the RTEMS directives as if they were on the same processor These directives allow application tasks to exchange data communicate and synchronize regardless of which processor they reside upon The RTEMS multiprocessor execution model is multiple instruction streams with multiple data streams MIMD This execution model has each of the processors executing code independent of the other processors Because of this parallelism the application designer can more easily guarantee deterministic behavior By supporting heterogeneous environments RTEMS allows the systems designer to select the most efficient processor for each subsystem of the application Configuring RTEMS for a heterogeneous environment is no more difficult than for a homogeneous one In keeping with RTEMS philosophy of providing transparent physical node boundaries the minimal heterogeneous processing required is isolated in the MPCI layer 24 2 1 Nodes A processor in a RTEMS system is referred to as a node Each node is assigned a unique non zero node number by the application designer RTEMS assumes that node numbers 272 RTEMS C User s Guide are assigned consecutively from one to the maximum_nodes configuration parameter The node number node and the maximum number of nodes maximum_nodes in a system are found in the Mult
204. econd option is RTEMS CLOCK GET TICKS PER SECOND and the number of ticks since the executive was initialized option is RTEMS CLOCK GET TICKS SINCE BOOT The option argument may taken on any value of the enumerated type rtems clock get options The data type expected for time buffer is based on the value of option as indicated below e RTEMS_CLOCK_GET_TOD rtems time of day e RTEMS CLOCK GET SECONDS SINCE EPOCH rtems interval e RTEMS CLOCK GET TICKS SINCE BOOT rtems interval e RTEMS CLOCK GET TICKS PER SECOND rtems interval e RTEMS CLOCK GET TIME VALUE rtems clock time value NOTES This directive is callable from an ISR This directive will not cause the running task to be preempted Re initializing RTEMS causes the system date and time to be reset to an uninitialized state Another call to rtems_clock_set is required to re initialize the system date and time to application specific specifications 76 RTEMS C User s Guide 7 4 3 CLOCK_GET_TOD Get date and time in TOD format CALLING SEQUENCE rtems_status_code rtems_clock_get_tod rtems_time_of_day time_buffer 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL current time obtained successfully RTEMS NOT DEFINED system date and time is not set RTEMS INVALID ADDRESS time buffer is NULL DESCRIPTION This directive obtains the system date and time If the date and time has not been set with a previous cal
205. ed A typical declaration for a User Extension Table which defines the TASK CREATE TASK_DELETE TASK_SWITCH and FATAL extension might appear as follows rtems_extensions_table User_extensions task_create_extension NULL NULL task_delete_extension task_switch_extension NULL NULL fatal_extension do More information regarding the user extensions is provided in the User Extensions chapter 23 10 Multiprocessor Configuration Table The Multiprocessor Configuration Table contains information needed when using RTEMS in a multiprocessor configuration Many of the details associated with configuring a mul tiprocessor system are dependent on the multiprocessor communications layer provided by 264 RTEMS C User s Guide the user The address of the Multiprocessor Configuration Table should be placed in the User multiprocessing table entry in the primary Configuration Table Further details regarding many of the entries in the Multiprocessor Configuration Table will be provided in the Multiprocessing chapter When using the rtems confdefs h mechanism for configuring an RTEMS application the macro CONFIGURE MP APPLICATION must be defined to automatically generate the Multi processor Configuration Table If CONFIGURE MP APPLICATION is not defined then a NULL pointer is configured as the address of this table The format of the Multiprocessor Configuration Table is defined in the following C structure typedef struct
206. ed in the following table e RTEMS_WAIT task will wait for segment default e RTEMS_NO_WAIT task should not wait Option values are specifically designed to be mutually exclusive therefore bitwise OR and addition operations are equivalent as long as each option appears exactly once in the compo nent list An option listed as a default is not required to appear in the option list although it is a good programming practice to specify default options If all defaults are desired the option RTEMS_DEFAULT_OPTIONS should be specified on this call This example demonstrates the option parameter needed to poll for a segment The option parameter passed to the rtems_region_get_segment directive should be RTEMS_NO_WAIT 14 3 Operations 14 3 1 Creating a Region The rtems region create directive creates a region with the user defined name The user may select FIFO or task priority as the method for placing waiting tasks in the task wait queue RTEMS allocates a Region Control Block RNCB from the RNCB free list to maintain the newly created region RTEMS also generates a unique region ID which is returned to the calling task It is not possible to calculate the exact number of bytes available to the user since RTEMS requires overhead for each segment allocated For example a region with one segment that is the size of the entire region has more available bytes than a region with two segments that collectively are the size of the entire region
207. ed to have thirty two bit names may have string names assigned to them via the rtems object set name service The original impetus in providing this service was so the normally anonymous POSIX threads could have a user defined name in CPU Usage Reports 27 3 Operations 27 3 1 Decomposing and Recomposing an Object Id Services are provided to decompose an object Id into its subordinate components The following services are used to do this e rtems object id get api e rtems object id get class e rtems object id get node e rtems object id get index The following C language example illustrates the decomposition of an Id and printing the values void printObjectId rtems_id id 1 printf API 4d Class d Node d Index d n rtems object id get api id rtems object id get class id rtems object id get node id rtems object id get index id n This prints the components of the Ids as integers It is also possible to construct an arbitrary Id using the rtems_build_id service The following C language example illustrates how to construct the next Id rtems_id nextObjectId rtems_id id return rtems_build_id rtems_object_id_get_api id rtems_object_id_get_class id rtems object id get node id rtems object id get index id 1 Chapter 27 Object Services 291 25 Note that this Id may not be valid in this system or associated with an allocated object 27 3 2 Printing an Object Id RTEMS also provides services
208. een executing If the task has been running less than 1 clock tick then for the purposes of the statistics it is assumed to have executed 1 clock tick This results in some inaccuracy but the alternative is for the task to have appeared to execute 0 clock ticks RTEMS versions newer than the 4 7 release series support the ability to obtain timestamps with nanosecond granularity if the BSP provides support It is a desirable enhancement to change the way the usage data is gathered to take advantage of this recently added capability Please consider sponsoring the core RTEMS development team to add this capability 26 3 Operations 26 3 1 Report CPU Usage Statistics The application may dynamically report the CPU usage for every task in the system by calling the rtems cpu usage report routine This routine prints a table with the following information per task e task id e task name e number of clock ticks executed e percentage of time consumed by this task The following is an example of the report generated 286 RTEMS C User s Guide CPU Usage by thread ID NAME TICKS PERCENT 0x04010001 IDLE 0 0 000 0x08010002 TA1 1203 0 748 0x08010003 TA2 203 0 126 0x08010004 TA3 202 0 126 Ticks since last reset 1600 Total Units 1608 Notice that the Total Units is greater than the ticks per reset This is an artifact of the way in which RTEMS keeps track of CPU usage When a task is context switched into the CPU the number of
209. ems tcb started task 25 where current task can be used to access the TCB for the currently executing task and started task can be used to access the T CB for the dormant task being started This extension is invoked from the task start directive after started task has been made ready to start execution but before it is placed on a ready TCB chain 234 RTEMS C User s Guide 22 2 3 3 TASK RESTART Extension The TASK_RESTART extension directly corresponds to the task_restart directive If this extension is defined in any static or dynamic extension set and a task is being restarted then the extension should have a prototype similar to the following rtems extension user task restart rtems tcb current task rtems tcb restarted task where current task can be used to access the TCB for the currently executing task and restarted task can be used to access the TCB for the task being restarted This extension is invoked from the task restart directive after restarted task has been made ready to start execution but before it is placed on a ready TCB chain 22 2 3 4 TASK DELETE Extension The TASK DELETE extension is associated with the task delete directive If this extension is defined in any static or dynamic extension set and a task is being deleted then the extension routine will automatically be invoked by RT EMS The extension should have a prototype similar to the following rtems extension user task delete rtems tc
210. epoch the number of ticks since the executive was initialized and the number of ticks per second The information returned by the rtems clock get directive is dependent on the option selected by the caller This is specified using one of the following constants associated with the enumerated type rtems clock get options e RTEMS CLOCK GET TOD obtain native style date and time e RTEMS CLOCK GET TIME VALUE obtain UNIX style date and time e RTEMS CLOCK GET TICKS SINCE BOOT obtain number of ticks since RTEMS was initialized e RTEMS CLOCK GET SECONDS SINCE EPOCH obtain number of seconds since RTEMS epoch e RTEMS CLOCK GET TICKS PER SECOND obtain number of clock ticks per second Calendar time operations will return an error code if invoked before the date and time have been set 7 4 Directives This section details the clock manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes 74 RTEMS C User s Guide 7 4 1 CLOCK_SET Set date and time CALLING SEQUENCE rtems_status_code rtems_clock_set rtems_time_of_day time_buffer 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL date and time set successfully RTEMS INVALID ADDRESS time buffer is NULL RTEMS INVALID CLOCK invalid time of day DESCRIPTION This directive sets the system date and time The date time and ticks in the time
211. equired by an RTEMS application Rather than building the individual tables by hand the application simply specifies the values for the configuration parameters it wishes to set In the following example the configuration information for a simple system with a message queue and a time slice of 50 milliseconds is configured define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER define CONFIGURE_MICROSECONDS_PER_TICK 1000 1 millisecond define CONFIGURE_TICKS_PER_TIMESLICE 50 50 milliseconds define CONFIGURE_MAXIMUM_TASKS 4 define CONFIGURE_RTEMS_INIT_TASKS_TABLE This system will begin execution with the single initialization task named Init It will be configured to have both a console device driver for standard I O and a clock tick device driver For each configuration parameter in the configuration tables the macro corresponding to that field is discussed Most systems can be easily configured using the rtems confdefs h mechanism The CONFIGURE INIT constant must be defined in order to make rtems confdefs h in stantiate the configuration data structures This can only be defined in one source file per application that includes rtems confdefs h or the symbol table will be instantiated multiple times and linking errors produced The user should be aware that the defaults are intentionally set as low as possible By default no application resources are configured The rtems
212. er isi ee ERE Rua ertet 142 13 3 5 Deleting a Partition 0 00 eee eens 142 13 4 Directives sceccee da a eetdaneeh nies th bet ad deed dd doxes 142 13 4 4 PARTITION CREATE Create a partition 143 13 4 2 PARTITION IDENT Get ID of a partition 145 13 4 8 PARTITION_DELETE Delete a partition 146 13 4 4 PARTITION GET BUFFER Get buffer from a partition TTE 147 13 4 5 PARTITION_RETURN_BUFFER Return buffer to a POLLO izzeneseseseedeem e REG nota aoe vax aie generac Reger Race 148 14 Region Manager e sss 149 14 1 IntroductOn u unio ren ela eae brc bp ec co dca 149 142 Backsround iii isses ben Te ema ber hue xao ea deca Rer bipes 149 14 2 1 Region Manager Definitions 0000085 149 14 2 2 Building an Attribute Set 0 e eee eee 149 14 2 8 Building an Option Set 0 e eee eee eee eee 150 14 3 Operations ec species cocks vex Ped I uma ace rrid rd EEUU 150 14 3 1 Creating a Region sssssseeseese esee 150 14 3 2 Obtaining Region IDs 0 cece eee eee ee 150 14 8 8 Adding Memory to a Region 000s eee 151 14 3 4 Acquiring a Segment 0 cece eee ees 151 14 3 5 Releasing a Segment 0 c cece eee eee 151 14 3 6 Obtaining the Size of a Segment 000 eee 151 14 3 7 Changing the Size of a Segment 004 151 14 3 8 Deleting a Regi
213. er 22 Chapter 23 Chapter 24 Chapter 25 Chapter 26 11 Scheduling Concepts details the RTEMS scheduling algorithm and task state transitions Rate Monotonic Manager describes the functionality and directives provided by the Rate Monotonic Manager Board Support Packages defines the functionality required of user supplied board support packages User Extensions shows the user how to extend RTEMS to incorpo rate custom features Configuring a System details the process by which one tailors RTEMS for a particular single processor or multiprocessor applica tion Multiprocessing Manager presents a conceptual overview of the mul tiprocessing capabilities provided by RTEMS as well as describing the Multiprocessing Communications Interface Layer and Multipro cessing Manager directives Directive Status Codes provides a definition of each of the directive status codes referenced in this manual Example Application provides a template for simple RTEMS appli cations Glossary defines terms used throughout this manual Chapter 2 Key Concepts 13 2 Key Concepts 2 1 Introduction The facilities provided by RTEMS are built upon a foundation of very powerful concepts These concepts must be understood before the application developer can efficiently utilize RTEMS The purpose of this chapter is to familiarize one with these concepts 2 2 Objects RTEMS provides directives which can be used to dynamically
214. er is willing to block or return immediately with an error indicating that the resource was not available rtems packet prefix is the data structure that defines the first bytes in every packet sent between nodes in an RT EMS multiprocessor system It contains routing information that is expected to be used by the MPCI layer rtems signal set is the data type used to manage and manipulate RTEMS signal sets with the Signal Manager int8 t is the C99 data type that corresponds to signed eight bit integers This data type is defined by RTEMS in a manner that ensures it is portable across different target processors Chapter 3 RTEMS Data Types 21 e inti6_t is the C99 data type that corresponds to signed sixteen bit integers This data type is defined by RTEMS in a manner that ensures it is portable across different target processors e int32 t is the C99 data type that corresponds to signed thirty two bit integers This data type is defined by RTEMS in a manner that ensures it is portable across different target processors e int64 t is the C99 data type that corresponds to signed sixty four bit integers This data type is defined by RTEMS in a manner that ensures it is portable across different target processors e rtems single is the RTEMS data type that corresponds to single precision floating point on the target hardware This type is deprecated Use float instead e rtems status codes is the e rtems task is the return type for
215. er task to execute When a global task is deleted the task id must be transmitted to every node in the system for deletion from the local copy of the global object table The task must reside on the local node even if the task was created with the RTEMS GLOBAL option Chapter 5 Task Manager 4T 5 4 7 TASK SUSPEND Suspend a task CALLING SEQUENCE rtems status code rtems task suspend rtems id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL task restarted successfully RTEMS INVALID ID task id invalid RTEMS ALREADY SUSPENDED task already suspended DESCRIPTION This directive suspends the task specified by id from further execution by placing it in the suspended state This state is additive to any other blocked state that the task may already be in The task will not execute again until another task issues the rtems task resume directive for this task and any blocked state has been removed NOTES The requesting task can suspend itself by specifying RTEMS SELF as id In this case the task will be suspended and a successful return code will be returned when the task is resumed Suspending a global task which does not reside on the local node will generate a request to the remote node to suspend the specified task If the task specified by id is already suspended then the RTEMS ALREADY SUSPENDED status code is returned 48 RTEMS C User s Guide 5 4 8 TASK RESUME Resume a task CALLING SEQUENCE
216. es 88 RTEMS C User s Guide 8 4 1 TIMER_CREATE Create a timer CALLING SEQUENCE rtems_status_code rtems_timer_create rtems_name name rtems_id id DIRECTIVE STATUS CODES RTEMS SUCCESSFUL timer created successfully RTEMS INVALID ADDRESS id is NULL RTEMS INVALID NAME invalid timer name RTEMS TOO MANY too many timers created DESCRIPTION This directive creates a timer The assigned timer id is returned in id This id is used to access the timer with other timer manager directives For control and maintenance of the timer RTEMS allocates a TMCB from the local TMCB free pool and initializes it NOTES This directive will not cause the calling task to be preempted Chapter 8 Timer Manager 89 8 4 2 TIMER IDENT Get ID of a timer CALLING SEQUENCE rtems status code rtems timer ident rtems name name rtems id id DIRECTIVE STATUS CODES RTEMS SUCCESSFUL timer identified successfully RTEMS INVALID ADDRESS id is NULL RTEMS INVALID NAME timer name not found DESCRIPTION This directive obtains the timer id associated with the timer name to be acquired If the timer name is not unique then the timer id will match one of the timers with that name However this timer id is not guaranteed to correspond to the desired timer The timer id is used to access this timer in other timer related directives NOTES This directive will not cause the running task to be preempted
217. es how the help macro CONFIGURE MESSAGE BUFFERS FOR QUEUE can be used to assist in calculating the message buffer memory required In this example there are two message queues used in this application The first message queue has maximum of 24 pending messages with the message structure defined by the type one message type The other message queue has maximum of 500 pending messages with the message structure defined by the type other message type define CONFIGURE MESSAGE BUFFERS FOR QUEUE CONFIGURE MESSAGE BUFFERS FOR QUEUE C 24 sizeof one message type CONFIGURE MESSAGE BUFFERS FOR QUEUE 500 sizeof other message type CONFIGURE MEMORY OVERHEAD is set to the number of kilobytes the application wishes to add to the requirements calculated by rtems confdefs h The default value is 0 CONFIGURE EXTRA TASK STACKS is set to the number of bytes the applications wishes to add to the task stack requirements calculated by rtems confdefs h This parameter is very important If the application creates tasks with stacks larger then the minimum then that memory is NOT accounted for by rtems confdefs h The default value is 0 NOTE The required size of the Executive RAM Work Area is calculated automatically when using the rtems confdefs h mechanism 23 2 3 Idle Task Configuration This section defines the IDLE task related configuration parameters supported by rtems confdefs h Chapter 23 Configuring a System 245 C
218. es that when given tasks of equal priority the task which has been ready longest will execute first RMS s priority assignment scheme does not provide one with exact numeric values for task priorities For example consider the following task set and priority assignments Task Period Priority in milliseconds 1 100 Low 2 50 Medium 3 50 Medium 4 25 High RMS only calls for task 1 to have the lowest priority task 4 to have the highest priority and tasks 2 and 3 to have an equal priority between that of tasks 1 and 4 The actual RTEMS priorities assigned to the tasks must only adhere to those guidelines Many applications have tasks with both hard and soft deadlines The tasks with hard deadlines are typically referred to as the critical task set with the soft deadline tasks being the non critical task set The critical task set can be scheduled using RMS with the non critical tasks not executing under transient overload by simply assigning priorities such that the lowest priority critical task i e longest period has a higher priority than the highest priority non critical task Although RMS may be used to assign priorities to the non critical tasks it is not necessary In this instance schedulability is only guaranteed for the critical task set 198 RTEMS C User s Guide 19 2 5 Schedulability Analysis RMS allows application designers to ensure that tasks can meet all deadlines even under transient o
219. eseeeees 167 15 4 4 PORT_EXTERNAL_TO_INTERNAL Convert external to internal address 2 25er ERE 4r nim 168 15 4 5 PORT INTERNAL TO EXTERNAL Convert internal to external address ccc cece cence Rn 169 vil vili RTEMS C User s Guide 16 I O Nana OP esecocee thru Pkt rh Dr tR 171 16 1 Introduction 5 Reb RP ISP UDCHEEREGRR e ERE IAS 171 16 2 Background rece ree EIS Re Ra REDE RE eee Tri 16 2 1 Device Driver Table 0 0 ccc eee eee 171 16 2 2 Major and Minor Device Numbers 5 172 16 2 8 Device Names cci sivaasaaccesnaas sone P Rn eo eher ee 172 16 2 4 Device Driver Environment 0 0 0 eee eee eee 172 16 2 5 Runtime Driver Registration 0 200 172 16 2 6 Device Driver Interface 0 00 cece eee eee 173 16 2 7 Device Driver Initialization 0002 000 173 10 9 Operations ivecGadeoctaes haven wae ba cedi d e RU ER Nd 173 16 3 1 Register and Lookup Name 0 eee ee eee 173 16 3 2 Accessing an Device Driver 0 00 eee e eee eee 173 10 4 DIP CCUIVES x uid enel eds eam vin tine cena ne RO DA AT EEE 174 16 4 4 IO_REGISTER_DRIVER Register a device driver 175 16 4 2 IO UNREGISTER DRIVER Unregister a device driver EET 176 16 4 8 IO INITIALIZE Initialize a device driver Jer 16 4 4 IO REGISTER NAME Register a device 178 16 4 5 IO LOOKUP NAME Lookup a device
220. esigned to be mutually exclusive therefore bitwise OR and addition operations are equivalent as long as each event appears exactly once in the event set list For example when sending the event set consisting of RTEMS_EVENT_6 RTEMS_EVENT_15 and RTEMS_EVENT_31 the event parameter to the rtems_event_send directive should be RTEMS_EVENT_6 RTEMS_EVENT_15 RTEMS_EVENT_31 130 RTEMS C User s Guide 11 2 3 Building an EVENT_RECEIVE Option Set In general an option is built by a bitwise OR of the desired option components The set of valid options for the rtems_event_receive directive are listed in the following table e RTEMS_WAIT task will wait for event default e RTEMS_NO_WAIT task should not wait e RTEMS_EVENT_ALL return after all events default e RTEMS_EVENT_ANY return after any events Option values are specifically designed to be mutually exclusive therefore bitwise OR and addition operations are equivalent as long as each option appears exactly once in the compo nent list An option listed as a default is not required to appear in the option list although it is a good programming practice to specify default options If all defaults are desired the option RTEMS_DEFAULT_OPTIONS should be specified on this call This example demonstrates the option parameter needed to poll for all events in a particular event condition to arrive The option parameter passed to the rtems_event_receive direc tive should be either RTEMS_
221. esults The requested lowering of the task s priority will occur when the task has released all priority inheritance binary semaphores l he task s priority can be increased regardless of the task s use of priority inheritance binary semaphores Chapter 5 Task Manager 51 5 4 11 TASK_MODE Change the current task mode CALLING SEQUENCE rtems_status_code rtems_task_mode rtems_mode mode_set rtems_mode mask rtems_mode previous_mode_set 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL task mode set successfully RTEMS INVALID ADDRESS previous mode set is NULL DESCRIPTION This directive manipulates the execution mode of the calling task A task s execution mode enables and disables preemption timeslicing asynchronous signal processing as well as specifying the current interrupt level To modify an execution mode the mode class es to be changed must be specified in the mask parameter and the desired mode s must be specified in the mode parameter NOTES The calling task will be preempted if it enables preemption and a higher priority task is ready to run Enabling timeslicing has no effect if preemption is disabled For a task to be timesliced that task must have both preemption and timeslicing enabled A task can obtain its current execution mode without modifying it by calling this directive with a mask value of RTEMS CURRENT MODE To temporarily disable the processing of a valid ASR a task should call th
222. evels 0 through 4 must use the interrupt manager Interrupts are nested whenever an interrupt occurs during the execution of another ISR RTEMS supports efficient interrupt nesting by allowing the nested ISRs to terminate with out performing any dispatch processing Only when the outermost ISR terminates will the postponed dispatching occur 6 2 2 RTEMS Interrupt Levels Many processors support multiple interrupt levels or priorities The exact number of inter rupt levels is processor dependent RTEMS internally supports 256 interrupt levels which are mapped to the processor s interrupt levels For specific information on the mapping be tween RTEMS and the target processor s interrupt levels refer to the Interrupt Processing chapter of the Applications Supplement document for a specific target processor 6 2 3 Disabling of Interrupts by RTEMS During the execution of directive calls critical sections of code may be executed When these sections are encountered RTEMS disables all maskable interrupts before the execution of the section and restores them to the previous level upon completion of the section RTEMS has been optimized to ensure that interrupts are disabled for a minimum length of time The maximum length of time interrupts are disabled by RTEMS is processor dependent and is detailed in the Timing Specification chapter of the Applications Supplement document for a specific target processor Non maskable interrupts NMI cannot
223. execution It is invoked imme diately before the body of the starting procedure and executes in the context in the task This user extension have a prototype similar to the following rtems_extension user_task_begin rtems_tcb current_task 25 where current task can be used to access the TCB for the currently executing task which has begun The distinction between the TASK BEGIN and TASK START extension is that the TASK BEGIN extension is executed in the context of the actual task while the TASK START extension is executed in the context of the task performing the task start directive For most extensions this is not a critical distinction 22 2 3 7 TASK EXITTED Extension The TASK_EXITTED extension is invoked when a task exits the body of the starting procedure by either an implicit or explicit return statement This user extension have a prototype similar to the following rtems extension user task exitted rtems tcb current task J where current_task can be used to access the TCB for the currently executing task which has just exitted Although exiting of task is often considered to be a fatal error this extension allows recovery by either restarting or deleting the exiting task If the user does not wish to recover then a fatal error may be reported If the user does not provide a TASK EXITTED extension or the provided handler returns control to RTEMS then the RTEMS default handler will be used This default handler inv
224. extension thread_switch rtems_task_begin_extension thread_begin rtems_task_exitted_extension thread_exitted rtems_fatal_extension fatal rtems_extensions_table 232 RTEMS C User s Guide RTEMS allows the user to have multiple extension sets active at the same time First a single static extension set may be defined as the application s User Extension Table which is included as part of the Configuration Table This extension set is active for the entire life of the system and may not be deleted This extension set is especially important because it is the only way the application can provided a FATAL error extension which is invoked if RTEMS fails during the initialize_executive directive The static extension set is optional and may be configured as NULL if no static extension set is required Second the user can install dynamic extensions using the rtems_extension_create di rective These extensions are RTEMS objects in that they have a name an ID and can be dynamically created and deleted In contrast to the static extension set these exten sions can only be created and installed after the initialize executive directive successfully completes execution Dynamic extensions are useful for encapsulating the functionality of an extension set For example the application could use extensions to manage a special coprocessor do performance monitoring and to do stack bounds checking Each of these extension sets could be written and ins
225. f no other tasks of the same priority are ready to run then the task does not lose control of the processor 18 2 5 Dispatching Tasks The dispatcher is the RTEMS component responsible for allocating the processor to a ready task In order to allocate the processor to one task it must be deallocated or retrieved from the task currently using it This involves a concept called a context switch To perform a context switch the dispatcher saves the context of the current task and restores the context of the task which has been allocated to the processor Saving and restoring a task s context is the storing loading of all the essential information about a task to enable it to continue Chapter 18 Scheduling Concepts 191 execution without any effects of the interruption For example the contents of a task s register set must be the same when it is given the processor as they were when it was taken away All of the information that must be saved or restored for a context switch is located either in the TCB or on the task s stacks Tasks that utilize a numeric coprocessor and are created with the RTEMS_FLOATING_POINT attribute require additional operations during a context switch These additional operations are necessary to save and restore the floating point context of RTEMS_FLOATING_POINT tasks To avoid unnecessary save and restore operations the state of the numeric coprocessor is only saved when a RTEMS_FLOATING_POINT task is dispatched a
226. f system clock ticks When the requested interval has elapsed the task is made ready The rtems clock tick directive automatically updates the delay period NOTES Setting the system date and time with the rtems clock set directive has no effect on a rtems task wake after blocked task A task may give up the processor and remain in the ready state by specifying a value of RTEMS YIELD PROCESSOR in ticks The maximum timer interval that can be specified is the maximum value which can be represented by the uint32_t type A clock tick is required to support the functionality of this directive Chapter 5 Task Manager 55 5 4 15 TASK WAKE WHEN Wake up when specified CALLING SEQUENCE rtems_status_code rtems task wake when rtems time of day time buffer 23 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL awakened at date time successfully RTEMS INVALID ADDRESS time buffer is NULL RTEMS INVALID TIME OF DAY invalid time buffer RTEMS NOT DEFINED system date and time is not set DESCRIPTION This directive blocks a task until the date and time specified in time buffer At the requested date and time the calling task will be unblocked and made ready to execute NOTES The ticks portion of time buffer structure is ignored The timing granularity of this directive is a second A clock tick is required to support the functionality of this directive 56 RTEMS C User s Guide 5 4 16 ITERATE_OVER_ALL_THREADS
227. f the time it is an application implementation error to use RTEMS_SELF from an ISR rtems_task_get_note rtems_task_set_note rtems_task_suspend rtems_task_resume e Interrupt Management rtems_interrupt_enable rtems interrupt disable rtems interrupt flash rtems interrupt is in progress rtems interrupt catch e Message Event and Signal Management rtems message queue send rtems message queue urgent rtems event send rtems_signal_send e Semaphore Management rtems semaphore release e Dual Ported Memory Management rtems port external to internal rtems port internal to external e IO Management The following services are safe to call from an ISR if and only if the device driver service invoked is also safe The IO Manager itself is safe but the invoked driver entry point may or may not be rtems_io_initialize rtems_io_open rtems_io_close 64 RTEMS C User s Guide rtems_io_read rtems io write rtems io control e Fatal Error Management rtems fatal error occurred e Multiprocessing rtems multiprocessing announce 6 4 Directives This section details the interrupt manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes Chapter 6 Interrupt Manager 65 6 4 1 INTERRUPT CATCH Establish an ISR CALLING SEQUENCE rtems status code rtems interrupt catch
228. fault is not required to appear in the attribute list although it is a good programming practice to specify default attributes If all defaults are desired the attribute RTEMS_DEFAULT_ATTRIBUTES should be specified on this call This example demonstrates the attribute_set parameter needed to create a local message queue with the task priority waiting queue discipline The attribute_set parameter to the rtems_message_queue_create directive could be either RTEMS_PRIORITY or RTEMS_LOCAL RTEMS_PRIORITY The attribute_set parameter can be set to RTEMS_PRIORITY because RTEMS_LOCAL is the default for all created message queues If a similar message queue were to be known globally then the attribute_set parameter would be RTEMS_GLOBAL RTEMS_PRIORITY 10 2 4 Building a MESSAGE_QUEUE_RECEIVE Option Set In general an option is built by a bitwise OR of the desired option components The set of valid options for the rtems_message_queue_receive directive are listed in the following table e RTEMS_WAIT task will wait for a message default e RTEMS_NO_WAIT task should not wait An option listed as a default is not required to appear in the option OR list although it is a good programming practice to specify default options If all defaults are desired the option RTEMS_DEFAULT_OPTIONS should be specified on this call This example demonstrates the option parameter needed to poll for a message to arrive The option parameter passed to the rtems_mes
229. fferences between the formats of ASRs and ISRs is limited to the meaning of the single argument passed to an ASR The ASR should have the following calling sequence and adhere to C calling conventions rtems_asr user_routine rtems_signal_set signals When the ASR returns to RTEMS the mode and execution path of the interrupted task or ASR is restored to the context prior to entering the ASR 12 4 Directives This section details the signal manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes 138 RTEMS C User s Guide 12 4 1 SIGNAL_CATCH Establish an ASR CALLING SEQUENCE rtems_status_code rtems_signal_catch rtems_asr_entry asr_handler rtems_mode mode DIRECTIVE STATUS CODES RTEMS SUCCESSFUL always successful DESCRIPTION This directive establishes an asynchronous signal routine ASR for the calling task The asr handler parameter specifies the entry point of the ASR If asr handler is NULL the ASR for the calling task is invalidated and all pending signals are cleared Any signals sent to a task with an invalid ASR are discarded The mode parameter specifies the execution mode for the ASR This execution mode supersedes the task s execution mode while the ASR is executing NOTES This directive will not cause the calling task to be preempted The following task mode constants are defined by
230. fully RTEMS_INVALID_ADDRESS invalid name pointer RTEMS_INVALID_ID invalid object id DESCRIPTION This service looks up the name for the object id specified and if found places the result in name NOTES This directive is strictly local and does not impact task scheduling 294 RTEMS C User s Guide 27 4 3 OBJECT_GET_NAME Obtain object name as string CALLING SEQUENCE char rtems object get name rtems id id size t length char name 23 DIRECTIVE STATUS CODES Returns a pointer to the name if successful or NULL otherwise DESCRIPTION This service looks up the name of the object specified by id and places it in the memory pointed to by name Every attempt is made to return name as a printable string even if the object has the Classic API thirty two bit style name NOTES This directive is strictly local and does not impact task scheduling Chapter 27 Object Services 295 27 4 4 OBJECT_SET_NAME Set object name CALLING SEQUENCE rtems status code rtems object set name rtems id id const char name DIRECTIVE STATUS CODES RTEMS SUCCESSFUL name looked up successfully RTEMS INVALID ADDRESS invalid name pointer RTEMS INVALID ID invalid object id DESCRIPTION This service sets the name of id to that specified by the string located at name NOTES This directive is strictly local and does not impact task scheduling If the object specified by id is of a class that has a s
231. g task is within bounds NOTES This method checks the current stack pointer against the high and low addresses of the stack memory allocated when the task was created and it looks for damage to the high water mark pattern for the worst case usage of the task being called Chapter 25 Stack Bounds Checker 283 25 4 2 STACK CHECKER REPORT USAGE Report Task Stack Usage CALLING SEQUENCE void rtems stack checker report usage void STATUS CODES NONE DESCRIPTION This routine prints a table with the peak stack usage and stack space allocation of every task in the system NOTES NONE Chapter 26 CPU Usage Statistics 285 26 CPU Usage Statistics 26 1 Introduction The CPU usage statistics manager is an RTEMS support component that provides a conve nient way to manipulate the CPU usage information associated with each task The routines provided by the CPU usage statistics manager are e rtems_cpu_usage_report Report CPU Usage Statistics e rtems_cpu_usage_reset Reset CPU Usage Statistics 26 2 Background When analyzing and debugging real time applications it is important to be able to know how much CPU time each task in the system consumes This support component provides a mechanism to easily obtain this information with little burden placed on the target The raw data is gathered as part of performing a context switch RTEMS keeps track of how many clock ticks have occurred which the task being switched out has b
232. gers Functions utilized by multiple managers such as scheduling dispatching and object man agement are provided in the executive core The executive core depends on a small set of CPU dependent routines Together these components provide a powerful run time en vironment that promotes the development of efficient real time application systems The following figure illustrates this organization Initialization Task Fatal Error Event Message Dual Ported Memory Partition T Subsequent chapters present a detailed description of the capabilities provided by each of the following RTEMS managers 8 RTEMS C User s Guide e initialization e task e interrupt e clock e timer e semaphore e message e event e signal e partition e region e dual ported memory e I O e fatal error e rate monotonic e user extensions e multiprocessing 1 6 User Customization and Extensibility As thirty two bit microprocessors have decreased in cost they have become increasingly common in a variety of embedded systems A wide range of custom and general purpose processor boards are based on various thirty two bit processors RTEMS was designed to make no assumptions concerning the characteristics of individual microprocessor families or of specific support hardware In addition RTEMS allows the system developer a high degree of freedom in customizing and extending its features RTEMS assumes the existence of a s
233. gment cannot be allocated one of the following situations applies e By default the calling task will wait forever to acquire the segment e Specifying the RTEMS_NO_WAIT option forces an immediate return with an error status code e Specifying a timeout limits the interval the task will wait before returning with an error status code If the task waits for the segment then it is placed in the region s task wait queue in either FIFO or task priority order All tasks waiting on a region are returned an error when the message queue is deleted 14 3 5 Releasing a Segment When a segment is returned to a region by the rtems_region_return_segment directive it is merged with its unallocated neighbors to form the largest possible segment The first task on the wait queue is examined to determine if its segment request can now be satisfied If so it is given a segment and unblocked This process is repeated until the first task s segment request cannot be satisfied 14 3 6 Obtaining the Size of a Segment The rtems_region_get_segment_size directive returns the size in bytes of the specified segment The size returned includes any extra memory included in the segment because of rounding up to a page size boundary 14 3 7 Changing the Size of a Segment The rtems_region_resize_segment directive is used to change the size in bytes of the specified segment The size may be increased or decreased When increasing the size of a segment it
234. gn Since the proposed standards are still in draft form RTEMS cannot and does not claim compliance However the status of the standard is being carefully monitored to guarantee that RTEMS provides the functionality specified in the standard Once approved RTEMS will be made compliant This document is a detailed users guide for a functionally compliant real time multiprocessor executive It describes the user interface and run time behavior of Release 4 9 2 of the C interface to RTEMS Chapter 1 Overview 5 1 Overview 1 1 Introduction RTEMS Real Time Executive for Multiprocessor Systems is a real time executive ker nel which provides a high performance environment for embedded military applications including the following features e multitasking capabilities e homogeneous and heterogeneous multiprocessor systems e event driven priority based preemptive scheduling e optional rate monotonic scheduling e intertask communication and synchronization e priority inheritance e responsive interrupt management e dynamic memory allocation e high level of user configurability This manual describes the usage of RT EMS for applications written in the C programming language Those implementation details that are processor dependent are provided in the Applications Supplement documents A supplement document which addresses specific architectural issues that affect RTEMS is provided for each processor type that is supported 1
235. hat it has been allocated then the task creating the semaphore is considered the current holder of the semaphore At create time the method for ordering waiting tasks in the semaphore s task wait queue by FIFO or task priority is specified Additionally the priority inheritance or priority ceiling algorithm may be selected for local binary semaphores that use the priority task wait queue blocking discipline If the priority ceiling algorithm is selected then the highest priority of any task which will attempt to obtain this semaphore must be specified RTEMS allocates a Semaphore Control Block SMCB from the SMCB free list This data structure is used by RTEMS to manage the newly created semaphore Also a unique semaphore ID is generated and returned to the calling task 9 3 2 Obtaining Semaphore IDs When a semaphore is created RTEMS generates a unique semaphore ID and assigns it to the created semaphore until it is deleted The semaphore ID may be obtained by either of two methods First as the result of an invocation of the rtems_semaphore_create directive the semaphore ID is stored in a user provided location Second the semaphore ID may be obtained later using the rtems_semaphore_ident directive The semaphore ID is used by other semaphore manager directives to access this semaphore 9 3 3 Acquiring a Semaphore The rtems_semaphore_obtain directive is used to acquire the specified semaphore A simplified version of the rtems_semapho
236. he calling task will wait forever NOTES The following message receive option constants are defined by RTEMS e RTEMS WAIT task will wait for a message default e RTEMS NO WAIT task should not wait Chapter 10 Message Manager 125 Receiving a message from a global message queue which does not reside on the local node will generate a request to the remote node to obtain a message from the specified message queue If no message is available and RTEMS_WAIT was specified then the task must be blocked until a message is posted A proxy is allocated on the remote node to represent the task until the message is posted A clock tick is required to support the timeout functionality of this directive 126 RTEMS C User s Guide 10 4 8 MESSAGE QUEUE GET NUMBER PENDING Get number of messages pending on a queue CALLING SEQUENCE rtems status code rtems message queue get number pending rtems id id uint32 t count DIRECTIVE STATUS CODES RTEMS SUCCESSFUL number of messages pending returned successfully RTEMS INVALID ADDRESS count is NULL RTEMS INVALID ID invalid queue id DESCRIPTION This directive returns the number of messages pending on this message queue in count If no messages are present on the queue count is set to zero NOTES Getting the number of pending messages on a global message queue which does not reside on the local node will generate a request to the remote node to actually obtain
237. he enumerated type which specifies the categories of multiprocessing messages For example one of the classes is for messages that must be processed by the Task Manager rtems_mode is the data type used to manage and dynamically manipulate the exe cution mode of an RTEMS task rtems mpci entry is the return type of an RTEMS MPCI routine rtems mpci get packet entry is the address of the entry point to the get packet routine for an MPCI implementation rtems mpci initialization entry is the address of the entry point to the initial ization routine for an MPCI implementation rtems mpci receive packet entry is the address of the entry point to the receive packet routine for an MPCI implementation rtems mpci return packet entry is the address of the entry point to the return packet routine for an MPCI implementation rtems mpci send packet entry is the address of the entry point to the send packet routine for an MPCI implementation rtems mpci table is the data structure containing the configuration information for an MPCI rtems name is the data type used to contain the name of a Classic API object It is an unsigned thirty two bit integer which can be treated as a numeric value or initialized using rtems build name to contain four ASCII characters rtems option is the data type used to specify which behavioral options the caller desires It is commonly used with potentially blocking directives to specify whether the call
238. hore created with an initial count of three When a task requires access to one of the printers it issues the rtems semaphore obtain directive to obtain access to a printer If a printer is not currently available the task can wait for a printer to become available or return immediately When the task has completed printing it should issue the rtems semaphore release directive to allow other tasks access to the printer Task synchronization may be achieved by creating a semaphore with an initial count of zero One task waits for the arrival of another task by issuing a rtems semaphore obtain directive when it reaches a synchronization point The other task performs a correspond ing rtems semaphore release operation when it reaches its synchronization point thus unblocking the pending task 9 2 1 Nested Resource Access Deadlock occurs when a task owning a binary semaphore attempts to acquire that same semaphore and blocks as result Since the semaphore is allocated to a task it cannot be 100 RTEMS C User s Guide deleted Therefore the task that currently holds the semaphore and is also blocked waiting for that semaphore will never execute again RTEMS addresses this problem by allowing the task holding the binary semaphore to obtain the same binary semaphore multiple times in a nested manner Each rtems_semaphore_ obtain must be accompanied with a rtems_semaphore_release The semaphore will only be made available for acquisition by o
239. ic round robin scheduling algorithm The length of time allocated to each task is known as the quantum or timeslice The system s timeslice is defined as an integral number of ticks and is specified in the Configuration Table The timeslice is defined for the entire system of tasks but timeslicing is enabled and disabled on a per task basis The rtems_clock_tick directive implements timeslicing by decrementing the running task s time remaining counter when both timeslicing and preemption are enabled If the task s timeslice has expired then that task will be preempted if there exists a ready task of equal priority 7 2 4 Delays A sleep timer allows a task to delay for a given interval or up until a given time and then wake and continue execution This type of timer is created automatically by the rtems_task_wake_after and rtems_task_wake_when directives and as a result does not have an RTEMS ID Once activated a sleep timer cannot be explicitly deleted Each task may activate one and only one sleep timer at a time 7 2 5 Timeouts Timeouts are a special type of timer automatically created when the timeout option is used on the rtems_message_queue_receive rtems_event_receive rtems_semaphore_ obtain and rtems_region_get_segment directives Each task may have one and only one timeout active at a time When a timeout expires it unblocks the task with a timeout status code 7 3 Operations 7 3 1 Announcing a Tick RTEMS provides
240. ich is driver dependent mode An entry in a task s control block that is used to determine if the task allows preemption timeslicing processing of signals and the interrupt disable level used by the task MPCI An acronym for Multiprocessor Communications Interface Layer multiprocessing The simultaneous execution of two or more processes by a multiple processor computer system multiprocessor A computer with multiple CPUs available for executing applications Multiprocessor Communications Interface Layer A set of user provided routines which enable the nodes in a multi processor system to communicate with one another Multiprocessor Configuration Table The data structure defining the characteristics of the multiprocessor target system with which RTEMS will communicate multitasking The alternation of execution amongst a group of processes on a single CPU A scheduling algorithm is used to determine which process executes at which time mutual exclusion A term used to describe the act of preventing other tasks from ac cessing a resource simultaneously nested A term used to describe an ASR that occurs during another ASR or an ISR that occurs during another ISR node A term used to reference a processor running RTEMS in a multipro cessor system non existent The state occupied by an uncreated or deleted task numeric coprocessor A component used in computer systems to enhance performance in mathematically intensive situa
241. ics in the TCB s extended memory area When a task context switch is being executed the TASK_SWITCH extension could read a real time clock to calculate how long the task be ing swapped out has run as well as timestamp the starting time for the task being swapped in If used the extended memory area for the TCB should be allocated and the TCB extension pointer should be set at the time the task is created or started by either the T ASK CREATE or TASK START extension The application is responsible for managing this extended memory area for the TCBs The memory may be reinitialized by the TASK RESTART extension and should be deallocated by the TASK DELETE extension when the task is Chapter 22 User Extensions Manager 233 deleted Since the TCB extension buffers would most likely be of a fixed size the RTEMS partition manager could be used to manage the application s extended memory area The application could create a partition of fixed size TCB extension buffers and use the partition manager s allocation and deallocation directives to obtain and release the extension buffers 22 2 3 Extensions The sections that follow will contain a description of each extension Each section will contain a prototype of a function with the appropriate calling sequence for the corresponding extension The names given for the C function and its arguments are all defined by the user The names used in the examples were arbitrarily chosen and impose no naming
242. ics of a periodic task loop But it is just information The period statistics reported must be analyzed by the user in terms of what the applications is For example in an application where priorities are assigned by the Rate Monotonic Algorithm it would be very undesirable for high priority i e frequency tasks to miss their period Similarly in nearly any application if a task were supposed to execute its periodic loop every 10 milliseconds and it averaged 11 milliseconds then application requirements are not being met The information reported can be used to determine the hot spots in the application Given a period s id the user can determine the length of that period From that information and the CPU usage the user can calculate the percentage of CPU time consumed by that periodic task For example a task executing for 20 milliseconds every 200 milliseconds is consuming 10 percent of the processor s execution time This is usually enough to make it a good candidate for optimization However execution time alone is not enough to gauge the value of optimizing a particular task It is more important to optimize a task executing 2 millisecond every 10 milliseconds 20 percent of the CPU than one executing 10 milliseconds every 100 10 percent of the CPU As a general rule of thumb the higher frequency at which a task executes the more important it is to optimize that task 19 2 3 Rate Monotonic Manager Definitions A periodic task
243. ignal set to a task with an ASR that is both valid and enabled then the signal set is caught and the ASR will execute the next time the task is dispatched to run NOTES Sending a signal set to a task has no effect on that task s state If a signal set is sent to a blocked task then the task will remain blocked and the signals will be processed when the task becomes the running task Sending a signal set to a global task which does not reside on the local node will generate a request telling the remote node to send the signal set to the specified task Chapter 13 Partition Manager 141 13 Partition Manager 13 1 Introduction The partition manager provides facilities to dynamically allocate memory in fixed size units The directives provided by the partition manager are e rtems partition create Create a partition e rtems partition ident Get ID of a partition e rtems partition delete Delete a partition e rtems partition get buffer Get buffer from a partition e rtems partition return buffer Return buffer to a partition 13 2 Background 13 2 1 Partition Manager Definitions A partition is a physically contiguous memory area divided into fixed size buffers that can be dynamically allocated and deallocated Partitions are managed and maintained as a list of buffers Buffers are obtained from the front of the partition s free buffer chain and returned to the rear of the same chain When a buffer is on the free buffer ch
244. iguration Table 7 2 2 Time and Date Data Structures The clock facilities of the clock manager operate upon calendar time These directives utilize the following date and time structure for the native time and date format struct rtems tod control 1 uint32 t year greater than 1987 uint32 t month 1 12 uint32 t day 1 31 uint32_t hour 0 23 uint32 t minute 0 59 x uint32 t second 0 59 x uint32 t ticks elapsed between seconds Js typedef struct rtems tod control rtems time of day 72 RTEMS C User s Guide The native date and time format is the only format supported when setting the system date and time using the rtems_clock_get directive Some applications expect to operate on a UNIX style date and time data structure The rtems_clock_get directive can optionally return the current date and time in the following structure typedef struct uint32_t seconds seconds since RTEMS epoch uint32_t microseconds since last second rtems_clock_time_value The seconds field in this structure is the number of seconds since the POSIX epoch of January 1 1970 but will never be prior to the RTEMS epoch of January 1 1988 7 2 3 Clock Tick and Timeslicing Timeslicing is a task scheduling discipline in which tasks of equal priority are executed for a specific period of time before control of the CPU is passed to another task It is also sometimes referred to as the automat
245. ill match one of the periods with that name However this period id is not guaranteed to correspond to the desired period The period id is used to access this period in other rate monotonic manager directives NOTES This directive will not cause the running task to be preempted Chapter 19 Rate Monotonic Manager 209 19 4 3 RATE MONOTONIC CANCEL Cancel a period CALLING SEQUENCE rtems status code rtems rate monotonic cancel rtems id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL period canceled successfully RTEMS INVALID ID invalid rate monotonic period id RTEMS NOT OWNER OF RESOURCE rate monotonic period not created by calling task DESCRIPTION This directive cancels the rate monotonic period id This period will be reinitiated by the next invocation of rtems rate monotonic period with id NOTES This directive will not cause the running task to be preempted The rate monotonic period specified by id must have been created by the calling task 210 RTEMS C User s Guide 19 4 4 RATE MONOTONIC_DELETE Delete a rate monotonic period CALLING SEQUENCE rtems_status_code rtems_rate_monotonic_delete rtems_id id 23 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL period deleted successfully RTEMS INVALID ID invalid rate monotonic period id DESCRIPTION This directive deletes the rate monotonic period specified by id If the period is running it is automatically canceled The PCB for the deleted
246. ined by the Classic API Initialization Tasks Table By default the value is 1 which is the highest priority in the Classic API 248 RTEMS C User s Guide CONFIGURE_INIT_TASK_ATTRIBUTES is the task attributes of the single initialization task defined by the Classic API Initialization Tasks Table By default the value is RTEMS_DEFAULT_ATTRIBUTES CONFIGURE_INIT_TASK_ENTRY_POINT is the entry point a k a function name of the single initialization task defined by the Classic API Initialization Tasks Table By default the value is Init CONFIGURE_INIT_TASK_INITIAL_MODES is the initial execution mode of the single initialization task defined by the Classic API Initialization Tasks Table By default the value is RTEMS_NO_PREEMPT CONFIGURE_INIT_TASK_ARGUMENTS is the task argument of the single initialization task defined by the Classic API Initialization Tasks Table By default the value is 0 23 2 8 POSIX API Configuration The parameters in this section are used to configure resources for the RTEMS POSIX API They are only relevant if the POSIX API is enabled at configure time using the enable posix option CONFIGURE_MAXIMUM_POSIX_THREADS is the maximum number of POSIX API threads that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_POSIX_MUTEXES is the maximum number of POSIX API mu texes that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES is the maximum number of POSIX
247. inimize conversion overhead Another issue in the design of shared data structures is the alignment of data structure elements Alignment is both processor and compiler implementation dependent For exam ple some processors allow data elements to begin on any address boundary while others impose restrictions Common restrictions are that data elements must begin on either an even address or on a long word boundary Violation of these restrictions may cause an exception or impose a performance penalty Other issues which commonly impact the design of shared data structures include the rep resentation of floating point numbers bit fields decimal data and character strings In addition the representation method for negative integers could be one s or two s comple ment These factors combine to increase the complexity of designing and manipulating data structures shared between processors RTEMS addressed these issues in the design of the packets used to communicate between nodes The RTEMS packet format is designed to allow the MPCI layer to perform all necessary conversion without burdening the developer with the details of the RT EMS packet format As a result the MPCI layer must be aware of the following e All packets must begin on a four byte boundary e Packets are composed of both RTEMS and application data All RTEMS data is treated as thirty two 32 bit unsigned quantities and is in the first RTEMS MINIMUM UNSIGNED32S TO C
248. interface includes both the source code interfaces and run time behavior as seen by a real time application It does not include the details of how a kernel implements these functions The standard s goal is to serve as a complete definition of external interfaces so that application code that conforms to these interfaces will execute properly in all real time executive environments With the use of a standards compliant executive routines that acquire memory blocks create and manage message queues establish and use semaphores and send and receive signals need not be redeveloped for a different real time environment as long as the new environment is compliant with the standard Software developers need only concentrate on the hardware dependencies of the real time system Furthermore most hardware dependencies for real time applications can be localized to the device drivers A compliant executive provides simple and flexible real time multiprocessing It easily lends itself to both tightly coupled and loosely coupled configurations depending on the system hardware configuration Objects such as tasks queues events signals semaphores and memory blocks can be designated as global objects and accessed by any task regardless of which processor the object and the accessing task reside 2 RTEMS C User s Guide The acceptance of a standard for real time executives will produce the same advantages enjoyed from the push for UNIX standardization
249. ion The developer is then able to concentrate solely on the application By using standard software components the time and cost required to develop sophisticated real time applications is significantly reduced 1 4 RTEMS Application Architecture One important design goal of RTEMS was to provide a bridge between two critical layers of typical real time systems As shown in the following figure RTEMS serves as a buffer between the project dependent application code and the target hardware Most hardware dependencies for real time applications can be localized to the low level device drivers Chapter 1 Overview 7 Application Dependent Software Standard Application Components evice RTEMS rivers Target Hardware The RTEMS I O interface manager provides an efficient tool for incorporating these hard ware dependencies into the system while simultaneously providing a general mechanism to the application code that accesses them A well designed real time system can benefit from this architecture by building a rich library of standard application components which can be used repeatedly in other real time projects 1 5 RTEMS Internal Architecture RTEMS can be viewed as a set of layered components that work in harmony to provide a set of services to a real time application system The executive interface presented to the application is formed by grouping directives into logical sets called resource mana
250. iority of the task holding the semaphore is increased to that of the blocking task When the task holding the task completely releases the binary semaphore i e not for a nested release the holder s priority is restored to the value it had before any higher priority was inherited The RTEMS implementation of the priority inheritance algorithm takes into account the scenario in which a task holds more than one binary semaphore The holding task will execute at the priority of the higher of the highest ceiling priority or at the priority of the highest priority task blocked waiting for any of the semaphores the task holds Only when the task releases ALL of the binary semaphores it holds will its priority be restored to the normal value 9 2 4 Priority Ceiling Priority ceiling is an algorithm that calls for the lower priority task holding a resource to have its priority increased to that of the highest priority task which will EVER block waiting for that resource This algorithm addresses the problem of priority inversion although it avoids the possibility of changing the priority of the task holding the resource multiple times The priority ceiling algorithm will only change the priority of the task holding the Chapter 9 Semaphore Manager 101 resource a maximum of one time The ceiling priority is set at creation time and must be the priority of the highest priority task which will ever attempt to acquire that semaphore RTEMS supports prio
251. iprocessor Configuration Table The maximum_nodes field and the number of global objects maximum_global_objects is required to be the same on all nodes in a system The node number is used by RTEMS to identify each node when performing remote oper ations Thus the Multiprocessor Communications Interface Layer MPCI must be able to route messages based on the node number 24 2 2 Global Objects All RTEMS objects which are created with the GLOBAL attribute will be known on all other nodes Global objects can be referenced from any node in the system although certain directive specific restrictions e g one cannot delete a remote object may apply A task does not have to be global to perform operations involving remote objects The maximum number of global objects is the system is user configurable and can be found in the maximum_global_objects field in the Multiprocessor Configuration Table The distribution of tasks to processors is performed during the application design phase Dynamic task relocation is not supported by RTEMS 24 2 3 Global Object Table RTEMS maintains two tables containing object information on every node in a multipro cessor system a local object table and a global object table The local object table on each node is unique and contains information for all objects created on this node whether those objects are local or global The global object table contains information regarding all global objects in the system and
252. ir Device names are typically registered as part of the device driver initialization sequence The rtems io lookup directive is used to determine the major minor number pair associated with the specified device name The use of these di rectives frees the application from being dependent on the arbitrary assignment of major numbers in a particular application No device naming conventions are dictated by RT EMS 16 3 2 Accessing an Device Driver The I O manager provides directives which enable the application program to utilize device drivers in a standard manner There is a direct correlation between the RTEMS I O manager directives rtems io initialize rtems io open rtems io close rtems io read rtems io write and rtems io control and the underlying device driver entry points 174 RTEMS C User s Guide 16 4 Directives This section details the I O manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes Chapter 16 I O Manager 175 16 4 1 IO REGISTER DRIVER Register a device driver CALLING SEQUENCE rtems status code rtems io register driver rtems device major number major rtems driver address table xdriver table rtems device major number registered major J DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL successfully registered RTEMS_INVALID_ADDRESS invalid registered major pointer RTEMS_INVALID_ADD
253. ir own POSIX API Initialization Threads Table This table should be named POSIX_Initialization_threads By default this is not defined CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT is the entry point a k a function name of the single initialization thread defined by the POSIX API Initialization Threads Table By default the value is POSIX_Init CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE is the stack size of the single initial ization thread defined by the POSIX API Initialization Threads Table By default value is twice the configured minimum stack size 23 2 10 ITRON API Configuration The parameters in this section are used to configure resources for the RTEMS ITRON API They are only relevant if the POSIX API is enabled at configure time using the enable itron option CONFIGURE_MAXIMUM_ITRON_TASKS is the maximum number of ITRON API tasks that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_ITRON_SEMAPHORES is the maximum number of ITRON API semaphores that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_ITRON_EVENTFLAGS is the maximum number of ITRON API eventflags that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_ITRON_MAILBOXES is the maximum number of ITRON API mailboxes that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_ITRON_MESSAGE_BUFFERS is the maximum number of ITRON API message buffers that can be concurrently active The default is 0 CONFIGURE_MAXIMUM_ITRO
254. is directive can be invoked by RTEMS or by the user s application code including initialization tasks other tasks and ISRs NOTES This directive supports local operations only Unless the user defined error extension takes special actions such as restarting the calling task this directive WILL NOT RETURN to the caller The user defined extension for this directive may wish to initiate a global shutdown Chapter 18 Scheduling Concepts 189 18 Scheduling Concepts 18 1 Introduction The concept of scheduling in real time systems dictates the ability to provide immediate response to specific external events particularly the necessity of scheduling tasks to run within a specified time limit after the occurrence of an event For example software em bedded in life support systems used to monitor hospital patients must take instant action if a change in the patient s status is detected The component of RTEMS responsible for providing this capability is appropriately called the scheduler The scheduler s sole purpose is to allocate the all important resource of processor time to the various tasks competing for attention The RTEMS scheduler allocates the processor using a priority based preemptive algorithm augmented to provide round robin characteristics within individual priority groups The goal of this algorithm is to guarantee that the task which is executing on the processor at any point in time is the one with the highest pri
255. is directive with the RTEMS NO ASR indicator specified in mode The set of task mode constants and each mode s corresponding mask constant is provided in the following table e RTEMS PREEMPT is masked by RTEMS PREEMPT MASK and enables preemption e RTEMS NO PREEMPT is masked by RTEMS_PREEMPT_MASK and disables preemption e RTEMS NO TIMESLICE is masked by RTEMS TIMESLICE MASK and disables timeslicing e RTEMS TIMESLICE is masked by RTEMS TIMESLICE MASK and enables timeslicing e RTEMS ASR is masked by RTEMS_ASR_MASK and enables ASR processing e RTEMS NO ASR is masked by RTEMS_ASR_MASK and disables ASR processing e RTEMS INTERRUPT LEVEL O is masked by RTEMS INTERRUPT MASK and enables all interrupts e RTEMS INTERRUPT LEVEL n is masked by RTEMS_INTERRUPT_MASK and sets inter rupts level n 52 RTEMS C User s Guide 5 4 12 TASK_GET_NOTE Get task notepad entry CALLING SEQUENCE rtems_status_code rtems_task_get_note rtems_id id uint32_t notepad uint32_t note J DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL note obtained successfully RTEMS_INVALID_ADDRESS note is NULL RTEMS_INVALID_ID invalid task id RTEMS_INVALID_NUMBER invalid notepad location DESCRIPTION This directive returns the note contained in the notepad location of the task specified by id NOTES This directive will not cause the running task to be preempted If id is set to RTEMS_SELF the calling task accesses its own notepad
256. is possible that the request cannot be satisfied This directive provides functionality similar to the realloc function in the Standard C Library 14 3 8 Deleting a Region A region can be removed from the system and returned to RTEMS with the rtems_region_ delete directive When a region is deleted its control block is returned to the RNCB free list A region with segments still allocated is not allowed to be deleted Any task attempting to do so will be returned an error As a result of this directive all tasks blocked waiting to 152 RTEMS C User s Guide obtain a segment from the region will be readied and returned a status code which indicates that the region was deleted 14 4 Directives This section details the region manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes Chapter 14 Region Manager 153 14 4 1 REGION_CREATE Create a region CALLING SEQUENCE rtems_status_code rtems_region_create rtems_name name void starting address uint32 t length uint32 t page size rtems attribute attribute set rtems id id 5 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL region created successfully RTEMS INVALID NAME invalid region name RTEMS INVALID ADDRESS id is NULL RTEMS INVALID ADDRESS starting address is NULL RTEMS INVALID ADDRESS address not on four byte boundary RTEMS TOO MANY
257. iw oa Wena ess a pees 24 4 2 4 Initialization Manager Failure 00002 0000 24 4 3 Operations n tivssacapnnne poder sae ERG IRE CRDI CC ER EE RA R ed 24 4 3 1 Initializing RTEMS ssssesseeseeese eee 24 4 89 20 Shutting Down RTEMS esses 25 4 4 JDurectlvOS e ke eb ede pP PREISE URECRPERG AG RO Pbpqiee d 25 4 4 4 INITIALIZE DATA STRUCTURES Initialize RTEMS Data Sbfuctubes 5 62D ope e retenti et ele ens 26 ii RTEMS C User s Guide 4 4 2 INITIALIZE BEFORE DRIVERS Perform Initialization Before Device Drivers 000 e cence re rsrina suis 24 4 4 8 INITIALIZE DEVICE DRIVERS Initialize Device Drivers EET 28 4 4 4 INITIALIZE_START_MULTITASKING Complete Initialization and Start Multitasking 29 4 4 5 SHUTDOWN EXECUTIVE Shutdown RTEMS 30 5 Task Manager adu sh epE RS EC EDe Rn REdoea 31 Hel Introd ction siu e iad esd ee bon Saag dead br b ERE amu eR ol 5 2 JBaeckero ndk cic dert Robbe LE edid E siccis 31 5 2 Task Definition sssseeeeeeeee see al 5 2 2 Task Control Block eee reir kr tet ee bct 32 5 2 3 Task States oci ese rere Eo RR uS bere p RESERVE gs 32 5 2 4 Task Priory 2s Ie cb rces cre i ERR 32 5 2 5 Task Mode iie se exer e ob pcena hee 33 5 2 6 Accessing Task Arguments 2 000 e cece ee 34 5 2 7 Floating Point Considerations 0 eee e eee 34 5 2 8 Per Task Variables 0 0 ce
258. ize of a segment CALLING SEQUENCE rtems status code rtems region get segment size rtems id id void segment size t size J DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL segment obtained successfully RTEMS_INVALID_ADDRESS segment is NULL RTEMS_INVALID_ADDRESS size is NULL RTEMS_INVALID_ID invalid region id RTEMS_INVALID_ADDRESS segment address not in region DESCRIPTION This directive obtains the size in bytes of the specified segment NOTES The actual length of the allocated segment may be larger than the requested size because a segment size is always a multiple of the region s page size Chapter 14 Region Manager 161 14 4 8 REGION RESIZE SEGMENT Change size of a segment CALLING SEQUENCE rtems status code rtems region resize segment rtems id id void segment size t size size t old size DIRECTIVE STATUS CODES RTEMS SUCCESSFUL segment obtained successfully RTEMS INVALID ADDRESS segment is NULL RTEMS INVALID ADDRESS old size is NULL RTEMS INVALID ID invalid region id RTEMS INVALID ADDRESS segment address not in region RTEMS_UNSATISFIED unable to make segment larger DESCRIPTION This directive is used to increase or decrease the size of a segment When increasing the size of a segment it is possible that there is not memory available contiguous to the segment In this case the request is unsatisfied NOTES If an attempt to increase the size of a
259. k s state is ready following a call to the rtems_task_resume directive then the task is available for scheduling return code A value returned by RTEMS directives to indicate the completion status of the directive RNCB An acronym for Region Control Block round robin A task scheduling discipline in which tasks of equal priority are exe cuted in the order in which they are made ready RS 232 A standard for serial communications 344 running schedule schedulable segments semaphore RTEMS C User s Guide The state of a rate monotonic timer while it is being used to delin eate a period The timer exits this state by either expiring or being canceled The process of choosing which task should next enter the executing state A set of tasks which can be guaranteed to meet their deadlines based upon a specific scheduling algorithm Variable sized memory blocks allocated from a region An RTEMS object which is used to synchronize tasks and provide mutually exclusive access to resources Semaphore Control Block shared memory signal signal set SMCB soft real time system sporadic task stack status code suspend synchronous system call target task Task Control Block A data structure associated with each semaphore used by RTEMS to manage that semaphore Memory which is accessible by multiple nodes in a multiprocessor system An RTEMS provided mechanism to communicate asynchron
260. k restarted successfully RTEMS INVALID ID task id invalid RTEMS INCORRECT STATE task never started RTEMS ILLEGAL ON REMOTE 0BJECT cannot restart remote task DESCRIPTION This directive resets the task specified by id to begin execution at its original starting address T he task s priority and execution mode are set to the original creation values If the task is currently blocked RTEMS automatically makes the task ready A task can be restarted from any state except the dormant state The task s starting argument is contained in argument This argument can be a single value or an index into an array of parameter blocks The type of this numeric argument is an unsigned integer type with the property that any valid pointer to void can be converted to this type and then converted back to a pointer to void The result will compare equal to the original pointer This new argument may be used to distinguish between the initial rtems task start of the task and any ensuing calls to rtems task restart of the task This can be beneficial in deleting a task Instead of deleting a task using the rtems task delete directive a task can delete another task by restarting that task and allowing that task to release resources back to RTEMS and then delete itself NOTES If id is RTEMS SELF the calling task will be restarted and will not return from this directive The calling task will be preempted if its preemption mode is enabled and
261. ker The stack checker is initialized automatically when its task create extension runs for the first time The application must include the stack bounds checker extension set in its set of Initial Extensions This set of extensions is defined as STACK_CHECKER_EXTENSION If using lt rtems confdefs h gt for Configuration Table generation then all that is necessary is to define the macro STACK_CHECKER_ON before including lt rtems confdefs h gt as shown below define STACK_CHECKER_ON include lt rtems confdefs h gt 25 3 2 Checking for Blown Task Stack The application may check whether the stack pointer of currently executing task is within proper bounds at any time by calling the rtems_stack_checker_is_blown method This method return FALSE if the task is operating within its stack bounds and has not damaged its pattern area 25 3 3 Reporting Task Stack Usage The application may dynamically report the stack usage for every task in the system by calling the rtems_stack_checker_report_usage routine This routine prints a table with the peak usage and stack size of every task in the system The following is an example of the report generated ID NAME LOW HIGH AVAILABLE USED 0x04010001 IDLE 0x003e8a60 0x003e9667 2952 200 0x08010002 TA1 0x003e5750 0x003eT7b57 9096 1168 0x08010003 TA2 0Ox003e31c8 Ox003e55cf 9096 1168 0x08010004 TA3 0x003e0c40 0x003e3047 9096 1104 Oxffffffff INTR Ox003ecfcO Ox003effbf 12160 128 Notice the last time
262. ks are started at the same time then the deadlines will always be met for any combination of start times A key point with this rule is that ALL periodic tasks are assumed to start at the exact same instant in time Although this assumption may seem to be invalid RTEMS makes it quite easy to ensure By having a non preemptible user initialization task all application tasks regardless of priority can be created and started before the initialization deletes itself This technique ensures that all tasks begin to compete for execution time at the same instant when the user initialization task deletes itself 19 2 5 5 First Deadline Rule Example The First Deadline Rule can ensure schedulability even when the Processor Utilization Rule fails The example below is a modification of the Processor Utilization Rule example where task execution time has been increased from 15 to 25 units The following table details the RMS priority period execution time and processor utilization for each task Task RMS Period Execution Processor Priority Time Utilization 1 High 100 25 0 25 2 Medium 200 50 0 25 3 Low 300 100 0 33 The total processor utilization for the modified task set is 0 83 which is above the upper bound of 3 2 1 3 1 or 0 779 imposed by the Processor Utilization Rule Therefore this task set is not guaranteed to be schedulable using RMS However the First Deadline Rule can guarantee the schedula
263. l to rtems clock set then the RTEMS NOT DEFINED status code is returned NOTES This directive is callable from an ISR This directive will not cause the running task to be preempted Re initializing RTEMS causes the system date and time to be reset to an uninitialized state Another call to rtems_clock_set is required to re initialize the system date and time to application specific specifications Chapter 7 Clock Manager 77 7 4 4 CLOCK_GET_TOD_TIMEVAL Get date and time in timeval format CALLING SEQUENCE rtems_status_code rtems_clock_get_tod struct timeval time 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL current time obtained successfully RTEMS NOT DEFINED system date and time is not set RTEMS INVALID ADDRESS time is NULL DESCRIPTION This directive obtains the system date and time in POSIX struct timeval format If the date and time has not been set with a previous call to rtems clock set then the RTEMS NOT DEFINED status code is returned NOTES This directive is callable from an ISR This directive will not cause the running task to be preempted Re initializing RTEMS causes the system date and time to be reset to an uninitialized state Another call to rtems_clock_set is required to re initialize the system date and time to application specific specifications 78 RTEMS C User s Guide 7 4 5 CLOCK_GET_SECONDS_SINCE_EPOCH Get seconds since epoch CALLING SEQUENCE rtems status c
264. ld NOT modify the memory outside of any obtained segments and within the region s boundaries while the region is currently active in the system Upon return to the region the free block is coalesced with its neighbors if free on both sides to produce the largest possible unused block 14 2 2 Building an Attribute Set In general an attribute set is built by a bitwise OR of the desired attribute components The set of valid region attributes is provided in the following table e RTEMS_FIFO tasks wait by FIFO default e RTEMS PRIORITY tasks wait by priority Attribute values are specifically designed to be mutually exclusive therefore bitwise OR and addition operations are equivalent as long as each attribute appears exactly once in the component list An attribute listed as a default is not required to appear in the attribute 150 RTEMS C User s Guide list although it is a good programming practice to specify default attributes If all defaults are desired the attribute RTEMS_DEFAULT_ATTRIBUTES should be specified on this call This example demonstrates the attribute_set parameter needed to create a region with the task priority waiting queue discipline The attribute_set parameter to the rtems_region_ create directive should be RTEMS_PRIORITY 14 2 3 Building an Option Set In general an option is built by a bitwise OR of the desired option components The set of valid options for the rtems_region_get_segment directive are list
265. le The POSIX API Configuration Table is used to configure the managers which constitute the POSIX API for a particular application For example the user can configure the maximum number of threads for this application The POSIX API Configuration Table is defined in the following C structure typedef struct void thread_entry void posix_initialization_threads_table typedef struct int int int int int int int int int int int int maximum_threads maximum_mutexes maximum_condition_variables maximum keys maximum timers maximum queued signals maximum message queues maximum semaphores maximum barriers maximum rwlocks maximum spinlocks number of initialization tasks posix initialization threads table User initialization tasks table posix api configuration table maximum threads is the maximum number of threads that can be concurrently active created in the system including initialization threads When using the rtems confdefs h mechanism for configuring an RT EMS appli cation the value for this field corresponds to the setting of the macro CONFIGURE MAXIMUM POSIX THREADS If not defined by the applica tion then the CONFIGURE MAXIMUM POSIX THREADS macro defaults to 0 258 maximum_mutexes RTEMS C User s Guide is the maximum number of mutexes that can be concurrently ac tive in the system When using the rtems confdefs h mechanism for configuring an RTEMS app
266. le when a task delays for an interval of ten ticks it is implied that the task will not execute until ten clock ticks have occurred All intervals are specified using data type rtems_interval A characteristic of interval timing is that the actual interval period may be a fraction of a tick less than the interval requested This occurs because the time at which the delay timer is set up occurs at some time between two clock ticks Therefore the first countdown tick occurs in less than the complete time interval for a tick This can be a problem if the clock granularity is large The rate monotonic scheduling algorithm is a hard real time scheduling methodology This methodology provides rules which allows one to guarantee that a set of independent periodic tasks will always meet their deadlines even under transient overload conditions The rate monotonic manager provides directives built upon the Clock Manager s interval timer support routines Interval timing is not sufficient for the many applications which require that time be kept in wall time or true calendar form Consequently RTEMS maintains the current date and time This allows selected time operations to be scheduled at an actual calendar date and time For example a task could request to delay until midnight on New Year s Eve before lowering the ball at Times Square The data type rtems time of day is used to specify calendar time in RTEMS services See Section 7 2 2 Time and Date
267. le sized units The directives provided by the region manager are e rtems_region_create Create a region e rtems_region_ident Get ID of a region e rtems region delete Delete a region e rtems region extend Add memory to a region e rtems region get segment Get segment from a region e rtems region return segment Return segment to a region e rtems region get segment size Obtain size of a segment e rtems region resize segment Change size of a segment 14 2 Background 14 2 1 Region Manager Definitions A region makes up a physically contiguous memory space with user defined boundaries from which variable sized segments are dynamically allocated and deallocated A segment is a variable size section of memory which is allocated in multiples of a user defined page size This page size is required to be a multiple of four greater than or equal to four For example if a request for a 350 byte segment is made in a region with 256 byte pages then a 512 byte segment is allocated Regions are organized as doubly linked chains of variable sized memory blocks Memory requests are allocated using a first fit algorithm If available the requester receives the number of bytes requested rounded up to the next page size RTEMS requires some over head from the region s memory for each segment that is allocated Therefore an application should only modify the memory of a segment that has been obtained from the region The application shou
268. le the task s worst case stack usage as well as the worst case interrupt stack usage This is necessary because the worst case interrupt nesting could occur while any task is executing On many processors without dedicated hardware managed interrupt stacks RTEMS man ages a dedicated interrupt stack in software If this capability is supported on a CPU then it is logically equivalent to the processor supporting a separate interrupt stack in hardware Chapter 21 Board Support Packages 227 21 3 Device Drivers Device drivers consist of control software for special peripheral devices and provide a logical interface for the application developer The RTEMS I O manager provides directives which allow applications to access these device drivers in a consistent fashion A Board Support Package may include device drivers to access the hardware on the target platform These de vices typically include serial and parallel ports counter timer peripherals real time clocks disk interfaces and network controllers For more information on device drivers refer to the I O Manager chapter 21 3 1 Clock Tick Device Driver Most RTEMS applications will include a clock tick device driver which invokes the rtems_clock_tick directive at regular intervals The clock tick is necessary if the ap plication is to utilize timeslicing the clock manager the timer manager the rate monotonic manager or the timeout option on blocking directives The clock tick
269. led and one or more local tasks with a higher priority than the calling task are waiting on the deleted queue The calling task will NOT be preempted if the tasks that are waiting are remote tasks The calling task does not have to be the task that created the queue although the task and queue must reside on the same node When the queue is deleted any messages in the queue are returned to the free message buffer pool Any information stored in those messages is lost When a global message queue is deleted the message queue id must be transmitted to every node in the system for deletion from the local copy of the global object table Proxies used to represent remote tasks are reclaimed when the message queue is deleted Chapter 10 Message Manager 121 10 4 4 MESSAGE QUEUE SEND Put message at rear of a queue CALLING SEQUENCE rtems status code rtems message queue send rtems id id cons void buffer size t size X DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL message sent successfully RTEMS_INVALID_ID invalid queue id RTEMS_INVALID_SIZE invalid message size RTEMS_INVALID_ADDRESS buffer is NULL RTEMS_UNSATISFIED out of message buffers RTEMS_TOO_MANY queue s limit has been reached DESCRIPTION This directive sends the message buffer of size bytes in length to the queue specified by id If a task is waiting at the queue then the message is copied to the waiting task s buffer and the task is unblocked If n
270. led from the task_delete directive A value of NULL indicates that no extension is provided thread_switch is the address of the user supplied subroutine for the task context switch extension This subroutine is called from RTEMS dispatcher after the current task has been swapped out but before the new task has been swapped in A value of NULL indicates that no exten sion is provided As this routine is invoked after saving the current task s context and before restoring the heir task s context it is not necessary for this routine to save and restore any registers thread_begin is the address of the user supplied subroutine which is invoked im mediately before a task begins execution It is invoked in the context of the beginning task A value of NULL indicates that no extension is provided thread_exitted is the address of the user supplied subroutine which is invoked when a task exits This procedure is responsible for some action which will allow the system to continue execution i e delete or restart the task or to terminate with a fatal error If this field is set to NULL the default RTEMS TASK_EXITTED handler will be invoked fatal is the address of the user supplied subroutine for the FATAL exten sion This RTEMS extension of fatal error handling is called from the rtems_fatal_error_occurred directive If the user s fatal er ror handler returns or if this entry is NULL then the default RTEMS fatal error handler will be execut
271. leroeslereliQue ded elae RR AE RIP rPERS 88 create an extension set ssssuusssn 238 current task mode nes 51 current task priority 55 c v 3E TC EGER 50 D delay a task for an interval 54 delay a task until a wall time 55 delays isn sense be eu sag oneness aaa et 72 delete a barrier cece eee eee eee 222 delete a message queule 000 120 delete a partition 0 cece ee eee 146 delete a period 00 cece eee eee ees 210 delete a port cece eee eee een eee 167 delete a T6PFION iis cacans sinensis EPOR ER 155 delete a semaphore ee eee eee eee 108 delete a HIME cer erem tme ne edere 91 delete an extension set eee e ee eee 240 deleting 4task is dice ester RD eR REPE 46 device driver interface sleelsuuusus 173 Device Driver Table 171 260 device drlverss we ienen Ep f Wee pUwewes IT device names ocio uw nreee RR EGG rn NUES TE 172 disable interr pts 2 colere bI 66 disabling anterrupis 4 REPE RR RIP 62 dispatching occ rEIOPPERETORPU e ai 190 dual ported memory 00 00 163 dual ported memory definition 163 E enable interrupts 00 e cece eee eee 67 establish an ASR 00 2 cece eee eens 138 establish an ISR eile RR esas 65 event condition building 129 event flag definition
272. lication the value for this field cor responds to the setting of the macro CONFIGURE_MAXIMUM_POSIX_ MUTEXES If not defined by the application then the CONFIGURE_ MAXIMUM_POSIX_MUTEXES macro defaults to 0 maximum condition variables maximum keys maximum timers is the maximum number of condition variables that can be concur rently active in the system When using the rtems confdefs h mechanism for configuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE MAXIMUM POSIX CONDITION VARIABLES If not defined by the application then the CONFIGURE MAXIMUM POSIX CONDITION VARIABLES macro defaults to 0 is the maximum number of keys that can be concurrently active in the system When using the rtems confdefs h mechanism for con figuring an RT EMS application the value for this field corresponds to the setting of the macro CONFIGURE MAXIMUM POSIX KEYS If not de fined by the application then the CONFIGURE MAXIMUM POSIX KEYS macro defaults to 0 is the maximum number of POSIX timers that can be concurrently active in the system When using the rtems confdefs h mecha nism for configuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE MAXIMUM POSIX TIMERS If not defined by the application then the CONFIGURE MAXIMUM POSIX TIMERS macro defaults to 0 maximum queued signals is the maximum number of queued signals that can
273. lication the value for this field is calculated automat ically based on the number of entries in the Device Driver Table This calculation is based on the assumption that the Device Driver Table is named Device drivers and defined in C This table may be generated automatically for simple applications using only the device drivers that correspond to the following macros e CONFIGURE APPLICATION NEEDS CONSOLE DRIVER e CONFIGURE APPLICATION NEEDS CLOCK DRIVER e CONFIGURE APPLICATION NEEDS TIMER DRIVER e CONFIGURE APPLICATION NEEDS RTC DRIVER e CONFIGURE APPLICATION NEEDS STUB DRIVER Note that network device drivers are not configured in the Device Driver Table is the address of the Device Driver Table This table contains the entry points for each device driver If the number of device drivers field is zero then this entry should be NULL The format of this table will be discussed below When using the rtems confdefs h mechanism for configuring an RT EMS application the Device Driver Table is assumed to be named Device drivers and defined in C If the application is providing its own Device Driver Table then the macro CONFIGURE HAS OWN DEVICE DRIVER TABLE must be defined to indicate this and prevent rtems confdefs h from generating the table number of initial extensions User extension table is the number of initial user extensions T here should be the same number of entries as in the User extension table
274. lo World example as the baseline for an application and leaving out a clock tick source 246 RTEMS C User s Guide CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER is defined if the application wishes to include the Real Time Clock Driver By default this is not defined CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER is defined if the application wishes to include the Watchdog Driver By default this is not defined CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER is defined if the application wishes to include the Stub Device Driver This device driver simply provides entry points that return successful and is primarily a test fixture By default this is not defined CONFIGURE_BSP_PREREQUISITE_DRIVERS is defined if the BSP has device drivers it needs to include in the Device Driver Table This should be defined to the set of device driver entries that will be placed in the table at the FRONT of the Device Driver Table and initialized before any other drivers INCLUDING any application prerequisite drivers By default this is not defined CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS is defined if the application has device drivers it needs to include in the Device Driver Table This should be defined to the set of device driver entries that will be placed in the table at the FRONT of the Device Driver Table and initialized before any other drivers EXCEPT any BSP prerequisite drivers By default this is not defined CONFIGURE_APPLICATION_EXTRA_DRIVERS is define
275. m number of semaphores that can be concurrently ac tive in the system When using the rtems confdefs h mechanism for configuring an RTEMS application the value for this field corre sponds to the setting of the macro CONFIGURE MAXIMUM SEMAPHORES If not defined by the application then the CONFIGURE MAXIMUM SEMAPHORES macro defaults to 0 maximum message queues maximum partitions is the maximum number of message queues that can be concurrently active in the system When using the rtems confdefs h mechanism for configuring an RTEMS application the value for this field cor responds to the setting of the macro CONFIGURE MAXIMUM MESSAGE QUEUES If not defined by the application then the CONFIGURE MAXIMUM MESSAGE QUEUES macro defaults to 0 is the maximum number of partitions that can be concurrently ac tive in the system When using the rtems confdefs h mechanism for configuring an RTEMS application the value for this field corre sponds to the setting of the macro CONFIGURE MAXIMUM PARTITIONS If not defined by the application then the CONFIGURE MAXIMUM PARTITIONS macro defaults to 0 256 maximum_regions maximum_ports RTEMS C User s Guide is the maximum number of regions that can be concurrently active in the system When using the rtems confdefs h mechanism for con figuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE_MAXIMUM_REGIONS If not defined by the ap
276. maphore is not currently available With either RTEMS WAIT or RTEMS NO WAIT if the current semaphore count is positive then it is decremented by one and the semaphore is successfully acquired by returning immediately with a successful return code If the calling task chooses to return immediately and the current semaphore count is zero or negative then a status code is returned indicating that the semaphore is not available If the calling task chooses to wait for a semaphore and the current semaphore count is zero or negative then it is decremented by one and the calling task is placed on the semaphore s wait queue and blocked If the semaphore was created with the RTEMS PRIORITY attribute then the calling task is inserted into the queue according to its priority However if the semaphore was created with the RTEMS FIFO attribute then the calling task is placed at the rear of the wait queue If the binary semaphore was created with the RTEMS_INHERIT_ PRIORITY attribute then the priority of the task currently holding the binary semaphore is guaranteed to be greater than or equal to that of the blocking task If the binary semaphore was created with the RTEMS PRIORITY CEILING attribute a task successfully obtains the semaphore and the priority of that task is greater than the ceiling priority for this semaphore then the priority of the task obtaining the semaphore is elevated to that of the ceiling The timeout parameter specifies the maxi
277. mediately following the invocation of the rtems initialize executive directive NOTES This directive MUST be the last RT EMS directive invoked by an application and it DOES NOT RETURN to the caller This directive should not be invoked until the executive has successfully completed initial ization Chapter 5 Task Manager 31 5 Task Manager 5 1 Introduction The task manager provides a comprehensive set of directives to create delete and admin ister tasks The directives provided by the task manager are e rtems_task_create Create a task e rtems_task_ident Get ID of a task e rtems_task_self Obtain ID of caller e rtems_task_start Start a task e rtems_task_restart Restart a task e rtems_task_delete Delete a task e rtems_task_suspend Suspend a task e rtems_task_resume Resume a task e rtems_task_is_suspended Determine if a task is suspended e rtems_task_set_priority Set task priority e rtems task mode Change current task s mode e rtems task get note Get task notepad entry e rtems task set note Set task notepad entry e rtems task wake after Wake up after interval e rtems task wake when Wake up when specified e rtems iterate over all threads Iterate Over Tasks e rtems task variable add Associate per task variable e rtems task variable get Obtain value of a a per task variable e rtems task variable delete Remove per task variable 5 2 Background 5 2 1 Task Definition
278. ms processor and microprocessor A data structure which allows for efficient dynamic addition and removal of elements It differs from an array in that it is not limited to a predefined size 338 coalesce Configuration Table context context switch control block core CPU critical section CRT deadline device device driver directives dispatch dormant Device Driver Table dual ported embedded envelope RTEMS C User s Guide The process of merging adjacent holes into a single larger hole Some times this process is referred to as garbage collection A table which contains information used to tailor RTEMS for a par ticular application All of the processor registers and operating system data structures associated with a task Alternate term for task switch Taking control of the processor from one task and transferring it to another task A data structure used by the executive to define and control an object When used in this manual this term refers to the internal executive utility functions In the interest of application portability the core of the executive should not be used directly by applications An acronym for Central Processing Unit A section of code which must be executed indivisibly An acronym for Cathode Ray Tube Normally used in reference to the man machine interface A fixed time limit by which a task must have completed a set of actions Beyond this point
279. ms_status_code rtems extension delete rtems id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL extension set deleted successfully RTEMS INVALID ID invalid extension set id DESCRIPTION This directive deletes the extension set specified by id If the extension set is running it is automatically canceled The ESCB for the deleted extension set is reclaimed by RTEMS NOTES This directive will not cause the running task to be preempted A extension set can be deleted by a task other than the task which created the extension set NOTES This directive will not cause the running task to be preempted Chapter 23 Configuring a System 241 23 Configuring a System 23 1 Introduction RTEMS must be configured for an application This configuration information encompasses a variety of information including the length of each clock tick the maximum number of each RTEMS object that can be created the application initialization tasks and the device drivers in the application This information is placed in data structures that are given to RTEMS at system initialization time This chapter details the format of these data structures as well as a simpler mechanism to automate the generation of these structures 23 2 Automatic Generation of System Configuration RTEMS provides the rtems confdefs h C language header file that based on the setting of a variety of macros can automatically produce nearly all of the configuration tables r
280. mum interval the calling task is willing to be blocked waiting for the semaphore If it is set to RTEMS NO TIMEOUT then the calling task will wait forever If the semaphore is available or the RTEMS NO WAIT option component is set then timeout is ignored NOTES The following semaphore acquisition option constants are defined by RTEMS e RTEMS WAIT task will wait for semaphore default 110 RTEMS C User s Guide e RTEMS_NO_WAIT task should not wait Attempting to obtain a global semaphore which does not reside on the local node will generate a request to the remote node to access the semaphore If the semaphore is not available and RTEMS_NO_WAIT was not specified then the task must be blocked until the semaphore is released A proxy is allocated on the remote node to represent the task until the semaphore is released A clock tick is required to support the timeout functionality of this directive Chapter 9 Semaphore Manager 111 9 4 5 SEMAPHORE RELEASE Release a semaphore CALLING SEQUENCE rtems status code rtems semaphore release rtems id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL semaphore released successfully RTEMS INVALID ID invalid semaphore id RTEMS NOT OWNER OF RESOURCE calling task does not own semaphore DESCRIPTION This directive releases the semaphore specified by id The semaphore count is incremented by one If the count is zero or negative then the first task on this semapho
281. n designer to match the features of a particular manager with the complexity of communication and synchronization required The following managers were specifically designed for communication and synchronization e Semaphore e Message Queue e Event e Signal The semaphore manager supports mutual exclusion involving the synchronization of access to one or more shared user resources Binary semaphores may utilize the optional priority inheritance algorithm to avoid the problem of priority inversion The message manager supports both communication and synchronization while the event manager primarily pro vides a high performance synchronization mechanism The signal manager supports only asynchronous communication and is typically used for exception handling 2 4 Time The development of responsive real time applications requires an understanding of how RTEMS maintains and supports time related operations The basic unit of time in RTEMS is known as a tick The frequency of clock ticks is completely application dependent and determines the granularity and accuracy of all interval and calendar time operations 16 RTEMS C User s Guide By tracking time in units of ticks RTEMS is capable of supporting interval timing functions such as task delays timeouts timeslicing the delayed execution of timer service routines and the rate monotonic scheduling of tasks An interval is defined as a number of ticks relative to the current time For examp
282. n extension set 239 get index from object ID 06 14 get name from 105s pics in eer esd re RR Tees 293 get node from object ID 14 get number of pending messages 126 get object name as string lsssssssss 294 get per task variable 06 58 get segment from region 157 get size of segment 2 eee eee 160 get statistics of period 00 213 get status of period 06 212 get task mode Masse hne eR eeRPSS ERE TEES DE 51 get task notepad entry 02 52 get task preemption mode 51 get task Drlorky i ce crap i anhini kpi 50 global objects table 0000 272 global objects definition 272 H heterogeneous multiprocessing 276 I initialization tasks 23 Initialization Tasks Table 259 initialize a device driver suuuue irr initialize device drivers 000 cee eee 28 initialize RTEMS 0 c cece eee 29 initialize RTEMS before device drivers at RTEMS C User s Guide initialize RTEMS data structures 26 initiate the Timer Server 20000 94 install n ASR xL sebiscereraheree PER Reste 138 installan ISR oti errem dies det 65 internal addresses definition
283. n state RTEMS_ILLEGAL_ON_SELF illegal for calling task RTEMS_ILLEGAL_ON_REMOTE_OBJECT illegal for remote object RTEMS_CALLED_FROM_ISR invalid environment RTEMS_INVALID_PRIORITY invalid task priority RTEMS_INVALID_CLOCK invalid time buffer RTEMS_INVALID_NODE invalid node id RTEMS_NOT_CONFIGURED directive not configured RTEMS_NOT_OWNER_OF_RESOURCE not owner of resource RTEMS_NOT_IMPLEMENTED directive not implemented RTEMS_INTERNAL_ERROR RTEMS inconsistency detected RTEMS_NO_MEMORY could not get enough memory Chapter 30 Example Application 335 30 Example Application This file contains an example of a simple RTEMS application It instantiates the RTEMS Configuration Information using confdef h and contains two tasks a user initialization task and a simple task This example assumes that a board support package exists include lt rtems h gt rtems task user application rtems task argument argument rtems task init task x rtems task argument ignored rtems id tid rtems status code status rtems name name name rtems build name A P P 1 Status rtems task create name 1 RTEMS MINIMUM STACK SIZE RTEMS NO PREEMPT RTEMS FLOATING POINT amp tid 23 if status RTEMS STATUS SUCCESSFUL 1 printf rtems task create failed with status of d n status exit 1 status rtems_task_start tid user_application
284. n the same processor RTEMS supports 255 levels of priority ranging from 1 to 255 The data type rtems task priority is used to store task priorities Tasks of numerically smaller priority values are more important tasks than tasks of numer ically larger priority values For example a task at priority level 5 is of higher privilege than a task at priority level 10 There is no limit to the number of tasks assigned to the same priority Chapter 5 Task Manager 33 Each task has a priority associated with it at all times The initial value of this priority is assigned at task creation time The priority of a task may be changed at any subsequent time Priorities are used by the scheduler to determine which ready task will be allowed to execute In general the higher the logical priority of a task the more likely it is to receive processor execution time 5 2 5 Task Mode A task s execution mode is a combination of the following four components e preemption e ASR processing e timeslicing e interrupt level It is used to modify RTEMS scheduling process and to alter the execution environment of the task The data type rtems_task_mode is used to manage the task execution mode The preemption component allows a task to determine when control of the processor is relinquished If preemption is disabled RTEMS_NO_PREEMPT the task will retain control of the processor as long as it is in the executing state even if a higher priority t
285. nces of the same device For example a single routine could service interrupts from multiple serial ports and use the vector number to identify which port requires servicing To minimize the masking of lower or equal priority level interrupts the ISR should perform the minimum actions required to service the interrupt Other non essential actions should be handled by application tasks Once the user s ISR has completed it returns control to the RTEMS interrupt manager which will perform task dispatching and restore the registers saved before the ISR was invoked 62 RTEMS C User s Guide The RTEMS interrupt manager guarantees that proper task scheduling and dispatching are performed at the conclusion of an ISR A system call made by the ISR may have readied a task of higher priority than the interrupted task Therefore when the ISR completes the postponed dispatch processing must be performed No dispatch processing is performed as part of directives which have been invoked by an ISR Applications must adhere to the following rule if proper task scheduling and dispatching is to be performed The interrupt manager must be used for all ISRs which may be interrupted by the highest priority ISR which invokes an RTEMS directive Consider a processor which allows a numerically low interrupt level to interrupt a numer ically greater interrupt level In this example if an RTEMS directive is used in a level 4 ISR then all ISRs which execute at l
286. nd that preemption if enabled of a task by higher priority tasks will occur as required overriding the other factors presented in the description 18 2 1 Task Priority and Scheduling The most significant of these mechanisms is the ability for the user to assign a priority level to each individual task when it is created and to alter a task s priority at run time RTEMS 190 RTEMS C User s Guide provides 255 priority levels Level 255 is the lowest priority and level 1 is the highest When a task is added to the ready chain it is placed behind all other tasks of the same priority This rule provides a round robin within priority group scheduling characteristic This means that in a group of equal priority tasks tasks will execute in the order they become ready or FIFO order Even though there are ways to manipulate and adjust task priorities the most important rule to remember is The RTEMS scheduler will always select the highest priority task that is ready to run when allocating the processor to a task 18 2 2 Preemption Another way the user can alter the basic scheduling algorithm is by manipulating the preemption mode flag RTEMS_PREEMPT_MASK of individual tasks If preemption is disabled for a task RTEMS_NO_PREEMPT then the task will not relinquish control of the processor until it terminates blocks or re enables preemption Even tasks which become ready to run and possess higher priority levels will not be allowed to execu
287. nd that task was not the last task to utilize the coprocessor 18 3 Task State Transitions Tasks in an RTEMS system must always be in one of the five allowable task states These states are executing ready blocked dormant and non existent A task occupies the non existent state before a rtems_task_create has been issued on its behalf A task enters the non existent state from any other state in the system when it is deleted with the rtems_task_delete directive While a task occupies this state it does not have a TCB or a task ID assigned to it therefore no other tasks in the system may reference this task When a task is created via the rtems_task_create directive it enters the dormant state This state is not entered through any other means Although the task exists in the system it cannot actively compete for system resources It will remain in the dormant state until it is started via the rtems_task_start directive at which time it enters the ready state The task is now permitted to be scheduled for the processor and to compete for other system resources Non existent Creating Deleting Starting Deleting 4 Ready Yielding Readying Dispatching Blocking Blocked Blocking Deleting Deleting Non existent 192 RTEMS C User s Guide A task occupies the blocked state whenever it is unable to be scheduled to run A running task may block itself or be blocked by other tasks in the system The running task
288. ndition must be removed before the task becomes ready to run again A task occupies the ready state when it is able to be scheduled to run but currently does not have control of the processor Tasks of the same or higher priority will yield the processor by either becoming blocked completing their timeslice or being deleted All tasks with the same priority will execute in FIFO order A task enters the ready state due to any of the following conditions e A running task issues a rtems_task_resume directive for a task that is suspended and the task is not blocked waiting on any resource e A running task issues a rtems_message_queue_send rtems_message_queue_ broadcast or a rtems_message_queue_urgent directive which posts a message to the queue on which the blocked task is waiting e A running task issues an rtems_event_send directive which sends an event condi tion to a task which is blocked waiting on that event condition e A running task issues a rtems_semaphore_release directive which releases the semaphore on which the blocked task is waiting e A timeout interval expires for a task which was blocked by a call to the rtems_task_ wake_after directive Chapter 18 Scheduling Concepts 193 A timeout period expires for a task which blocked by a call to the rtems_task_ wake_when directive A running task issues a rtems_region_return_segment directive which releases a segment to the region on which the blocked task is waiting and a re
289. ne NER dI e RR CER ORG ee 278 25 Stack Bounds Checker 279 20 1 InitrOductiOns s sort chee en Seah bd eran eae nee 279 25 2 Background cuisses p enc ube we voseeedaae reas 279 25 2 1 Task 5tackiis ere ERE ER IRSE RR EREMO ERE TOR 279 25 2 2 BixecutlOnu ceca rto e rw ete eda ade bata ced 279 25 3 ODSeratlOls st2o5n4 elg eRESS RW Nay ENRICO REDE tele 280 25 3 1 Initializing the Stack Bounds Checker 280 25 3 2 Checking for Blown Task Stack 220005 280 25 3 8 Reporting Task Stack Usage 0 0 ccc cece eee 280 25 3 4 When a Task Overflows the Stack 00005 280 25 4 Boutines s 5 cete enc aded ehe bii Ae aae hae EDS 281 25 41 STACK CHECKER IS BLOWN Has Current Task Blown WS Stak sre erre NULL RS Lue PESE MD Ue EER 282 25 4 3 STACK CHECKER REPORT USAGE Report Task Stack li ETE 283 26 CPU Usage Statistics 285 20 1 IntroducliOmnz ioina onin Estee aa ARR EN VR ES dS 285 20 2 Background s one bero ae er ERR RE ETCUCEU ER TER 285 26 3 OperatiOls sissie deese PPeEN REV RE Ia ee REDI E Pis 285 26 3 1 Report CPU Usage Statistics lesse 285 26 3 2 Reset CPU Usage Statistics 0 0 0 0 286 20 4 JDirectiVeS ius erect br ch dcm ene tote ee net RP RACE erar 286 26 4 1 cpu usage report Report CPU Usage Statistics 287 26 4 2 cpu usage reset Reset CPU Usage Statistics 288 27 Object Services occesehe ere a9 don
290. ned by RTEMS e RTEMS WAIT task will wait for semaphore default 158 RTEMS C User s Guide e RTEMS_NO_WAIT task should not wait A clock tick is required to support the timeout functionality of this directive Chapter 14 Region Manager 159 14 4 6 REGION RETURN SEGMENT Return segment to a region CALLING SEQUENCE rtems status code rtems region return segment rtems id id void segment DIRECTIVE STATUS CODES RTEMS SUCCESSFUL segment returned successfully RTEMS INVALID ADDRESS segment is NULL RTEMS INVALID ID invalid region id RTEMS INVALID ADDRESS segment address not in region DESCRIPTION This directive returns the segment specified by segment to the region specified by id The returned segment is merged with its neighbors to form the largest possible segment The first task on the wait queue is examined to determine if its segment request can now be satisfied If so it is given a segment and unblocked This process is repeated until the first task s segment request cannot be satisfied NOTES This directive will cause the calling task to be preempted if one or more local tasks are waiting for a segment and the following conditions exist e a waiting task has a higher priority than the calling task e the size of the segment required by the waiting task is less than or equal to the size of the segment returned 160 RTEMS C User s Guide 14 4 7 REGION_GET_SEGMENT_SIZE Obtain s
291. ng any blocking RTEMS directives before rtems_initialize_start_ multitasking is unpredictable but guaranteed to be bad After the directive rtems_initialize_data_structures is invoked it is permissible to allocate RTEMS ob jects and perform non blocking operations But the user should be distinctly aware that multitasking is not available yet and they are NOT executing in a task context Many of RTEMS actions during initialization are based upon the contents of the Configu ration Table For more information regarding the format and contents of this table please refer to the chapter Chapter 23 Configuring a System page 241 The final step in the initialization sequence is the initiation of multitasking When the scheduler and dispatcher are enabled the highest priority ready task will be dispatched to run Control will not be returned to the Board Support Package after multitasking is enabled until the rtems_shutdown_executive directive is called This directive is called as a side effect of POSIX calls including exit 4 3 2 Shutting Down RTEMS The rtems_shutdown_executive directive is invoked by the application to end multitasking and return control to the board support package The board support package resumes execution at the code immediately following the invocation of the rtems_initialize_ start_multitasking directive 4 4 Directives This section details the Initialization Manager s directives A subsection is dedicated to each
292. nimum stack size RECOMMENDED for use on this processor This value is selected by the RTEMS developers conservatively to minimize the risk of blown stacks for most user applications Using this constant when specifying the task stack size indicates that the stack size will be at least RTEMS_MINIMUM_STACK_SIZE bytes in size If the user configured minimum stack size is larger than the recommended minimum then it will be used Chapter 5 Task Manager 41 e RTEMS_CONFIGURED_MINIMUM_STACK_SIZE indicates that this task is to be created with a stack size of the minimum stack size that was configured by the application If not explicitly configured by the application the default configured minimum stack size is the processor dependent value RTEMS_MINIMUM_STACK_SIZE Since this uses the configured minimum stack size value you may get a stack size that is smaller or larger than the recommended minimum This can be used to provide large stacks for all tasks on complex applications or small stacks on applications that are trying to conserve memory Application developers should consider the stack usage of the device drivers when calculating the stack size required for tasks which utilize the driver The following task attribute constants are defined by RTEMS e RTEMS_NO_FLOATING_POINT does not use coprocessor default e RTEMS_FLOATING_POINT uses numeric coprocessor e RTEMS_LOCAL local task default e RTEMS_GLOBAL global task The following
293. nsions Manager 231 22 User Extensions Manager 22 1 Introduction The RTEMS User Extensions Manager allows the application developer to augment the executive by allowing them to supply extension routines which are invoked at critical system events The directives provided by the user extensions manager are e rtems_extension_create Create an extension set e rtems_extension_ident Get ID of an extension set e rtems_extension_delete Delete an extension set 22 2 Background User extension routines are invoked when the following system events occur e Task creation e Task initiation e Task reinitiation e Task deletion e Task context switch e Post task context switch e Task begin e Task exits e Fatal error detection These extensions are invoked as a function with arguments that are appropriate to the system event 22 2 1 Extension Sets An extension set is defined as a set of routines which are invoked at each of the critical system events at which user extension routines are invoked Together a set of these rou tines typically perform a specific functionality such as performance monitoring or debugger support RTEMS is informed of the entry points which constitute an extension set via the following structure typedef struct rtems_task_create_extension thread_create rtems_task_start_extension thread_start rtems_task_restart_extension thread_restart rtems_task_delete_extension thread_delete rtems_task_switch_
294. nt Manager 131 e Specifying a timeout limits the period the task will wait before returning with an error status code 11 3 3 Determining the Pending Event Set A task can determine the pending event set by calling the rtems_event_receive directive with a value of RTEMS_PENDING_EVENTS for the input event condition The pending events are returned to the calling task but the event set is left unaltered 11 3 4 Receiving all Pending Events A task can receive all of the currently pending events by calling the rtems_event_receive directive with a value of RTEMS_ALL_EVENTS for the input event condition and RTEMS_NO_ WAIT RTEMS_EVENT_ANY for the option set The pending events are returned to the calling task and the event set is cleared If no events are pending then the RTEMS_UNSATISFIED status code will be returned 11 4 Directives This section details the event manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes 132 RTEMS C User s Guide 11 4 1 EVENT_SEND Send event set to a task CALLING SEQUENCE rtems_status_code rtems_event_send rtems_id id rtems_event_set event_in 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL event set sent successfully RTEMS INVALID ID invalid task id DESCRIPTION This directive sends an event set event in to the task specified by id If a blocked task s input event c
295. nvalid node id DESCRIPTION This directive obtains the task id associated with the task name specified in name A task may obtain its own id by specifying RTEMS_SELF or its own task name in name If the task name is not unique then the task id returned will match one of the tasks with that name However this task id is not guaranteed to correspond to the desired task The task id returned in id is used in other task related directives to access the task NOTES This directive will not cause the running task to be preempted If node is RTEMS_SEARCH_ALL_NODES all nodes are searched with the local node being searched first All other nodes are searched with the lowest numbered node searched first If node is a valid node number which does not represent the local node then only the tasks exported by the designated node are searched This directive does not generate activity on remote nodes It accesses only the local copy of the global object table Chapter 5 Task Manager 43 5 4 3 TASK_SELF Obtain ID of caller CALLING SEQUENCE rtems_id rtems_task_self void DIRECTIVE STATUS CODES Returns the object Id of the calling task DESCRIPTION This directive returns the Id of the calling task NOTES If called from an interrupt service routine this directive will return the Id of the interrupted task 44 RTEMS C User s Guide 5 4 4 TASK_START Start a task CALLING SEQUENCE rtems status code rtems task start
296. o create and start each of the user initialization tasks Alternate term for user supplied This term is used to designate any software routines which must be written by the application designer Alternate term for user provided This term is used to designate any software routines which must be written by the application designer Memory pointers used by the processor to fetch the address of rou tines which will handle various exceptions and interrupts The list of tasks blocked pending the release of a particular resource Message queues regions and semaphores have a wait queue associ ated with them When a task voluntarily releases control of the processor Command and Variable Index Command and Variable Index _Internal_errors_What_happened 185 C confd fSvh sslaemseesentus ipse euer 241 CONFIGURE APPLICATION DOES NOT NEED CLOCK DREYER corse leh s vied epa REI d GR PERDE 245 CONFIGURE APPLICATION EXTRA DRIVERS 246 CONFIGURE APPLICATION NEEDS CLOCK DRIVER LitsoRgurpesst etenivbiepepPusebr ede deed ee 245 CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER ielsagalqv0stRetbhneRPeePPusnr dcrumpeg 245 CONFIGURE APPLICATION NEEDS RTC DRIVER 245 CONFIGURE APPLICATION NEEDS STUB DRIVER E 246 CONFIGURE APPLICATION NEEDS TIMER DRIVER VuUldrbsrscueeu E iem pi tae serene dud 245 CONFIGURE APPLICATION NEEDS WATCHDOG DRIVER Picus revu ee ea ins acts en ed iiec 246 CONFIGURE_APPLICATION_PRERE
297. o tasks are waiting at the queue then the message is copied to a message buffer which is obtained from this message queue s message buffer pool The message buffer is then placed at the rear of the queue NOTES The calling task will be preempted if it has preemption enabled and a higher priority task is unblocked as the result of this directive Sending a message to a global message queue which does not reside on the local node will generate a request to the remote node to post the message on the specified message queue If the task to be unblocked resides on a different node from the message queue then the message is forwarded to the appropriate node the waiting task is unblocked and the proxy used to represent the task is reclaimed 122 RTEMS C User s Guide 10 4 5 MESSAGE QUEUE URGENT Put message at front of a queue CALLING SEQUENCE rtems status code rtems message queue urgent rtems id id const void buffer size t size X DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL message sent successfully RTEMS_INVALID_ID invalid queue id RTEMS_INVALID_SIZE invalid message size RTEMS_INVALID_ADDRESS buffer is NULL RTEMS_UNSATISFIED out of message buffers RTEMS_TOO_MANY queue s limit has been reached DESCRIPTION This directive sends the message buffer of size bytes in length to the queue specified by id If a task is waiting on the queue then the message is copied to the task s buffer and the task is
298. ocal message queue default e RTEMS GLOBAL global message queue Message queues should not be made global unless remote tasks must interact with the created message queue This is to avoid the system overhead incurred by the creation of a global message queue When a global message queue is created the message queue s name and id must be transmitted to every node in the system for insertion in the local copy of the global object table 118 RTEMS C User s Guide For GLOBAL message queues the maximum message size is effectively limited to the longest message which the MPCI is capable of transmitting The total number of global objects including message queues is limited by the maxi mum_global_objects field in the configuration table Chapter 10 Message Manager 119 10 4 2 MESSAGE QUEUE IDENT Get ID of a queue CALLING SEQUENCE rtems status code rtems message queue ident rtems name name uint32 t node rtems id id Jz DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL queue identified successfully RTEMS_INVALID_ADDRESS id is NULL RTEMS_INVALID_NAME queue name not found RTEMS_INVALID_NODE invalid node id DESCRIPTION This directive obtains the queue id associated with the queue name specified in name If the queue name is not unique then the queue id will match one of the queues with that name However this queue id is not guaranteed to correspond to the desired queue The queue id is used with other message rel
299. ocess and manage these events and tasks are growing more complicated The design process is complicated further by spreading this activity over a set of processors instead of a single processor The challenges associated with designing and building real 6 RTEMS C User s Guide time application systems become very complex when multiple processors are involved New requirements such as interprocessor communication channels and global resources that must be shared between competing processors are introduced The ramifications of multiple processors complicate each and every characteristic of a real time system 1 3 Real time Executive Fortunately real time operating systems or real time executives serve as a cornerstone on which to build the application system A real time multitasking executive allows an appli cation to be cast into a set of logical autonomous processes or tasks which become quite manageable Each task is internally synchronous but different tasks execute independently resulting in an asynchronous processing stream Tasks can be dynamically paused for many reasons resulting in a different task being allowed to execute for a period of time The exec utive also provides an interface to other system components such as interrupt handlers and device drivers System components may request the executive to allocate and coordinate resources and to wait for and trigger synchronizing conditions The executive system calls effectivel
300. od so delete period and SELF void rtems_rate_monotonic_delete period 1 void rtems rate monotonic delete period 2 void task delete SELF 206 RTEMS C User s Guide The above task creates two rate monotonic periods as part of its initialization The first time the loop is executed the rtems_rate_monotonic_period directive will initiate the period_1 period for 100 ticks and return immediately Subsequent invocations of the rtems_rate_ monotonic period directive for period_1 will result in the task blocking for the remainder of the 100 tick period The period 2 period is used to control the execution time of the two sets of actions within each 100 tick period established by period_1 The rtems rate monotonic cancel period 2 call is performed to ensure that the period 2 period does not expire while the task is blocked on the period 1 period If this cancel operation were not performed every time the rtems rate monotonic period period 2 40 call is ex ecuted except for the initial one a directive status of RTEMS TIMEOUT is returned It is important to note that every time this call is made the period 2 period will be initiated immediately and the task will not block If for any reason the task misses any deadline the rtems rate monotonic period direc tive will return the RTEMS TIMEOUT directive status If the above task misses its deadline it will delete the rate monotonic periods and itself 19 4 Di
301. od will be returned The following table details the relationship between the period s status and the directive status code returned by the rtems_rate_monotonic_period directive e RTEMS_SUCCESSFUL period is running e RTEMS TIMEOUT period has expired e RTEMS NOT DEFINED period has never been initiated 202 RTEMS C User s Guide Obtaining the status of a rate monotonic period does not alter the state or length of that period 19 3 4 Canceling a Period The rtems_rate_monotonic_cancel directive is used to stop the period maintained by the specified rate monotonic period The period is stopped and the rate monotonic period can be reinitiated using the rtems_rate_monotonic_period directive 19 3 5 Deleting a Rate Monotonic Period The rtems_rate_monotonic_delete directive is used to delete a rate monotonic period If the period is running and has not expired the period is automatically canceled The rate monotonic period s control block is returned to the PCB free list when it is deleted A rate monotonic period can be deleted by a task other than the task which created the period 19 3 6 Examples The following sections illustrate common uses of rate monotonic periods to construct peri odic tasks 19 3 7 Simple Periodic Task This example consists of a single periodic task which after initialization executes every 100 clock ticks Chapter 19 Rate Monotonic Manager 203 rtems_task Periodic_task rtems_task_argument arg
302. ode rtems_clock_get_seconds_since_epoch rtems interval the interval 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL current time obtained successfully RTEMS NOT DEFINED system date and time is not set RTEMS INVALID ADDRESS the interval is NULL DESCRIPTION This directive returns the number of seconds since the RTEMS epoch and the current system date and time If the date and time has not been set with a previous call to rtems clock set then the RTEMS NOT DEFINED status code is returned NOTES This directive is callable from an ISR This directive will not cause the running task to be preempted Re initializing RTEMS causes the system date and time to be reset to an uninitialized state Another call to rtems_clock_set is required to re initialize the system date and time to application specific specifications Chapter 7 Clock Manager 79 7 46 CLOCK_GET_TICKS_PER_SECOND Get ticks per second CALLING SEQUENCE rtems_interval rtems_clock_get_ticks_per_seconds void DIRECTIVE STATUS CODES NONE DESCRIPTION This directive returns the number of clock ticks per second This is strictly based upon the microseconds per clock tick that the application has configured NOTES This directive is callable from an ISR This directive will not cause the running task to be preempted Re initializing RTEMS causes the system date and time to be reset to an uninitialized state Another call to rtems_clock_set is re
303. of buffers 28 3 3 Iterating a Chain Iterating a chain is a common function The example shows how to iterate the buffer pool chain created in the last section to find buffers starting with a specific string If the buffer is located it is extracted from the chain and placed on another chain void foobar const char match rtems_chain_control chain rtems_chain_control out rtems_chain_node node foox bar rtems chain initialize empty out node chain gt first while rtems_chain_is_tail chain node t bar foo node if strcmp match bar gt data 0 312 RTEMS C User s Guide rtems_chain_node next_node node gt next rtems_chain_extract node rtems_chain_append out node node next_node 28 4 Directives The section details the Chains directives Chapter 28 Chains 313 28 4 1 Initialize Chain With Nodes CALLING SEQUENCE void rtems_chain_initialize rtems_chain_control the_chain void starting address size t number nodes size t node size RETURNS Returns nothing DESCRIPTION This function take in a pointer to a chain control and initializes it to contain a set of chain nodes The chain will contain number nodes chain nodes from the memory pointed to by start address Each node is assumed to be node size bytes NOTES This call will discard any nodes on the chain This call does NOT inititialize any user data on each node 314 RTEMS C User s Guide
304. of this directive RTEMS initializes the task s stack based upon the task s initial execution mode and start address The starting argument is passed to the task in accordance with the target processor s calling convention The rtems_task_restart directive restarts a task at its initial starting address with its original priority and execution mode but with a possibly different argument The new argument may be used to distinguish between the original invocation of the task and subse quent invocations The task s stack and control block are modified to reflect their original creation values Although references to resources that have been requested are cleared resources allocated by the task are NOT automatically returned to RTEMS A task cannot be restarted unless it has previously been started i e dormant tasks cannot be restarted All restarted tasks are placed in the ready state 5 3 4 Suspending and Resuming Tasks The rtems_task_suspend directive is used to place either the caller or another task into a suspended state The task remains suspended until a rtems_task_resume directive is issued This implies that a task may be suspended as well as blocked waiting either to acquire a resource or for the expiration of a timer The rtems_task_resume directive is used to remove another task from the suspended state If the task is not also blocked resuming it will place it in the ready state allowing it to once again compete for the pro
305. of this manager s directives and describes the calling sequence related constants usage and status codes 26 RTEMS C User s Guide 4 4 1 INITIALIZE DATA STRUCTURES Initialize RTEMS Data Structures CALLING SEQUENCE void rtems initialize data structures rtems configuration table configuration table 25 DIRECTIVE STATUS CODES NONE DESCRIPTION This directive is called when the Board Support Package has completed its basic initializa tion and allows RTEMS to initialize the application environment based upon the informa tion in the Configuration Table User Initialization Tasks Table Device Driver Table User Extension Table Multiprocessor Configuration Table and the Multiprocessor Communica tions Interface MPCI Table This directive returns to the caller after completing the basic RTEMS initialization NOTES The Initialization Manager directives must be used in the proper sequence and invokved only once in the life of an application This directive must be invoked with interrupts disabled Interrupts should be disabled as early as possible in the initialization sequence and remain disabled until the first context switch Chapter 4 Initialization Manager 27 4 4 2 INITIALIZE BEFORE DRIVERS Perform Initialization Before Device Drivers CALLING SEQUENCE void rtems initialize before drivers void DIRECTIVE STATUS CODES NONE DESCRIPTION This directive is called by the Board Support Package a
306. okes the directive fatal error occurred with the RTEMS_TASK_ EXITTED directive status 22 2 3 8 FATAL Error Extension The FATAL error extension is associated with the fatal error occurred directive If this extension is defined in any static or dynamic extension set and the fatal error occurred directive has been invoked then this extension will be called This extension should have a prototype similar to the following rtems extension user fatal error Internal errors Source the source bool is internal uint32 t the error where the error is the error code passed to the fatal error occurred directive This extension is invoked from the fatal error occurred directive If defined the user s FATAL error extension is invoked before RTEMS default fatal error routine is invoked and the processor is stopped For example this extension could be used 236 RTEMS C User s Guide to pass control to a debugger when a fatal error occurs This extension should not call any RTEMS directives 22 2 4 Order of Invocation When one of the critical system events occur the user extensions are invoked in either forward or reverse order Forward order indicates that the static extension set is invoked followed by the dynamic extension sets in the order in which they were created Reverse order means that the dynamic extension sets are invoked in the opposite of the order in which they were created followed by the static extension set By
307. on Chapter 24 Multiprocessing Manager 273 1 The application issues a directive accessing a remote global object 2 RTEMS determines the node on which the object resides 3 RTEMS calls the user provided MPCI routine GET_PACKET to obtain a packet in which to build a RQ message 4 After building a message packet RTEMS calls the user provided MPCI routine SEND_PACKET to transmit the packet to the node on which the object resides referred to as the destination node 5 The calling task is blocked until the RR message arrives and control of the processor is transferred to another task 6 The MPCI layer on the destination node senses the arrival of a packet commonly in an ISR and calls the rtems nultiprocessing announce directive This directive readies the Multiprocessing Server 7 The Multiprocessing Server calls the user provided MPCI routine RE CEIVE PACKET performs the requested operation builds an RR message and returns it to the originating node 8 The MPCI layer on the originating node senses the arrival of a packet typically via an interrupt and calls the RTEMS rtems multiprocessing announce directive This directive readies the Multiprocessing Server 9 The Multiprocessing Server calls the user provided MPCI routine RE CEIVE_PACKET readies the original requesting task and blocks until another packet arrives Control is transferred to the original task which then completes processing of the directive
308. on e RTEMS_NO_TIMESLICE is masked by RTEMS_TIMESLICE_MASK and disables timeslicing e RTEMS_TIMESLICE is masked by RTEMS_TIMESLICE_MASK and enables timeslicing e RTEMS_ASR is masked by RTEMS_ASR_MASK and enables ASR processing e RTEMS_NO_ASR is masked by RTEMS_ASR_MASK and disables ASR processing e RTEMS_INTERRUPT_LEVEL 0 is masked by RTEMS_INTERRUPT_MASK and enables all interrupts e RTEMS_INTERRUPT_LEVEL n is masked by RTEMS_INTERRUPT_MASK and sets inter rupts level n Mode values are specifically designed to be mutually exclusive therefore bitwise OR and ad dition operations are equivalent as long as each mode appears exactly once in the component list A mode component listed as a default is not required to appear in the mode component list although it is a good programming practice to specify default components If all de faults are desired the mode RTEMS DEFAULT MODES and the mask RTEMS ALL MODE MASKS should be used The following example demonstrates the mode and mask parameters used with the rtems task mode directive to place a task at interrupt level 3 and make it non preemptible The mode should be set to RTEMS_INTERRUPT_LEVEL 3 RTEMS NO PREEMPT to indicate the desired preemption mode and interrupt level while the mask parameter should be set to RTEMS_INTERRUPT_MASK RTEMS_NO_PREEMPT_MASK to indicate that the calling task s interrupt level and preemption mode are being altered 5 3 Operations 5 3 1 Creating T
309. ondition is satisfied by this directive then it will be made ready If its input event condition is not satisfied then the events satisfied are updated and the events not satisfied are left pending If the task specified by id is not blocked waiting for events then the events sent are left pending NOTES Specifying RTEMS SELF for id results in the event set being sent to the calling task Identical events sent to a task are not queued In other words the second and subsequent posting of an event to a task before it can perform an rtems event receive has no effect The calling task will be preempted if it has preemption enabled and a higher priority task is unblocked as the result of this directive Sending an event set to a global task which does not reside on the local node will generate a request telling the remote node to send the event set to the appropriate task Chapter 11 Event Manager 133 11 4 2 EVENT_RECEIVE Receive event condition CALLING SEQUENCE rtems_status_code rtems_event_receive rtems event set event in rtems option option set rtems interval ticks rtems event set event out DIRECTIVE STATUS CODES RTEMS SUCCESSFUL event received successfully RTEMS_UNSATISFIED input event not satisfied RTEMS NO WAIT RTEMS INVALID ADDRESS event out is NULL RTEMS TIMEOUT timed out waiting for event DESCRIPTION This directive attempts to receive the event condition specified in event_in If
310. ore id will match one of the semaphores with that name However this semaphore id is not guaranteed to correspond to the desired semaphore The semaphore id is used by other semaphore related directives to access the semaphore NOTES This directive will not cause the running task to be preempted If node is RTEMS_SEARCH_ALL_NODES all nodes are searched with the local node being searched first All other nodes are searched with the lowest numbered node searched first If node is a valid node number which does not represent the local node then only the semaphores exported by the designated node are searched This directive does not generate activity on remote nodes It accesses only the local copy of the global object table 108 RTEMS C User s Guide 9 4 3 SEMAPHORE DELETE Delete a semaphore CALLING SEQUENCE rtems status code rtems semaphore delete rtems id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL semaphore deleted successfully RTEMS INVALID ID invalid semaphore id RTEMS ILLEGAL ON REMOTE OBJECT cannot delete remote semaphore RTEMS RESOURCE IN USE binary semaphore is in use DESCRIPTION This directive deletes the semaphore specified by id All tasks blocked waiting to acquire the semaphore will be readied and returned a status code which indicates that the semaphore was deleted The SMCB for this semaphore is reclaimed by RTEMS NOTES The calling task will be preempted if it is enabled
311. ority among all tasks in the ready state There are two common methods of accomplishing the mechanics of this algorithm Both ways involve a list or chain of tasks in the ready state One method is to randomly place tasks in the ready chain forcing the scheduler to scan the entire chain to determine which task receives the processor The other method is to schedule the task by placing it in the proper place on the ready chain based on the designated scheduling criteria at the time it enters the ready state Thus when the processor is free the first task on the ready chain is allocated the processor RTEMS schedules tasks using the second method to guarantee faster response times to external events 18 2 Scheduling Mechanisms RTEMS provides four mechanisms which allow the user to impact the task scheduling process e user selectable task priority level e task preemption control e task timeslicing control e manual round robin selection Each of these methods provides a powerful capability to customize sets of tasks to satisfy the unique and particular requirements encountered in custom real time applications Although each mechanism operates independently there is a precedence relationship which governs the effects of scheduling modifications The evaluation order for scheduling characteristics is always priority preemption mode and timeslicing When reading the descriptions of timeslicing and manual round robin it is important to keep in mi
312. orting an extension 22 3 2 Obtaining Extension Set IDs When an extension set is created RTEMS generates a unique extension set ID and assigns it to the created extension set until it is deleted The extension ID may be obtained by either of two methods First as the result of an invocation of the rtems extension create Chapter 22 User Extensions Manager 237 directive the extension set ID is stored in a user provided location Second the extension set ID may be obtained later using the rtems_extension_ident directive The extension set ID is used by other directives to manipulate this extension set 22 3 3 Deleting an Extension Set The rtems_extension_delete directive is used to delete an extension set The extension set s control block is returned to the ESCB free list when it is deleted An extension set can be deleted by a task other than the task which created the extension set Any subsequent references to the extension s name and ID are invalid 22 4 Directives This section details the user extension manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes 238 RTEMS C User s Guide 22 4 1 EXTENSION_CREATE Create a extension set CALLING SEQUENCE rtems_status_code rtems_extension_create C rtems_name name rtems extensions table table rtems id id J DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL
313. os sasda miadi kena enana enia 154 14 4 Directives eccriene I eC PIPeSG eI REPRE AG TOUS een 152 14 4 1 REGION CREATE Create a region 153 14 4 4 REGION IDENT Get ID of a region 154 14 4 5 REGION DELETE Delete a region 155 14 4 4 REGION EXTEND Add memory to a region 156 14 4 5 REGION GET SEGMENT Get segment from a region CESET EE cde ER UOPPC E E EE LOT 14 4 5 REGION RETURN SEGMENT Return segment to a region E e E KE AG a d aes ep IHE IHR RA RI UE De ene fa 159 14 4 7 REGION GET SEGMEN T SIZE Obtain size of a segment Spas dain ee pueveeskurbp dee ketkecsseUxrERER eR sho nkensenerss LOO 14 4 8 REGION RESIZE SEGMENT Change size of a segment E 161 15 Dual Ported Memory Manager 163 15 4 IntroductiOnz i e eerte rn tear t ea eret e kae aca 163 15 2 Background isses ppc rre RERBEDER RI A Ea RR 163 15 3 Operations 2s mee PERPE EC EXE EIER RPZE RICE 163 15 3 1 Creating a Por iR RRDHL RI etr eh b em bre 163 15 3 2 Obtaining Port IDS 44 icr t RR ERR ER RES 163 15 8 8 Converting an Address 0 000 enrere neren 164 15 3 4 Deleting a DPMA Port 0 00 eee eee eee 164 154b Directives deri mee ee eaawegedeies os nue EERERER quad dees 164 15 4 1 PORT_CREATE Create a port 00000005 165 15 4 2 PORT_IDENT Get ID of a port 166 15 4 3 PORT DELETE Delete a port ssss
314. ough the critical task set can be guaranteed to execute even under transient overload the non critical task set is not guaranteed to execute In conclusion the application designer must be fully cognizant of the system and its run time behavior when performing schedulability analysis for a system using RMS Every hardware and software factor which impacts the execution time of each task must be accounted for in the schedulability analysis 19 2 5 7 Further Reading For more information on Rate Monotonic Scheduling and its schedulability analysis the reader is referred to the following Chapter 19 Rate Monotonic Manager 201 C L Liu and J W Layland Scheduling Algorithms for Multiprogramming in a Hard Real Time Environment Journal of the Association of Computing Machinery January 1973 pp 46 61 John Lehoczky Lui Sha and Ye Ding The Rate Monotonic Scheduling Algo rithm Exact Characterization and Average Case Behavior IEEE Real Time Sys tems Symposium 1989 pp 166 171 Lui Sha and John Goodenough Real Time Scheduling Theory and Ada TEEE Computer April 1990 pp 53 62 Alan Burns Scheduling hard real time systems a review Software Engineering Journal May 1991 pp 116 128 19 3 Operations 19 3 1 Creating a Rate Monotonic Period The rtems_rate_monotonic_create directive creates a rate monotonic period which is to be used by the calling task to delineate a period RTEMS allocates a Period Control Block P
315. ously with a task Upon reception of a signal the ASR of the receiving task will be invoked A thirty two bit entity which is used to represent a task s collection of pending signals and the signals sent to a task An acronym for Semaphore Control Block A real time system in which a missed deadline does not compromise the integrity of the system A task which executes at irregular intervals and must comply with a hard deadline A minimum period of time between successive itera tions of the task can be guaranteed A data structure that is managed using a Last In First Out LIFO discipline Each task has a stack associated with it which is used to store return information and local variables Also known as error code or return value A term used to describe a task that is not competing for the CPU because it has had a rtems_task_suspend directive Related in order or timing to other occurrences in the system In this document this is used as an alternate term for directive The system on which the application will ultimately execute A logically complete thread of execution The CPU is allocated among the ready tasks A data structure associated with each task used by RTEMS to man age that task Chapter 31 Glossary task switch TCB tick tightly coupled timeout timer Timer Control Block timeslicing timeslice TMCB transient overload user extensions User Extension Table 345 Alternate
316. out the need to travse the chain Chains have a small memory footprint and can be used in interrupt service routines and are thread safe in a multi threaded environment The directives list which operations disable interrupts Chains are very useful in Board Support packages and applications 310 RTEMS C User s Guide 28 2 1 Nodes A chain is made up from nodes that orginate from a chain control object A node is of type rtems_chain_node The node is designed to be part of a user data structure and a cast is used to move from the node address to the user data structure address For example typedef struct foo 1 rtems chain node node int bar foo creates a type foo that can be placed on a chain To get the foo structure from the list you perform the following foo get foo rtems chain control control 1 return foo rtems chain get control The node is placed at the start of the user s structure to allow the node address on the chain to be easly cast to the user s structure address 28 2 2 Controls A chain is anchored with a control object Chain control provide the user with access to the nodes on the chain The control is head of the node Control leo r T gt permanent null 2 NODE last 4 gt The implementation does not require special checks for manipulating the first and last nodes on the chain To accomplish this the rtems_chain_control st
317. pecifies that the task will execute at interrupt level n e RTEMS_PREEMPT enable preemption default e RTEMS_NO_PREEMPT disable preemption e RTEMS_NO_TIMESLICE disable timeslicing default e RTEMS_TIMESLICE enable timeslicing 34 RTEMS C User s Guide e RTEMS_ASR enable ASR processing default e RTEMS_NO_ASR disable ASR processing e RTEMS_INTERRUPT_LEVEL 0 enable all interrupts default e RTEMS INTERRUPT LEVEL n execute at interrupt level n The set of default modes may be selected by specifying the RTEMS DEFAULT MODES constant 5 2 6 Accessing Task Arguments All RTEMS tasks are invoked with a single argument which is specified when they are started or restarted The argument is commonly used to communicate startup information to the task The simplest manner in which to define a task which accesses it argument is rtems task user task rtems task argument argument 25 Application tasks requiring more information may view this single argument as an index into an array of parameter blocks 5 2 7 Floating Point Considerations Creating a task with the RTEMS FLOATING POINT attribute flag results in additional memory being allocated for the T CB to store the state of the numeric coprocessor during task switches This additional memory is NOT allocated for RTEMS NO FLOATING POINT tasks Saving and restoring the context of a RTEMS FLOATING POINT task takes longer than that of a RTEMS NO FLOATING PO
318. period is reclaimed by RTEMS NOTES This directive will not cause the running task to be preempted A rate monotonic period can be deleted by a task other than the task which created the period Chapter 19 Rate Monotonic Manager 211 19 4 5 RATE MONOTONIC PERIOD Conclude current Start next period CALLING SEQUENCE rtems_status_code rtems_rate_monotonic_period rtems_id id rtems_interval length DIRECTIVE STATUS CODES RTEMS SUCCESSFUL period initiated successfully RTEMS INVALID ID invalid rate monotonic period id RTEMS NOT OWNER OF RESOURCE period not created by calling task RTEMS NOT DEFINED period has never been initiated only possible when period is set to PERIOD STATUS RTEMS TIMEOUT period has expired DESCRIPTION This directive initiates the rate monotonic period id with a length of period ticks If id is running then the calling task will block for the remainder of the period before reinitiating the period with the specified period If id was not running either expired or never initiated the period is immediately initiated and the directive returns immediately If invoked with a period of RTEMS PERIOD STATUS ticks the current state of id will be returned The directive status indicates the current state of the period This does not alter the state or period of the period NOTES This directive will not cause the running task to be preempted 212 RTEMS C User s Guide
319. plication then the CONFIGURE_MAXIMUM_REGIONS macro defaults to 0 is the maximum number of ports into dual port memory areas that can be concurrently active in the system When using the rtems confdefs h mechanism for configuring an RTEMS applica tion the value for this field corresponds to the setting of the macro CONFIGURE_MAXIMUM_PORTS If not defined by the application then the CONFIGURE_MAXIMUM_PORTS macro defaults to 0 number_of_initialization_tasks is the number of initialization tasks configured At least one RTEMS initialization task or POSIX initializatin must be configured in or der for the user s application to begin executing When using the rtems confdefs h mechanism for configuring an RTEMS applica tion the user must define the CONFIGURE_RTEMS_INIT_TASKS_TABLE to indicate that there is one or more RTEMS initialization task If the application only has one RTEMS initialization task then the automatically generated Initialization Task Table will be sufficient The following macros correspond to the single initialization task e CONFIGURE_INIT_TASK_NAME is the name of the task If this macro is not defined by the application then this defaults to the task name of UI1 for User Initialization Task 1 e CONFIGURE_INIT_TASK_STACK_SIZE is the stack size of the single initialization task If this macro is not defined by the application then this defaults to configured minimum stack size e CONFIGURE_INIT_TASK_PRIO
320. pplication use ASCII characters to build object names For example if an application requires one hundred tasks it would be difficult to assign meaningful ASCII names to each task A more convenient approach would be to name them the binary values one through one hundred respectively RTEMS provides a helper routine rtems object get name which can be used to obtain the name of any RTEMS object using just its ID This routine attempts to convert the name into a printable string The following example illustrates the use of this method to print an object name include lt rtems h gt include rtems bsplo h 14 RTEMS C User s Guide void print_name rtems_id the_object char buffer 10 name assumed to be 10 characters or less char result result rtems object get name id sizeof buffer buffer printk ID 0x 08x name s n id result result no name 2 2 2 Object IDs An object ID is a unique unsigned thirty two bit entity composed of four parts API object class node and index The data type rtems_id is used to store object IDs Bits Contents 0 15 Object Index 16 23 Node 24 26 API 27 31 Class The most significant five bits are the object class The next three bits indicate the API to which the object class belongs The next eight bits 16 23 are the number of the node on which this object was created The node number is always one 1 in a single processo
321. processor specific in general it will disable all maskable interrupts place the error code in a known processor dependent place generally either on the stack or in a register and halt the processor The precise actions of the RTEMS fatal error are discussed in the Default Fatal Error Processing chapter of the Applications Supplement document for a specific target processor 17 3 Operations 17 3 1 Announcing a Fatal Error The rtems_fatal_error_occurred directive is invoked when a fatal error is detected Be fore invoking any user supplied fatal error handlers or the RTEMS fatal error handler the rtems_fatal_error_occurred directive stores useful information in the variable _ Internal_errors_What_happened This structure contains three pieces of information e the source of the error API or executive core e whether the error was generated internally by the executive and a e a numeric code to indicate the error type 186 RTEMS C User s Guide The error type indicator is dependent on the source of the error and whether or not the error was internally generated by the executive If the error was generated from an API then the error code will be of that API s error or status codes The status codes for the RTEMS API are in cpukit rtems include rtems rtems status h Those for the POSIX API can be found in lt errno h gt The rtems_fatal_error_occurred directive is responsible for invoking an optional user supplied fatal error h
322. pt service routine NOT a task The directives available to an interrupt service routine are restricted NOTES This directive will not cause the calling task to be preempted Chapter 7 Clock Manager 71 7 Clock Manager 7 1 Introduction The clock manager provides support for time of day and other time related capabilities The directives provided by the clock manager are e rtems_clock_set Set date and time e rtems clock get Get date and time information e rtems_clock_get_tod Get date and time in TOD format e rtems_clock_get_tod_timeval Get date and time in timeval format e rtems_clock_get_seconds_since_epoch Get seconds since epoch e rtems_clock_get_ticks_per_second Get ticks per second e rtems_clock_get_ticks_since_boot Get ticks since boot e rtems clock get uptime Get time since boot e rtems clock set nanoseconds extension Install the nanoseconds since last tick handler e rtems clock tick Announce a clock tick 7 2 Background 7 2 1 Required Support For the features provided by the clock manager to be utilized periodic timer interrupts are required Therefore a real time clock or hardware timer is necessary to create the timer interrupts The rtems clock tick directive is normally called by the timer ISR to announce to RTEMS that a system clock tick has occurred Elapsed time is measured in ticks A tick is defined to be an integral number of microseconds which is specified by the user in the Conf
323. queue create rtems name name uint32 t count size t max message size rtems attribute attribute set rtems id id DIRECTIVE STATUS CODES RTEMS SUCCESSFUL queue created successfully RTEMS INVALID NAME invalid queue name RTEMS INVALID ADDRESS id is NULL RTEMS INVALID NUMBER invalid message count RTEMS INVALID SIZE invalid message size RTEMS TOO MANY too many queues created RTEMS_UNSATISFIED unable to allocate message buffers RTEMS MP NOT CONFIGURED multiprocessing not configured RTEMS TOO MANY too many global objects DESCRIPTION This directive creates a message queue which resides on the local node with the user defined name specified in name For control and maintenance of the queue RT EMS allocates and initializes a QCB Memory is allocated from the RTEMS Workspace for the specified count of messages each of max message size bytes in length The RTEMS assigned queue id returned in id is used to access the message queue Specifying RTEMS PRIORITY in attribute set causes tasks waiting for a message to be ser viced according to task priority When RTEMS FIFO is specified waiting tasks are serviced in First In First Out order NOTES This directive will not cause the calling task to be preempted The following message queue attribute constants are defined by RTEMS e RTEMS_FIFO tasks wait by FIFO default e RTEMS PRIORITY tasks wait by priority e RTEMS LOCAL l
324. queue_get_number_pending Get number of messages pending on a queue e rtems_message_queue_flush Flush all messages on a queue 10 2 Background 10 2 1 Messages A message is a variable length buffer where information can be stored to support com munication The length of the message and the information stored in that message are user defined and can be actual data pointer s or empty 10 2 2 Message Queues A message queue permits the passing of messages among tasks and ISRs Message queues can contain a variable number of messages Normally messages are sent to and received from the queue in FIFO order using the rtems_message_queue_send directive However the rtems_message_queue_urgent directive can be used to place messages at the head of a queue in LIFO order Synchronization can be accomplished when a task can wait for a message to arrive at a queue Also a task may poll a queue for the arrival of a message The maximum length message which can be sent is set on a per message queue basis 10 2 3 Building a Message Queue Attribute Set In general an attribute set is built by a bitwise OR of the desired attribute components The set of valid message queue attributes is provided in the following table e RTEMS_FIFO tasks wait by FIFO default e RTEMS_PRIORITY tasks wait by priority e RTEMS_LOCAL local message queue default e RTEMS_GLOBAL global message queue 114 RTEMS C User s Guide An attribute listed as a de
325. quired to re initialize the system date and time to application specific specifications 80 RTEMS C User s Guide 7 4 7 CLOCK_GET_TICKS_SINCE_BOOT Get ticks since boot CALLING SEQUENCE rtems_interval rtems_clock_get_ticks_since_boot void DIRECTIVE STATUS CODES NONE DESCRIPTION This directive returns the number of clock ticks that have elapsed since the system was booted This is the historical measure of uptime in an RTEMS system The newer service rtems_clock_get_uptime is another and potentially more accurate way of obtaining similar information NOTES This directive is callable from an ISR This directive will not cause the running task to be preempted Re initializing RTEMS causes the system date and time to be reset to an uninitialized state Another call to rtems_clock_set is required to re initialize the system date and time to application specific specifications This directive simply returns the number of times the dirivective rtems_clock_tick has been invoked since the system was booted Chapter 7 Clock Manager 81 7 4 8 CLOCK_GET_UPTIME Get the time since boot CALLING SEQUENCE rtems status code rtems_clock_get_uptime struct timespec uptime i DIRECTIVE STATUS CODES RTEMS SUCCESSFUL clock tick processed successfully RTEMS INVALID ADDRESS time buffer is NULL DESCRIPTION This directive returns the seconds and nanoseconds since the system was booted If the BSP supports nanosecond clock
326. r describes the functionality and directives provided by the Task Manager Chapter 6 Interrupt Manager describes the functionality and directives pro vided by the Interrupt Manager Chapter 7 Clock Manager describes the functionality and directives provided by the Clock Manager Chapter 8 Timer Manager describes the functionality and directives provided by the Timer Manager Chapter 9 Semaphore Manager describes the functionality and directives pro vided by the Semaphore Manager Chapter 10 Message Manager describes the functionality and directives provided by the Message Manager Chapter 11 Event Manager describes the functionality and directives provided by the Event Manager Chapter 12 Signal Manager describes the functionality and directives provided by the Signal Manager Chapter 13 Partition Manager describes the functionality and directives pro vided by the Partition Manager Chapter 14 Region Manager describes the functionality and directives provided by the Region Manager Chapter 15 Dual Ported Memory Manager describes the functionality and di rectives provided by the Dual Ported Memory Manager Chapter 16 I O Manager describes the functionality and directives provided by the I O Manager Chapter 17 Fatal Error Manager describes the functionality and directives pro vided by the Fatal Error Manager Chapter 1 Overview Chapter 18 Chapter 19 Chapter 20 Chapter 21 Chapt
327. r system The least significant sixteen bits form an identifier within a particular object type This identifier called the object index ranges in value from 1 to the maximum number of objects configured for this object type The four components of an object ID make it possible to quickly locate any object in even the most complicated multiprocessor system Object ID s are associated with an object by RTEMS when the object is created and the corresponding ID is returned by the appropriate object create directive The object ID is required as input to all directives involving objects except those which create an object or obtain the ID of an object The object identification directives can be used to dynamically obtain a particular object s ID given its name This mapping is accomplished by searching the name table associated with this object type If the name is non unique then the ID associated with the first occurrence of the name will be returned to the application Since object IDs are returned when the object is created the object identification directives are not necessary in a properly designed single processor application In addition services are provided to portably examine the subcomponents of an RTEMS ID These services are described in detail later in this manual but are prototyped as follows uint32_t rtems_object_id_get_api rtems_id Chapter 2 Key Concepts 15 uint32_t rtems_object_id_get_class rtems_id uint32_t
328. r of size byes in length is copied to that task s message buffer The number of tasks that were unblocked is returned in count NOTES The calling task will be preempted if it has preemption enabled and a higher priority task is unblocked as the result of this directive The execution time of this directive is directly related to the number of tasks waiting on the message queue although it is more efficient than the equivalent number of invocations of rtems message queue send Broadcasting a message to a global message queue which does not reside on the local node will generate a request telling the remote node to broadcast the message to the specified message queue When a task is unblocked which resides on a different node from the message queue a copy of the message is forwarded to the appropriate node the waiting task is unblocked and the proxy used to represent the task is reclaimed 124 RTEMS C User s Guide 10 4 7 MESSAGE QUEUE RECEIVE Receive message from a queue CALLING SEQUENCE rtems status code rtems message queue receive rtems id id void buffer size t size rtems option option set rtems interval timeout 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL message received successfully RTEMS INVALID ID invalid queue id RTEMS INVALID ADDRESS buffer is NULL RTEMS INVALID ADDRESS size is NULL RTEMS UNSATISFIED queue is empty RTEMS_TIMEOUT timed out waiting for message RT
329. re s wait queue is removed and unblocked The unblocked task may preempt the running task if the running task s preemption mode is enabled and the unblocked task has a higher priority than the running task NOTES The calling task may be preempted if it causes a higher priority task to be made ready for execution Releasing a global semaphore which does not reside on the local node will generate a request telling the remote node to release the semaphore If the task to be unblocked resides on a different node from the semaphore then the semaphore allocation is forwarded to the appropriate node the waiting task is unblocked and the proxy used to represent the task is reclaimed The outermost release of a local binary priority inheritance or priority ceiling semaphore may result in the calling task having its priority lowered This will occur if the calling task holds no other binary semaphores and it has inherited a higher priority 112 RTEMS C User s Guide 9 4 6 SEMAPHORE_FLUSH Unblock all tasks waiting on a semaphore CALLING SEQUENCE rtems_status_code rtems_semaphore_flush rtems_id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL semaphore released successfully RTEMS INVALID ID invalid semaphore id RTEMS ILLEGAL ON REMOTE OBJECT not supported for remote semaphores DESCRIPTION This directive unblocks all tasks waiting on the semaphore specified by id Since there are tasks blocked on the semaphor
330. re_obtain directive can be described as follows Chapter 9 Semaphore Manager 103 if semaphore s count is greater than zero then decrement semaphore s count else wait for release of semaphore return SUCCESSFUL When the semaphore cannot be immediately acquired one of the following situations ap plies e By default the calling task will wait forever to acquire the semaphore e Specifying RTEMS_NO_WAIT forces an immediate return with an error status code e Specifying a timeout limits the interval the task will wait before returning with an error status code If the task waits to acquire the semaphore then it is placed in the semaphore s task wait queue in either FIFO or task priority order If the task blocked waiting for a binary semaphore using priority inheritance and the task s priority is greater than that of the task currently holding the semaphore then the holding task will inherit the priority of the blocking task All tasks waiting on a semaphore are returned an error code when the semaphore is deleted When a task successfully obtains a semaphore using priority ceiling and the priority ceiling for this semaphore is greater than that of the holder then the holder s priority will be elevated 9 3 4 Releasing a Semaphore The rtems_semaphore_release directive is used to release the specified semaphore A simplified version of the rtems_semaphore_release directive can be described as follows if no tasks are wai
331. receive server task in bytes The MPCI receive server may invoke nearly all direc tives and may require extra stack space on some targets is the address of the Multiprocessor Communications Interface Table This table contains the entry points of user provided functions which constitute the multiprocessor communications layer This table must be provided in multiprocessor configurations with all entries config ured The format of this table and details regarding its entries can be found in the next section When using the rtems confdefs h mech anism for configuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE MP MPCI TABLE POINTER If not defined by the application then the CONFIGURE MP MPCI TABLE POINTER macro defaults to the address of the table named MPCI table 23 11 Multiprocessor Communications Interface Table This table defines the set of callouts that must be provided by an Multiprocessor Commu nications Interface implementation When using the rtems confdefs h mechanism for configuring an RTEMS application the name of this table is assumed to be MPCI table unless the application sets the CONFIGURE MP MPCI TABLE POINTER when configuring a multiprocessing system The format of this table is defined in the following C structure typedef struct uint32_t uint32_t default_timeout in ticks maximum_packet_size rtems_mpci_initialization_entry initializa
332. rectives This section details the rate monotonic manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes Chapter 19 Rate Monotonic Manager 207 19 4 1 RATE MONOTONIC_CREATE Create a rate monotonic period CALLING SEQUENCE rtems_status_code rtems_rate_monotonic_create rtems_name name rtems_id id DIRECTIVE STATUS CODES RTEMS SUCCESSFUL rate monotonic period created successfully RTEMS INVALID NAME invalid period name RTEMS TOO MANY too many periods created DESCRIPTION This directive creates a rate monotonic period The assigned rate monotonic id is returned in id This id is used to access the period with other rate monotonic manager directives For control and maintenance of the rate monotonic period RT EMS allocates a PCB from the local PCB free pool and initializes it NOTES This directive will not cause the calling task to be preempted 208 RTEMS C User s Guide 19 4 2 RATE MONOTONIC IDENT Get ID of a period CALLING SEQUENCE rtems status code rtems rate monotonic ident rtems name name rtems id id j DIRECTIVE STATUS CODES RTEMS SUCCESSFUL period identified successfully RTEMS INVALID NAME period name not found DESCRIPTION This directive obtains the period id associated with the period name to be acquired If the period name is not unique then the period id w
333. red 187 rtems fatal extension 19 235 rtems Jd bens dah a Ru cedis T 14 19 rtems initialization tasks table 259 rtems initialize before drivers 27 rtems_initialize_data_structures 26 rtems_initialize_device_drivers 28 rtems_initialize_start_multitasking 29 rtems_interrupt_catch 00 65 rtems_interrupt_disable 66 rtems_interrupt_enable 67 rtems_interrupt_flash 0 68 rtems_interrupt_frame 0 19 rtems_interrupt_is_in_progress 69 rtems interrupt level sss 19 rtems interval eese 15 20 rtems 160 ClO088 i 5 A9Gauehs ya ious EE SURG 181 rtems lo CONELO o sick ode ee e GARS 184 rtems lo initialize lose Eo Tr rtems io lookup name s s 179 rfbtens 10 Open c gk e tir e RE 180 rtems lo read sss pua aso RR YR GUERRE SR 182 rtems io register driver 175 rtems io register name 178 rtems io unregister driver 176 rtems lJo write o web DO RReDRHEWPRVESS 183 rftens lSf 2 ve e I9 a e Pe d epETICu ees 20 61 ttemns isr entry o eec te e are ee ee 20 rtems iterate over all threads 56 rtems message queue broadcast 123 rtems message queue create 117 rtems_message_queue_delete 1
334. riority 50 5 4 11 TASK MODE Change the current task mode 51 5 4 12 TASK GET NOTE Get task notepad entry 52 5 4 18 TASK SET NOTE Set task notepad entry 53 5 4 14 TASK WAKE AFTER Wake up after interval 54 5 4 15 TASK WAKE WHEN Wake up when specified 55 5 4 16 ITERATE OVER ALL THREADS Iterate Over Tasks bape dea s ate a RR ACER A E PR HORA RR CC CY GRECE UICE EROR RC eee e s 56 5 4 17 TASK VARIABLE ADD Associate per task variable 57 5 4 18 TASK VARIABLE GET Obtain value of a per task Variable cider t ane ae daria baud opt Sad eens 58 5 4 19 TASK VARIABLE DELETE Remove per task variable munere ved E MER E EM Ree e 59 6 Interrupt Manager 05 61 6 1 Introdu ction issue ore RE Re au rereptrheRRRE NE ug e nae 61 0 2 Baekegrot nd ois dete Ere d iacere mua RR nii Rag 61 6 2 1 Processing an Interrupt 0 cee eee eee eee 61 6 2 2 RTEMS Interrupt Levels 000 62 6 2 3 Disabling of Interrupts by RTEMS 62 6 3 Operations ed sas denedshe cm RO Re ban Er E ai 62 6 3 1 Establishing an ISR 0 eee eee 62 6 3 2 Directives Allowed from an ISR 00 00 eee 63 0 4 DWHEOCUIVOSu s eee ione RR didn ease talit Eod Le s a peto edet 64 6 4 1 INTERRUPT CATCH Establish an ISR 65 6 4 3 INTERRUPT DISABLE Disable Interrupts 66 6 4 3 I
335. rity ceiling for local binary semaphores that use the priority task wait queue blocking discipline When a task of lower priority than the ceiling priority successfully obtains the semaphore its priority is raised to the ceiling priority When the task holding the task completely releases the binary semaphore i e not for a nested release the holder s priority is restored to the value it had before any higher priority was put into effect The need to identify the highest priority task which will attempt to obtain a particular semaphore can be a difficult task in a large complicated system Although the priority ceiling algorithm is more efficient than the priority inheritance algorithm with respect to the maximum number of task priority changes which may occur while a task holds a particular semaphore the priority inheritance algorithm is more forgiving in that it does not require this apriori information The RTEMS implementation of the priority ceiling algorithm takes into account the scenario in which a task holds more than one binary semaphore The holding task will execute at the priority of the higher of the highest ceiling priority or at the priority of the highest priority task blocked waiting for any of the semaphores the task holds Only when the task releases ALL of the binary semaphores it holds will its priority be restored to the normal value 9 2 5 Building a Semaphore Attribute Set In general an attribute set is built by a bi
336. rocessors affect each and every characteristic of a real time system almost always making them more complicated RTEMS addresses these issues by providing simple and flexible real time multiprocessing capabilities The executive easily lends itself to both tightly coupled and loosely coupled configurations of the target system hardware In addition RTEMS supports systems com posed of both homogeneous and heterogeneous mixtures of processors and target boards A major design goal of the RTEMS executive was to transcend the physical boundaries of the target hardware configuration This goal is achieved by presenting the application software with a logical view of the target system where the boundaries between processor nodes are transparent As a result the application developer may designate objects such as tasks queues events signals semaphores and memory blocks as global objects These global objects may then be accessed by any task regardless of the physical location of the object and the accessing task RTEMS automatically determines that the object being accessed resides on another processor and performs the actions required to access the desired object Simply stated RTEMS allows the entire system both hardware and software to be viewed logically as a single system 24 2 Background RTEMS makes no assumptions regarding the connection media or topology of a multipro cessor system The tasks which compose a particular application can b
337. rovided location Second the timer ID may be obtained later using the rtems timer ident directive The timer ID is used by other directives to manipulate this timer 8 3 3 Initiating an Interval Timer The rtems timer fire after and rtems timer server fire after directives initiate a timer to fire a user provided timer service routine after the specified number of clock ticks have elapsed When the interval has elapsed the timer service routine will be invoked from the rtems clock tick directive if it was initiated by the rtems timer fire after directive and from the Timer Server task if initiated by the rtems timer server fire after directive 8 3 4 Initiating a Time of Day Timer The rtems timer fire when and rtems timer server fire when directive initiate a timer to fire a user provided timer service routine when the specified time of day has been reached When the interval has elapsed the timer service routine will be invoked from the Chapter 8 Timer Manager 87 rtems_clock_tick directive by the rtems_timer_fire_when directive and from the Timer Server task if initiated by the rtems_timer_server_fire_when directive 8 3 5 Canceling a Timer The rtems_timer_cancel directive is used to halt the specified timer Once canceled the timer service routine will not fire unless the timer is reinitiated The timer can be reinitiated using the rtems_timer_reset rtems_timer_fire_after and rtems_timer_fire_when directives 8 3 6 Resetting
338. rtems object id get node rtems id uint32 t rtems object id get index rtems id An object control block is a data structure defined by RT EMS which contains the infor mation necessary to manage a particular object type For efficiency reasons the format of each object type s control block is different However many of the fields are similar in func tion The number of each type of control block is application dependent and determined by the values specified in the user s Configuration Table An object control block is allocated at object create time and freed when the object is deleted With the exception of user extension routines object control blocks are not directly manipulated by user applications 2 3 Communication and Synchronization In real time multitasking applications the ability for cooperating execution threads to com municate and synchronize with each other is imperative A real time executive should provide an application with the following capabilities e Data transfer between cooperating tasks e Data transfer between tasks and ISRs e Synchronization of cooperating tasks e Synchronization of tasks and ISRs Most RTEMS managers can be used to provide some form of communication and or syn chronization However managers dedicated specifically to communication and synchroniza tion provide well established mechanisms which directly map to the application s varying needs This level of flexibility allows the applicatio
339. rtition_delete directive allows a partition to be removed and returned to RTEMS When a partition is deleted the PTCB for that partition is returned to the PTCB free list A partition with buffers still allocated cannot be deleted Any task attempting to do so will be returned an error status code 13 4 Directives This section details the partition manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes Chapter 13 Partition Manager 143 13 4 1 PARTITION_CREATE Create a partition CALLING SEQUENCE rtems status code rtems partition create rtems name name void starting address uint32 t length uint32 t buffer size rtems attribute attribute set rtems id id 5 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL partition created successfully RTEMS INVALID NAME invalid partition name RTEMS TOO MANY too many partitions created RTEMS INVALID ADDRESS address not on four byte boundary RTEMS INVALID ADDRESS starting address is NULL RTEMS INVALID ADDRESS id is NULL RTEMS INVALID SIZE length or buffer size is 0 RTEMS INVALID SIZE length is less than the buffer size RTEMS INVALID SIZE buffer size not a multiple of 4 RTEMS MP NOT CONFIGURED multiprocessing not configured RTEMS TOO MANY too many global objects DESCRIPTION This directive creates a partition of fixed size
340. ructure is treated as two overlapping rtems_chain_node structures The permanent head of the chain overlays a node structure on the first and permanent nu11 fields The permanent tail of the chain overlays a node structure on the permanent null and last elements of the structure 28 3 Operations 28 3 1 Multi threading Chains are designed to be used in a multi threading environment The directives list which operations mask interrupts Chains supports tasks and interrupt service routines appending and extracting nodes with out the need for extra locks Chains how ever cannot insure the integrity of a chain for all operations This is the responsibility of the user For example an interrupt service routine extracting nodes while a task is iterating over the chain can have unpredictable results Chapter 28 Chains 311 28 3 2 Creating a Chain To create a chain you need to declare a chain control then add nodes to the control Consider a user structure and chain control typedef struct foo t rtems chain node node uint8 t char data foo rtems chain control chain Add nodes with the following code rtems chain initialize empty amp chain for i 0 i lt count i 1 foo bar malloc sizeof foo if foo return 1 bar gt data malloc size rtems_chain_append amp chain amp bar gt node The chain is initialized and the nodes allocated and appended to the chain This is an example of a pool
341. rue if there is only one node on the chain and false otherwise Chapter 28 Chains 323 28 4 11 Is this Node the Chain Head CALLING SEQUENCE bool rtems chain is head rtems chain control the chain rtems const chain node the node J3 RETURNS This function returns true if the node is the head of the chain and false otherwise DESCRIPTION This function returns true if the node is the head of the chain and false otherwise 324 RTEMS C User s Guide 28 4 12 Is this Node the Chain Tail CALLING SEQUENCE bool rtems chain is tail rtems chain control the chain const rtems chain node the node RETURNS This function returns true if the node is the tail of the chain and false otherwise DESCRIPTION This function returns true if the node is the tail of the chain and false otherwise Chapter 28 Chains 325 28 4 13 Extract a Node CALLING SEQUENCE void rtems_chain_extract rtems_chain_node the_node 25 RETURNS Returns nothing DESCRIPTION This routine extracts the node from the chain on which it resides NOTES Interrupts are disabled while extracting the node to ensure the atomicity of the operation 326 RTEMS C User s Guide 28 4 14 Get the First Node CALLING SEQUENCE rtems_chain_node rtems_chain_get rtems_chain_control the_chain 3 RETURNS Returns a pointer a node If a node was removed then a pointer to that node is returned If the chain was empty then NULL is
342. rupt re sponse times by providing the critical ability to alter task execution which allows a task to be preempted upon exit from an ISR The interrupt manager includes the following directive e rtems_interrupt_catch Establish an ISR e rtems_interrupt_disable Disable Interrupts e rtems interrupt enable Enable Interrupts e rtems interrupt flash Flash Interrupt e rtems interrupt is in progress Is an ISR in Progress 6 2 Background 6 2 1 Processing an Interrupt The interrupt manager allows the application to connect a function to a hardware inter rupt vector When an interrupt occurs the processor will automatically vector to RT EMS RTEMS saves and restores all registers which are not preserved by the normal C calling convention for the target processor and invokes the user s ISR The user s ISR is respon sible for processing the interrupt clearing the interrupt if necessary and device specific manipulation The rtems interrupt catch directive connects a procedure to an interrupt vector The vector number is managed using the rtems vector number data type The interrupt service routine is assumed to abide by these conventions and have a prototype similar to the following rtems isr user isr rtems vector number vector 25 The vector number argument is provided by RTEMS to allow the application to identify the interrupt source This could be used to allow a single routine to service interrupts from multiple insta
343. s in preemption mode Chapter 19 Rate Monotonic Manager 195 19 Rate Monotonic Manager 19 1 Introduction The rate monotonic manager provides facilities to implement tasks which execute in a periodic fashion Critically it also gathers information about the execution of those periods and can provide important statistics to the user which can be used to analyze and tune the application The directives provided by the rate monotonic manager are e rtems_rate_monotonic_create Create a rate monotonic period e rtems_rate_monotonic_ident Get ID of a period e rtems_rate_monotonic_cancel Cancel a period e rtems_rate_monotonic_delete Delete a rate monotonic period e rtems_rate_monotonic_period Conclude current Start next period e rtems_rate_monotonic_get_status Obtain status from a period e rtems_rate_monotonic_get_statistics Obtain statistics from a period e rtems_rate_monotonic_reset_statistics Reset statistics for a period e rtems_rate_monotonic_reset_all_statistics Reset statistics for all periods e rtems_rate_monotonic_report_statistics Print period statistics report 19 2 Background The rate monotonic manager provides facilities to manage the execution of periodic tasks This manager was designed to support application designers who utilize the Rate Monotonic Scheduling Algorithm RMS to ensure that their periodic tasks will meet their deadlines even under transient overload conditions Although designed for hard
344. s directive removes a device driver from the Device Driver Table NOTES Currently no specific checks are made and the driver is not closed Chapter 16 I O Manager 177 16 4 3 IO_INITIALIZE Initialize a device driver CALLING SEQUENCE rtems_status_code rtems_io_initialize rtems_device_major_number major rtems_device_minor_number minor void argument X DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL successfully initialized RTEMS_INVALID_NUMBER invalid major device number DESCRIPTION This directive calls the device driver initialization routine specified in the Device Driver Table for this major number This directive is automatically invoked for each device driver when multitasking is initiated via the initialize_executive directive A device driver initialization module is responsible for initializing all hardware and data structures associated with a device If necessary it can allocate memory to be used during other operations NOTES This directive may or may not cause the calling task to be preempted This is dependent on the device driver being initialized 178 RTEMS C User s Guide 16 4 4 IO REGISTER NAME Register a device CALLING SEQUENCE rtems status code rtems io register name const char name rtems device major number major rtems device minor number minor DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL successfully initialized RTEMS_TOO_MANY too many devices registered DESCRIPTION
345. s executed before the call to any RTEMS initialization routines has the following requirements e Must not make any blocking RTEMS directive calls e If the processor supports multiple privilege levels must leave the processor in the most privileged or supervisory state e Must allocate a stack of sufficient size to execute the initialization and shutdown of the system This stack area will NOT be used by any task once the system is initialized This stack is often reserved via the linker script or in the assembly language start up file e Must initialize the stack pointer for the initialization process to that allocated e Must initialize the processor s Interrupt Vector Table e Must disable all maskable interrupts 226 RTEMS C User s Guide e If the processor supports a separate interrupt stack must allocate the interrupt stack and initialize the interrupt stack pointer At the end of the initialization sequence RTEMS does not return to the BSP initialization code but instead context switches to the highest priority task to begin application execution This task is typically a User Initialization Task which is responsible for performing both local and global application initialization which is dependent on RTEMS facilities It is also responsible for initializing any higher level RTEMS services the application uses such as networking and blocking device drivers 21 2 1 Interrupt Stack Requirements The worst case stack usag
346. s from the RTEMS Workspace When using the rtems confdefs h mechanism for configuring an RT EMS application the value for this field corresponds to the setting of the macro CONFIGURE TASK STACK ALLOCATOR may point to a user provided routine to free task stacks The de fault is to allocate task stacks from the RTEMS Workspace When using the rtems confdefs h mechanism for configuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE TASK STACK DEALLOCATOR indicates whether RTEMS should zero the RTEMS Workspace and C Program Heap as part of its initialization If set to TRUE the Workspace is zeroed Otherwise it is not When using the rtems confdefs h mechanism for configuring an RTEMS applica tion the value for this field corresponds to the setting of the macro CONFIGURE ZERO WORKSPACE AUTOMATICALLY is the maximum number of device drivers that can be registered When using the rtems confdefs h mechanism for configuring an Chapter 23 Configuring a System 253 RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE_MAXIMUM_DRIVERS number of device drivers Device driver table is the number of device drivers for the system There should be the same number of entries in the Device Driver Table If this field is zero then the User driver address table entry should be NULL When using the rtems confdefs h mechanism for configuring an RTEMS app
347. s layer receive is the address of the entry point for the procedure called by RTEMS to retrieve an envelope containing a message from another node This procedure is part of the user supplied multiprocessor communications layer More information regarding the required functionality of these entry points is provided in the Multiprocessor chapter 23 12 Determining Memory Requirements Since memory is a critical resource in many real time embedded systems the RTEMS Classic API was specifically designed to allow unused managers to be forcibly excluded from the run time environment This allows the application designer the flexibility to tailor RTEMS to most efficiently meet system requirements while still satisfying even the most stringent memory constraints As result the size of the RTEMS executive is application dependent It is not necessary for RTEMS Application Developers to calculate the amount of memory required for the RTEMS Workspace This is done automatically by rtems confdefs h See Section 23 13 Configuring a System Sizing the RTEMS RAM Workspace page 267 for more details on how this works In the event you are interested in the memory required Chapter 23 Configuring a System 267 for an instance of a particular RTEMS object please run the test spsize on your target board RTEMS is built to be a library and any routines that you do not directly or indirectly require in your application will NOT be included in your exe
348. s the second step in initializing RTEMS This directive performs initialization that must occur between basis RTEMS data structure initialization and device driver initialization In particular in a multiprocessor configuration this directive will create the MPCI Server Task This directive returns to the caller after completing the basic RTEMS initialization NOTES The Initialization Manager directives must be used in the proper sequence and invokved only once in the life of an application This directive must be invoked with interrupts disabled Interrupts should be disabled as early as possible in the initialization sequence and remain disabled until the first context switch 28 RTEMS C User s Guide 4 4 3 INITIALIZE_DEVICE_DRIVERS Initialize Device Drivers CALLING SEQUENCE void rtems initialize device drivers void DIRECTIVE STATUS CODES NONE DESCRIPTION This directive is called by the Board Support Package as the third step in initializing RTEMS This directive initializes all statically configured device drivers and performs all RTEMS initialization which requires device drivers to be initialized In a multiprocessor configuration this service will initialize the Multiprocessor Communi cations Interface MPCI and synchronize with the other nodes in the system After this directive is executed control will be returned to the Board Support Package framework NOTES The Initialization Manager directives must
349. sage_queue_receive directive should be RTEMS_NO_WAIT 10 3 Operations 10 3 1 Creating a Message Queue The rtems_message_queue_create directive creates a message queue with the user defined name The user specifies the maximum message size and maximum number of messages which can be placed in the message queue at one time The user may select FIFO or task priority as the method for placing waiting tasks in the task wait queue RTEMS allocates a Queue Control Block QCB from the QCB free list to maintain the newly created queue as well as memory for the message buffer pool associated with this message queue RTEMS also generates a message queue ID which is returned to the calling task For GLOBAL message queues the maximum message size is effectively limited to the longest message which the MPCI is capable of transmitting 10 3 2 Obtaining Message Queue IDs When a message queue is created RTEMS generates a unique message queue ID The message queue ID may be obtained by either of two methods First as the result of an invocation of the rtems message queue create directive the queue ID is stored in a user provided location Second the queue ID may be obtained later using the rtems message queue ident directive The queue ID is used by other message manager directives to access this message queue Chapter 10 Message Manager 115 10 3 3 Receiving a Message The rtems_message_queue_receive directive attempts to retrieve a message from
350. scheduling eR DSERPRSRRS PR doves ne RI TIER 189 scheduling mechanisms suuuusuuu 189 segment definition 00 149 semaphotf s 2e slcg lr E RR ee M Eriki tS 99 send event set to a task 00 132 send message to a queue 0006 121 send signal S6 ccascasce be der eERRE 139 set object name 0 eee eee ee eee 295 set task mode cece eee eee ee eee 51 set task notepad entry ssssssssss 53 set task preemption mode ususssuse 51 set task PriOvity iesus bee RE RE Rs 50 set the time of day 000000 74 shutdown RTEMS eeseees 30 signal set building 0 135 Sn M Em 135 special device services eee ee eee 184 sporadic task definition 00 196 start current period ee eee ee eee 211 start multitasking esee 29 Starting task ecel b RR ERR ERE peas 44 suspending task ere Rr Rte m AT T task argumentis nce AE RR RR eee 34 task attributes building 35 task mode iones nero eret trusts 33 354 task mode building 00 36 task Priority e repu rre Pita see ees 32 189 task private daba i es reete 57 59 task private variable s ssserscsisesisrnisess 57 99 bask protolype seem hpex e rh epe 34 task scheduling Rees 189 task state transitions
351. se disciplines must adopt standards which channel individual software efforts toward a common goal The push for standards in the software development field has been met with various degrees of success The Microprocessor Operating Systems Interfaces MOSI effort has experienced only limited success As popular as the UNIX operating system has grown the attempt to develop a standard interface definition to allow portable application development has only recently begun to produce the results needed in this area Unfortunately very little effort has been expended to provide standards addressing the needs of the real time community Several organizations have addressed this need during recent years The Real Time Executive Interface Definition RTEID was developed by Motorola with technical input from Software Components Group RTEID was adopted by the VMEbus International Trade Association VITA as a baseline draft for their proposed standard multiprocessor real time executive interface Open Real Time Kernel Interface Definition ORKID These two groups are currently working together with the IEEE P1003 4 commit tee to insure that the functionality of their proposed standards is adopted as the real time extensions to POSIX This emerging standard defines an interface for the development of real time software to ease the writing of real time application programs that are directly portable across multiple real time executive implementations This
352. sks blocked waiting for the barrier to be released will be readied and returned a status code which indicates that the barrier was deleted Any subsequent references to the barrier s name and ID are invalid 20 4 Directives This section details the barrier manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes 220 RTEMS C User s Guide 20 4 1 BARRIER_CREATE Create a barrier CALLING SEQUENCE rtems_status_code rtems barrier create rtems name name rtems attribute attribute set uint32 t maximum waiters rtems id id DIRECTIVE STATUS CODES RTEMS SUCCESSFUL barrier created successfully RTEMS INVALID NAME invalid barrier name RTEMS INVALID ADDRESS id is NULL RTEMS TOO MANY too many barriers created DESCRIPTION This directive creates a barrier which resides on the local node The created barrier has the user defined name specified in name and the initial count specified in count For control and maintenance of the barrier RTEMS allocates and initializes a BCB The RTEMS assigned barrier id is returned in id This barrier id is used with other barrier related directives to access the barrier RTEMS BARRIER MANUAL RELEASE only release Specifying RTEMS BARRIER AUTOMATIC RELEASE in attribute set causes tasks calling the rtems barrier wait directive to block until there are maximum
353. sks have met their first deadlines at time 200 and the task set is schedulable using the First Deadline Rule 19 2 5 6 Relaxation of Assumptions The assumptions used to develop the RMS schedulability rules are uncommon in most real time systems For example it was assumed that tasks have constant unvarying execution time It is possible to relax this assumption simply by using the worst case execution time of each task Another assumption is that the tasks are independent This means that the tasks do not wait for one another or contend for resources This assumption can be relaxed by accounting for the amount of time a task spends waiting to acquire resources Similarly each task s execution time must account for any I O performed and any RTEMS directive calls In addition the assumptions did not account for the time spent executing interrupt service routines This can be accounted for by including all the processor utilization by interrupt service routines in the utilization calculation Similarly one should also account for the impact of delays in accessing local memory caused by direct memory access and other processors accessing local dual ported memory The assumption that nonperiodic tasks are used only for initialization or failure recovery can be relaxed by placing all periodic tasks in the critical task set This task set can be scheduled and analyzed using RMS All nonperiodic tasks are placed in the non critical task set Alth
354. specified the api and the class NOTES This directive is strictly local and does not impact task scheduling The string returned is from constant space Do not modify or free it Chapter 27 Object Services 307 27 4 16 OBJECT GET CLASS INFORMATION Obtain Class Information CALLING SEQUENCE rtems status code rtems object get class information uint32 t the api uint32 t the class rtems object api class information info Jz DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL information obtained successfully RTEMS_INVALID_ADDRESS info is NULL RTEMS_INVALID_NUMBER invalid api or the_class If successful the structure located at info will be filled in with information about the specified api the_class pairing DESCRIPTION This service returns information about the object class indicated by the specified api and the_class This structure is defined as follows typedef struct rtems_id minimum_id rtems_id maximum_id uint32_t maximum bool auto_extend uint32_t unallocated rtems_object_api_class_information NOTES This directive is strictly local and does not impact task scheduling Chapter 28 Chains 309 28 Chains 28 1 Introduction The Chains API is an interface to the Super Core score chain implementation The Super Core uses chains for all list type functions This includes wait queues and task queues The Chains API provided by RTEMS is e rtems_chain_node Chain node used in user objects
355. stitute the RTEMS API for a particular application For example the user can configure the maximum number of tasks for this application The RTEMS API Configuration Table is defined in the following C structure Chapter 23 Configuring a System 255 typedef struct uint32_t maximum_tasks uint32_t maximum_timers uint32 t maximum_semaphores uint32 t maximum message queues uint32 t maximum partitions uint32 t maximum regions uint32 t maximum ports uint32 t maximum periods uint32 t maximum barriers uint32 t number of initialization tasks rtems initialization tasks table User initialization tasks table rtems api configuration table maximum tasks maximum timers maximum semaphores is the maximum number of tasks that can be concurrently active created in the system including initialization tasks When using the rtems confdefs h mechanism for configuring an RT EMS appli cation the value for this field corresponds to the setting of the macro CONFIGURE MAXIMUM TASKS If not defined by the application then the CONFIGURE MAXIMUM TASKS macro defaults to 0 is the maximum number of timers that can be concurrently active in the system When using the rtems confdefs h mechanism for configuring an RTEMS application the value for this field corre sponds to the setting of the macro CONFIGURE MAXIMUM TIMERS If not defined by the application then the CONFIGURE MAXIMUM TIMERS macro defaults to 0 is the maximu
356. sulting segment is large enough to satisfy the task s request A rate monotonic period expires for a task which blocked by a call to the rtems_rate_monotonic_period directive A timeout interval expires for a task which was blocked waiting on a message event semaphore or segment with a timeout specified A running task issues a directive which deletes a message queue a semaphore or a region on which the blocked task is waiting A running task issues a rtems_task_restart directive for the blocked task The running task with its preemption mode enabled may be made ready by issuing any of the directives that may unblock a task with a higher priority This directive may be issued from the running task itself or from an ISR A ready task occupies the executing state when it has control of the CPU A task enters the executing state due to any of the following conditions The task is the highest priority ready task in the system The running task blocks and the task is next in the scheduling queue The task may be of equal priority as in round robin scheduling or the task may possess the highest priority of the remaining ready tasks The running task may reenable its preemption mode and a task exists in the ready queue that has a higher priority than the running task The running task lowers its own priority and another task is of higher priority as a result The running task raises the priority of a task above its own and the running task i
357. system for insertion in the local copy of the global object table The total number of global objects including partitions is limited by the maxi mum_global_objects field in the Configuration Table Chapter 13 Partition Manager 145 13 4 2 PARTITION_IDENT Get ID of a partition CALLING SEQUENCE rtems_status_code rtems_partition_ident rtems_name name uint32_t node rtems id id Jz DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL partition identified successfully RTEMS_INVALID_ADDRESS id is NULL RTEMS_INVALID_NAME partition name not found RTEMS_INVALID_NODE invalid node id DESCRIPTION This directive obtains the partition id associated with the partition name If the partition name is not unique then the partition id will match one of the partitions with that name However this partition id is not guaranteed to correspond to the desired partition The partition id is used with other partition related directives to access the partition NOTES This directive will not cause the running task to be preempted If node is RTEMS_SEARCH_ALL_NODES all nodes are searched with the local node being searched first All other nodes are searched with the lowest numbered node searched first If node is a valid node number which does not represent the local node then only the partitions exported by the designated node are searched This directive does not generate activity on remote nodes It accesses only the local copy of th
358. t set to a task 132 11 4 2 EVENT RECEIVE Receive event condition 133 12 Signal Manager ceo oce c i aen 135 12 1 Introduction Rt cere te E a daeh EE PEE 135 12 2 Background di csnatwoddenenn Er eta ces aee ape d war rach 135 12 2 1 Signal Manager Definitions 00 eee eee 135 12 2 2 A Comparison of ASRs and ISRs 004 135 12 2 3 Building a Signal Set 0 cece ee eee 135 12 2 4 Building an ASR Mode 00 cece eee 136 12 9 Operations asacegss oan qure aie xoc ch rao aae Roca 136 12 3 1 Establishing an ASR eee eee 136 12 3 2 Sending Signal Set acce ese da bere sean eens 137 12 3 8 Processing an ASR 00 0 e eee eee eee 137 WA D rectvess iore RR Re OU ETCUREREP RP REEF 137 12 4 4 SIGNAL CATCH Establish an ASR 138 12 4 2 SIGNAL SEND Send signal set to a task 139 13 Partition Manager coeee erm 141 13 1 Introducti n eere nb reae eas reb vem de ea 141 132 Background i sc 0icasedaiendes sg onan minn Aaa Rd nen 141 13 2 1 Partition Manager Definitions 0 00 141 13 2 2 Building a Partition Attribute Set 141 19 9 ODeratlons codsma c ae mkv ERRARE yeas oa ade edes 141 13 3 1 Creating Partition usce etate p e E 141 13 3 2 Obtaining Partition IDs esses 142 13 3 3 Acquiring a Buffer essees oce seemed et reete eene 142 13 34 Releasing Bull
359. talled independently of the others All user extensions are optional and RTEMS places no naming restrictions on the user The user extension entry points are copied into an internal RTEMS structure This means the user does not need to keep the table after creating it and changing the handler entry points dynamically in a table once created has no effect Creating a table local to a function can save space in space limited applications Extension switches do not effect the context switch overhead if no switch handler is installed 22 2 2 TCB Extension Area RTEMS provides for a pointer to a user defined data area for each extension set to be linked to each task s control block This set of pointers is an extension of the TCB and can be used to store additional data required by the user s extension functions It is also possible for a user extension to utilize the notepad locations associated with each task although this may conflict with application usage of those particular notepads The TCB extension is an array of pointers in the TCB The index into the table can be obtained from the extension id returned when the extension is created index rtems object id get index extension id The number of pointers in the area is the same as the number of user extension sets con figured This allows an application to augment the TCB with user defined information For example an application could implement task profiling by storing timing statist
360. te Note that the preemption setting has no effect on the manner in which a task is scheduled It only applies once a task has control of the processor 18 2 3 Timeslicing Timeslicing or round robin scheduling is an additional method which can be used to alter the basic scheduling algorithm Like preemption timeslicing is specified on a task by task basis using the timeslicing mode flag RTEMS_TIMESLICE_MASK If timeslicing is enabled for a task RTEMS_TIMESLICE then RTEMS will limit the amount of time the task can execute before the processor is allocated to another task Each tick of the real time clock reduces the currently running task s timeslice When the execution time equals the timeslice RTEMS will dispatch another task of the same priority to execute If there are no other tasks of the same priority ready to execute then the current task is allocated an additional timeslice and continues to run Remember that a higher priority task will preempt the task unless preemption is disabled as soon as it is ready to run even if the task has not used up its entire timeslice 18 2 4 Manual Round Robin The final mechanism for altering the RTEMS scheduling algorithm is called manual round robin Manual round robin is invoked by using the rtems_task_wake_after directive with a time interval of RTEMS_YIELD_PROCESSOR This allows a task to give up the processor and be immediately returned to the ready chain at the end of its priority group I
361. te a queue ALT 10 4 3 MESSAGE_QUEUE_IDENT Get ID of a queue 119 10 4 3 MESSAGE QUEUE DELETE Delete a queue 120 10 4 4 MESSAGE QUEUE SEND Put message at rear of a queue I 121 10 4 5 MESSAGE QUEUE URGENT Put message at front of a QUEUE a auiem Leere ree d eee deer e Soe E ERR rd eae 122 10 4 0 V MESSAGE QUEUE BROADCAST Broadcast N messages toaqueue m 128 10 4 7 MESSAGE QUEUE RECEIVE Receive message from a aD Pm 124 10 4 8 MESSAGE QUEUE GET NUMBER PENDING Get number of messages pending on a queue susssss 126 10 4 9 MESSAGE QUEUE FLUSH Flush all messages on a vi RTEMS C User s Guide 11 Event Manage eec RR nx eh 129 IL JntroductOn sce save eh patuere bee ie meo asc dtca 129 11 2 Backgrounds ee eec ee tek Fee Lea ce s dite lote dt RA 129 I1 2 1 Event S608 d ipow ete pene EEr E Ea enone E e 129 11 2 2 Building an Event Set or Condition 129 11 2 8 Building an EVENT RECEIVE Option Set 130 11 3 Operations e tega ers te Tet eee edhe CE exer DEEP RP ESUbd 130 11 3 Sending an Event Set ssssssssssseseeesees 130 11 8 2 Receiving an Event Set 00 cece eee eee 130 11 3 3 Determining the Pending Event Set 131 11 3 4 Receiving all Pending Events 22000 131 11 4 Directives ic sii eue Era eee beer tobias Fate UD EDITUS 131 11 4 44 EVENT SEND Send even
362. te at regular intervals and comply with a hard deadline The actual hardware address of a resource A mechanism used to determine if an event has occurred by periodi cally checking for a particular status Typical events include arrival of data completion of an action and errors A collection from which resources are allocated A term used to describe the ease with which software can be rehosted on another computer The act of sending an event message semaphore or signal to a task The act of forcing a task to relinquish the processor and dispatching to another task A mechanism used to represent the relative importance of an element in a set of items RTEMS uses priority to determine which task should execute An algorithm that calls for the lower priority task holding a resource to have its priority increased to that of the highest priority task blocked waiting for that resource This avoids the problem of priority inversion A form of indefinite postponement which occurs when a high priority tasks requests access to shared resource currently allocated to low priority task The high priority task must block until the low priority task releases the resource The percentage of processor time used by a task or a set of tasks An RTEMS control structure used to represent on a remote node a task which must block as part of a remote operation Chapter 31 Glossary 343 Proxy Control Block A data structure associated with
363. tems id id 25 DIRECTIVE STATUS CODES Returns the node portion of the object Id DESCRIPTION This directive returns the node portion of the provided object id NOTES This directive is strictly local and does not impact task scheduling This directive does NOT validate the id provided Chapter 27 Object Services 299 27 4 8 OBJECT ID GET INDEX Obtain Index from Id CALLING SEQUENCE uint32 t rtems object id get index rtems id id 25 DIRECTIVE STATUS CODES Returns the index portion of the object Id DESCRIPTION This directive returns the index portion of the provided object id NOTES This directive is strictly local and does not impact task scheduling This directive does NOT validate the id provided 300 RTEMS C User s Guide 27 4 9 BUILD_ID Build Object Id From Components CALLING SEQUENCE rtems_id rtems_build_id uint32_t the_api uint32_t the_class uint32_t the_node uint32_t the_index DIRECTIVE STATUS CODES Returns an object Id constructed from the provided arguments DESCRIPTION This service constructs an object Id from the provided the_api the_class the_node and the_index NOTES This directive is strictly local and does not impact task scheduling This directive does NOT validate the arguments provided or the Object id returned Chapter 27 Object Services 301 27 4 10 OBJECT_ID_API_MINIMUM Obtain Minimum API Value CALLING SEQUENCE uint32 t rtems_obje
364. tern in memory At each task switch the stack bounds checker s task switch extension is executed This extension checks that e the last n bytes of the task s stack have not been overwritten If this pattern has been damaged it indicates that at some point since this task was context switch to the CPU it has used too much stack space e the current stack pointer of the task is not within the address range allocated for use as the task s stack If either of these conditions is detected then a blown stack error is reported using the printk routine The number of bytes checked for an overwrite is processor family dependent The minimum stack frame per subroutine call varies widely between processor families On CISC families like the Motorola MC68xxx and Intel ix86 all that is needed is a return address On more complex RISC processors the minimum stack frame per subroutine call may include space to save a significant number of registers Another processor dependent feature that must be taken into account by the stack bounds checker is the direction that the stack grows On some processor families the stack grows 280 RTEMS C User s Guide up or to higher addresses as the task executes On other families it grows down to lower addresses The stack bounds checker implementation uses the stack description definitions provided by every RTEMS port to get for this information 25 3 Operations 25 3 1 Initializing the Stack Bounds Chec
365. ternal address is set to the given internal address NOTES This directive is callable from an ISR This directive will not cause the calling task to be preempted Chapter 16 I O Manager 171 16 I O Manager 16 1 Introduction The input output interface manager provides a well defined mechanism for accessing device drivers and a structured methodology for organizing device drivers The directives provided by the I O manager are e rtems io initialize Initialize a device driver e rtems io register driver Register a device driver e rtems io unregister driver Unregister a device driver e rtems io register name Register a device name e rtems io lookup name Look up a device name e rtems io open Open a device e rtems io close Close a device e rtems io read head from a device e rtems io write Write to a device e rtems io control Special device services 16 2 Background 16 2 1 Device Driver Table Each application utilizing the RTEMS I O manager must specify the address of a Device Driver Table in its Configuration Table This table contains each device driver s entry points that is to be initialised by RTEMS during initialization Each device driver may contain the following entry points e Initialization e Open e Close e Read e Write e Control If the device driver does not support a particular entry point then that entry in the Config uration Table should be NULL RTEMS will return RTEMS SUCC
366. the C Malloc Family of routines e CONFIGURE MALLOC BSP SUPPORTS SBRK is defined by a BSP to indicate that it does not allocate all available memory to the C Program Heap used by the Malloc Family of routines If defined when malloc is unable to allocate memory it will call the BSP supplied sbrk to obtain more memory e CONFIGURE LIBIO MAXIMUM FILE DESCRIPTORS is set to the maximum number of files that can be concurrently open Libio requires a Classic RTEMS semaphore for each file descriptor as well as one global one The default value is 3 file descriptors which is enough to support standard input output and error output e CONFIGURE TERMIOS DISABLED is defined if the software implementing POSIX termios functionality is not going to be used by this application By default this is not defined and resources are reserved for the termios functionality e CONFIGURE NUMBER OF TERMIOS PORTS is set to the number of ports using the termios functionality Each concurrently active termios port requires resources By default this is set to 1 so a console port can be used e CONFIGURE HAS OWN MOUNT TABLE is defined when the application provides their own filesystem mount table The mount table is an array of rtems filesystem mount table t entries pointed to by the global variable rtems filesystem mount table The number of entries in this table is in an integer variable named rtems_ filesystem mount table t e CONFIGURE USE IMFS AS
367. the region specified by id The address of the allocated segment is returned in segment The RTEMS_WAIT and RTEMS_NO_WAIT components of the options parameter are used to specify whether the calling tasks wish to wait for a segment to become available or return immediately if no segment is available For either option if a sufficiently sized segment is available then the segment is successfully acquired by returning immediately with the RTEMS_SUCCESSFUL status code If the calling task chooses to return immediately and a segment large enough is not avail able then an error code indicating this fact is returned If the calling task chooses to wait for the segment and a segment large enough is not available then the calling task is placed on the region s segment wait queue and blocked If the region was created with the RTEMS_PRIORITY option then the calling task is inserted into the wait queue according to its priority However if the region was created with the RTEMS_FIFO option then the calling task is placed at the rear of the wait queue The timeout parameter specifies the maximum interval that a task is willing to wait to obtain a segment If timeout is set to RTEMS_NO_TIMEOUT then the calling task will wait forever NOTES The actual length of the allocated segment may be larger than the requested size because a segment size is always a multiple of the region s page size The following segment acquisition option constants are defi
368. the rtems_clock_tick directive which is called from the user s real time clock ISR to inform RTEMS that a tick has elapsed The tick frequency value defined in microseconds is a configuration parameter found in the Configuration Table RTEMS Chapter 7 Clock Manager 73 divides one million microseconds one second by the number of microseconds per tick to determine the number of calls to the rtems_clock_tick directive per second The frequency of rtems clock tick calls determines the resolution granularity for all time dependent RTEMS actions For example calling rtems clock tick ten times per second yields a higher resolution than calling rtems clock tick two times per second The rtems clock tick directive is responsible for maintaining both calendar time and the dynamic set of timers 7 3 2 Setting the Time The rtems clock set directive allows a task or an ISR to set the date and time maintained by RTEMS If setting the date and time causes any outstanding timers to pass their deadline then the expired timers will be fired during the invocation of the rtems clock set directive 7 3 3 Obtaining the Time The rtems clock get directive allows a task or an ISR to obtain the current date and time or date and time related information The current date and time can be returned in either native or UNIX style format Additionally the application can obtain date and time related information such as the number of seconds since the RTEMS
369. the task being restarted has a higher priority The task must reside on the local node even if the task was created with the RTEMS GLOBAL option 46 RTEMS C User s Guide 5 4 6 TASK_DELETE Delete a task CALLING SEQUENCE rtems_status_code rtems_task_delete rtems_id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL task restarted successfully RTEMS INVALID ID task id invalid RTEMS ILLEGAL ON REMOTE OBJECT cannot restart remote task DESCRIPTION This directive deletes a task either the calling task or another task as specified by id RTEMS stops the execution of the task and reclaims the stack memory any allocated delay or timeout timers the TCB and if the task is RTEMS FLOATING POINT its floating point context area RTEMS does not reclaim the following resources region segments partition buffers semaphores timers or rate monotonic periods NOTES A task is responsible for releasing its resources back to RTEMS before deletion To insure proper deallocation of resources a task should not be deleted unless it is unable to execute or does not hold any RTEMS resources If a task holds RTEMS resources the task should be allowed to deallocate its resources before deletion A task can be directed to release its resources and delete itself by restarting it with a special argument or by sending it a message an event or a signal Deletion of the current task RTEMS SELF will force RTEMS to select anoth
370. ther tasks when the outermost rtems_semaphore_ obtain is matched with a rtems_semaphore_release Simple binary semaphores do not allow nested access and so can be used for task synchro nization 9 2 2 Priority Inversion Priority inversion is a form of indefinite postponement which is common in multitasking preemptive executives with shared resources Priority inversion occurs when a high priority tasks requests access to shared resource which is currently allocated to low priority task The high priority task must block until the low priority task releases the resource This problem is exacerbated when the low priority task is prevented from executing by one or more medium priority tasks Because the low priority task is not executing it cannot complete its interaction with the resource and release that resource The high priority task is effectively prevented from executing by lower priority tasks 9 2 3 Priority Inheritance Priority inheritance is an algorithm that calls for the lower priority task holding a resource to have its priority increased to that of the highest priority task blocked waiting for that resource Each time a task blocks attempting to obtain the resource the task holding the resource may have its priority increased RTEMS supports priority inheritance for local binary semaphores that use the priority task wait queue blocking discipline When a task of higher priority than the task holding the semaphore blocks the pr
371. timer 91 8 4 5 TIMER FIRE AFTER Fire timer after interval 92 8 4 6 TIMER FIRE WHEN Fire timer when specified 93 8 4 7 TIMER INITIATE SERVER Initiate server for task based TIMERS 4 es bv erePRRERST S Hoa AR wae ee ERE EGG EE 94 8 4 8 TIMER_ SERVER_FIRE_AFTER Fire task based timer after Interval ee iecore RTPIPPEPPIUSUPUOUS DOUDUOPDPEeIi eue 95 8 4 9 TIMER SERVER FIRE WHEN Fire task based timer when specified cuisse cesset eon DERE Ee cesta M RP nena 96 8 4 10 TIMER RESET Reset an interval timer 97 9 Semaphore Manager 99 OE Inb6FOGQUCblOI 24sec erties ees ces achicha seer en Laveen enero 99 9 2 Background isis ta garee Cer dives ORPERESENda dea es 99 9 2 1 Nested Resource ACCESS 0 cece es 99 9 2 2 Priority Inversion is mu e pr FI EERC ER 3E 100 9 2 3 Priority Inheritance ssssssesseeeesseeeeseeeeh 100 9 2 4 Priority Ceiling Loo em res ere e REN ERA Ea bac RE 100 9 2 5 Building a Semaphore Attribute Set iussus 101 9 2 6 Building SEMAPHORE OBTAIN Option Set 102 9 3 OperatlolSuocoe seen ebreP ERE arr Pena wee eee dae aha 102 9 3 1 Creating a Semaphore 0 0 cece ee eee ee 102 9 3 2 Obtaining Semaphore IDs 0c eee eee eee 102 9 3 8 Acquiring a Semaphore 0 0 cece cece eee 102 9 3 4 Releasing a Semaphore 00 cee eee eee eee eee 103 9 3 5
372. ting on this semaphore then increment semaphore s count else assign semaphore to a waiting task return SUCCESSFUL If this is the outermost release of a binary semaphore that uses priority inheritance or priority ceiling and the task does not currently hold any other binary semaphores then the task performing the rtems_semaphore_release will have its priority restored to its normal value 9 3 5 Deleting a Semaphore The rtems_semaphore_delete directive removes a semaphore from the system and frees its control block A semaphore can be deleted by any local task that knows the semaphore s ID As a result of this directive all tasks blocked waiting to acquire the semaphore will be readied and returned a status code which indicates that the semaphore was deleted Any subsequent references to the semaphore s name and ID are invalid 104 RTEMS C User s Guide 9 4 Directives This section details the semaphore manager s directives A subsection is dedicated to each of this manager s directives and describes the calling sequence related constants usage and status codes Chapter 9 Semaphore Manager 105 9 4 1 SEMAPHORE_CREATE Create a semaphore CALLING SEQUENCE rtems_status_code rtems_semaphore_create rtems_name name uint32_t count rtems_attribute attribute_set rtems_task_priority priority_ceiling rtems_id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL semaphore created successfully RTEMS INVALID N
373. tion rtems_mpci_get_packet_entry get_packet rtems_mpci_return_packet_entry return_packet 266 RTEMS C User s Guide rtems_mpci_send_entry send_packet rtems_mpci_receive_entry receive_packet rtems_mpci_table default timeout is the default maximum length of time a task should block waiting for a response to a directive which results in communication with a remote node The maximum length of time is a function the user supplied multiprocessor communications layer and the media used This timeout only applies to directives which would not block if the operation were performed locally maximum packet size is the size in bytes of the longest packet which the MPCI layer is capable of sending This value should represent the total number of bytes available for a RT EMS interprocessor messages initialization is the address of the entry point for the initialization procedure of the user supplied multiprocessor communications layer get packet is the address of the entry point for the procedure called by RTEMS to obtain a packet from the user supplied multiprocessor communi cations layer return packet is the address of the entry point for the procedure called by RTEMS to return a packet to the user supplied multiprocessor communica tions layer send is the address of the entry point for the procedure called by RTEMS to send an envelope to another node This procedure is part of the user supplied multiprocessor communication
374. tions It is typically viewed as a logical extension of the primary processor object In this document this term is used to refer collectively to tasks timers message queues partitions regions semaphores ports and rate monotonic periods All RTEMS objects have IDs and user assigned names object oriented A term used to describe systems with common mechanisms for uti lizing a variety of entities Object oriented systems shield the appli cation from implementation details 342 operating system overhead packet partition RTEMS C User s Guide The software which controls all the computer s resources and provides the base upon which application programs can be written The portion of the CPUs processing power consumed by the operat ing system A buffer which contains the messages passed between nodes in a multiprocessor system A packet is the contents of an envelope An RTEMS object which is used to allocate and deallocate fixed size blocks of memory from an dynamically specified area of memory Partition Control Block pending periodic task physical address poll pool portability posting preempt priority priority inheritance priority inversion processor utilization proxy A data structure associated with each partition used by RTEMS to manage that partition A term used to describe a task blocked waiting for an event message semaphore or signal A task which must execu
375. to support the timeout functionality of this directive 224 RTEMS C User s Guide 20 4 5 BARRIER RELEASE Release a barrier CALLING SEQUENCE rtems status code rtems barrier release rtems id id uint32 t released DIRECTIVE STATUS CODES RTEMS SUCCESSFUL barrier released successfully RTEMS INVALID ID invalid barrier id DESCRIPTION This directive releases the barrier specified by id All tasks waiting at the barrier will be unblocked If the running task s preemption mode is enabled and one of the unblocked tasks has a higher priority than the running task NOTES The calling task may be preempted if it causes a higher priority task to be made ready for execution Chapter 21 Board Support Packages 225 21 Board Support Packages 21 1 Introduction A board support package BSP is a collection of user provided facilities which interface RTEMS and an application with a specific hardware platform These facilities may include hardware initialization device drivers user extensions and a Multiprocessor Communica tions Interface MPCI However a minimal BSP need only support processor reset and initialization and if needed a clock tick 21 2 Reset and Initialization An RTEMS based application is initiated or re initiated when the processor is reset This initialization code is responsible for preparing the target platform for the RTEMS applica tion Although the exact actions performed by the initiali
376. tring name this method will free the existing name to the RTEMS Workspace and allocate enough memory from the RTEMS Workspace to make a copy of the string located at name If the object specified by id is of a class that has a thirty two bit integer style name then the first four characters in name will be used to construct the name name to the RTEMS Workspace and allocate enough memory from the RTEMS Workspace to make a copy of the string 296 RTEMS C User s Guide 27 4 5 OBJECT ID GET API Obtain API from Id CALLING SEQUENCE uint32 t rtems_object_id_get_api rtems id id DIRECTIVE STATUS CODES Returns the API portion of the object Id DESCRIPTION This directive returns the API portion of the provided object id NOTES This directive is strictly local and does not impact task scheduling This directive does NOT validate the id provided Chapter 27 Object Services 297 27 4 6 OBJECT_ID_GET_CLASS Obtain Class from Id CALLING SEQUENCE uint32 t rtems object id get class rtems id id 25 DIRECTIVE STATUS CODES Returns the class portion of the object Id DESCRIPTION This directive returns the class portion of the provided object id NOTES This directive is strictly local and does not impact task scheduling This directive does NOT validate the id provided 298 RTEMS C User s Guide 27 4 7 OBJECT_ID_GET_NODE Obtain Node from Id CALLING SEQUENCE uint32 t rtems_object_id_get_node r
377. twise OR of the desired attribute components The following table lists the set of valid semaphore attributes e RTEMS_FIFO tasks wait by FIFO default e RTEMS_PRIORITY tasks wait by priority e RTEMS_BINARY_SEMAPHORE restrict values to 0 and 1 e RTEMS_COUNTING_SEMAPHORE no restriction on values default e RTEMS_SIMPLE_BINARY_SEMAPHORE restrict values to 0 and 1 do not allow nested access allow deletion of locked semaphore e RTEMS_NO_INHERIT_PRIORITY do not use priority inheritance default e RTEMS_INHERIT_PRIORITY use priority inheritance e RTEMS_PRIORITY_CEILING use priority ceiling e RTEMS_NO_PRIORITY_CEILING do not use priority ceiling default e RTEMS_LOCAL local task default e RTEMS_GLOBAL global task Attribute values are specifically designed to be mutually exclusive therefore bitwise OR and addition operations are equivalent as long as each attribute appears exactly once in the component list An attribute listed as a default is not required to appear in the attribute list although it is a good programming practice to specify default attributes If all defaults are desired the attribute RTEMS_DEFAULT_ATTRIBUTES should be specified on this call This example demonstrates the attribute_set parameter needed to create a local semaphore with the task priority waiting queue discipline The attribute_set parameter passed to the rtems_semaphore_create directive could be either RTEMS_PRIORITY or RTEMS_
378. ultiple Periods This example consists of a single periodic task which after initialization performs two sets of actions every 100 clock ticks The first set of actions is performed in the first forty clock 204 RTEMS C User s Guide ticks of every 100 clock ticks while the second set of actions is performed between the fortieth and seventieth clock ticks The last thirty clock ticks are not used by this task Chapter 19 Rate Monotonic Manager 205 rtems_task Periodic_task rtems_task_argument arg rtems_name name 1 name 2 rtems id period 1 period 2 rtems status code status name 1 rtems build name P E R 1 D name 2 rtems build name P E R 2 void rtems rate monotonic create name 1 amp period 1 void rtems rate monotonic create name 2 amp period 2 while 1 1 if rtems_rate_monotonic_period period_1 100 TIMEOUT break if rtems_rate_monotonic_period period_2 40 TIMEOUT break Perform first set of actions between clock ticks O and 39 of every 100 ticks if rtems rate monotonic period period 2 30 TIMEOUT break Perform second set of actions between clock 40 and 69 of every 100 ticks THEN Check to make sure we didn t miss the period 2 period if rtems_rate_monotonic_period period 2 STATUS TIMEOUT break void rtems_rate_monotonic_cancel period_2 missed peri
379. ults to 10000 10 milliseconds is the number of clock ticks for a timeslice When using the rtems confdefs h mechanism for configuring an RTEMS applica tion the value for this field corresponds to the setting of the macro CONFIGURE TICKS PER TIMESLICE is the address of the optional user provided routine which is used as the system s IDLE task If this field is not NULL then the RTEMS default IDLE task is not used This field may be NULL to indicate that the default IDLE is to be used When using the rtems confdefs h mechanism for configuring an RTEMS applica tion the value for this field corresponds to the setting of the macro CONFIGURE IDLE TASK BODY is the size of the RTEMS idle task stack in bytes If this number is less than the configured minimum stack size then the idle task s stack will be set to the minimum When using the rtems confdefs h mechanism for configuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE IDLE TASK STACK SIZE is the size of the RTEMS interrupt stack in bytes If this number is less than configured minimum stack size then the interrupt stack will be set to the minimum When using the rtems confdefs h mechanism for configuring an RTEMS application the value for this field corresponds to the setting of the macro CONFIGURE INTERRUPT STACK SIZE may point to a user provided routine to allocate task stacks The default is to allocate task stack
380. umber is the data type used to manage device minor num bers rtems_double is the RTEMS data type that corresponds to double precision floating point on the target hardware This type is deprecated Use double instead rtems_event_set is the data type used to manage and manipulate RTEMS event sets with the Event Manager rtems_extension is the return type for RTEMS user extension routines rtems_fatal_extension is the entry point for a fatal error user extension handler routine rtems id is the data type used to manage and manipulate RTEMS object IDs rtems interrupt frame is the data structure that defines the format of the inter rupt stack frame as it appears to a user ISR This data structure may not be defined on all ports 20 RTEMS C User s Guide rtems_interrupt_level is the data structure used with the rtems_interrupt_ disable rtems_interrupt_enable and rtems_interrupt_flash routines This data type is CPU dependent and usually corresponds to the contents of the processor register containing the interrupt mask level rtems_interval is the data type used to manage and manipulate time intervals Intervals are non negative integers used to measure the length of time in clock ticks rtems_isr is the return type of a function implementing an RTEMS ISR rtems_isr_entry is the address of the entry point to an RTEMS ISR It is equivalent to the entry point of the function implementing the ISR rtems_mp_packet_classes is t
381. upported microprocessor and sufficient memory for both RTEMS and the real time application Board dependent components such as clocks interrupt controllers or I O devices can be easily integrated with RTEMS The customiza tion and extensibility features allow RTEMS to efficiently support as many environments as possible 1 7 Portability The issue of portability was the major factor in the creation of RTEMS Since RTEMS is designed to isolate the hardware dependencies in the specific board support packages the real time application should be easily ported to any other processor The use of RTEMS allows the development of real time applications which can be completely independent of a particular microprocessor architecture 1 8 Memory Requirements Since memory is a critical resource in many real time embedded systems RTEMS was specifically designed to automatically leave out all services that are not required from the Chapter 1 Overview 9 run time environment Features such as networking various fileystems and many other features are completely optional This allows the application designer the flexibility to tailor RTEMS to most efficiently meet system requirements while still satisfying even the most stringent memory constraints As a result the size of the RTEMS executive is application dependent RTEMS requires RAM to manage each instance of an RTEMS object that is created Thus the more RTEMS objects an application needs the mor
382. upported on remote tasks 50 RTEMS C User s Guide 5 4 10 TASK_SET_PRIORITY Set task priority CALLING SEQUENCE rtems status code rtems task set priority rtems id id rtems task priority new priority rtems task priority old priority J DIRECTIVE STATUS CODES RTEMS_SUCCESSFUL task priority set successfully RTEMS_INVALID_ID invalid task id RTEMS_INVALID_ADDRESS invalid return argument pointer RTEMS_INVALID_PRIORITY invalid task priority DESCRIPTION This directive manipulates the priority of the task specified by id An id of RTEMS_SELF is used to indicate the calling task When new priority is not equal to RTEMS_CURRENT_ PRIORITY the specified task s previous priority is returned in old priority When new priority is RTEMS CURRENT PRIORITY the specified task s current priority is returned in old priority Valid priorities range from a high of 1 to a low of 255 NOTES The calling task may be preempted if its preemption mode is enabled and it lowers its own priority or raises another task s priority Setting the priority of a global task which does not reside on the local node will generate a request to the remote node to change the priority of the specified task If the task specified by id is currently holding any binary semaphores which use the priority inheritance algorithm then the task s priority cannot be lowered immediately If the task s priority were lowered immediately then priority inversion r
383. urred The directive is usually called from the timer interrupt ISR of the local processor This directive maintains the system date and time decrements timers for delayed tasks timeouts rate monotonic periods and implements timeslicing NOTES This directive is typically called from an ISR The microseconds_per_tick and ticks_per_timeslice parameters in the Configuration Table contain the number of microseconds per tick and number of ticks per timeslice re spectively Chapter 8 Timer Manager 85 8 Timer Manager 8 1 Introduction The timer manager provides support for timer facilities The directives provided by the timer manager are e rtems_timer_create Create a timer e rtems_timer_ident Get ID of a timer e rtems_timer_cancel Cancel a timer e rtems_timer_delete Delete a timer e rtems_timer_fire_after Fire timer after interval e rtems_timer_fire_when Fire timer when specified e rtems_timer_initiate_server Initiate server for task based timers e rtems_timer_server_fire_after Fire task based timer after interval e rtems_timer_server_fire_when Fire task based timer when specified e rtems_timer_reset Reset an interval timer 8 2 Background 8 2 1 Required Support A clock tick is required to support the functionality provided by this manager 8 2 2 Timers A timer is an RTEMS object which allows the application to schedule operations to occur at specific times in the future User supplied timer ser
384. use the running task to be preempted 214 RTEMS C User s Guide 19 4 8 RATE_MONOTONIC_RESET_STATISTICS Reset statistics for a period CALLING SEQUENCE rtems status code rtems_rate_monotonic_reset_statistics rtems id id 25 DIRECTIVE STATUS CODES RTEMS SUCCESSFUL period initiated successfully RTEMS INVALID ID invalid rate monotonic period id DESCRIPTION This directive resets the statistics information associated with this rate monotonic period instance NOTES This directive will not cause the running task to be preempted Chapter 19 Rate Monotonic Manager 215 19 4 9 RATE MONOTONIC RESET ALL STATISTICS Reset statistics for all periods CALLING SEQUENCE void rtems rate monotonic reset all statistics void DIRECTIVE STATUS CODES NONE DESCRIPTION This directive resets the statistics information associated with all rate monotonic period instances NOTES This directive will not cause the running task to be preempted 216 RTEMS C User s Guide 19 4 10 RATE MONOTONIC REPORT STATISTICS Print period statistics report CALLING SEQUENCE void rtems rate monotonic report statistics void DIRECTIVE STATUS CODES NONE DESCRIPTION This directive prints a report on all active periods which have executed at least one period The following is an example of the output generated by this directive ID OWNER PERIODS MISSED CPU TIME WALL TIME MIN MAX AVG MIN MAX AVG 0x42010001 TA1 502 0
385. values are specifically designed to be mutually exclusive therefore bitwise OR and addition operations are equivalent as long as each attribute appears exactly once in the component list An attribute listed as a default is not required to appear in the attribute list although it is a good programming practice to specify default attributes If all defaults are desired the attribute RTEMS_DEFAULT_ATTRIBUTES should be specified on this call This example demonstrates the attribute_set parameter needed to create a barrier with the automatic release policy The attribute_set parameter passed to the rtems_barrier_ create directive will be RTEMS_BARRIER_AUTOMATIC_RELEASE In this case the user must also specify the maximum waiters parameter 20 3 Operations 20 3 1 Creating a Barrier The rtems barrier create directive creates a barrier with a user specified name and the desired attributes RTEMS allocates a Barrier Control Block BCB from the BCB free list This data structure is used by RTEMS to manage the newly created barrier Also a unique barrier ID is generated and returned to the calling task 20 3 2 Obtaining Barrier IDs When a barrier is created RT EMS generates a unique barrier ID and assigns it to the created barrier until it is deleted The barrier ID may be obtained by either of two methods First as the result of an invocation of the rtems barrier create directive the barrier ID is stored in a user provided location Second th
386. verload without knowing exactly when any given task will execute by applying proven schedulability analysis rules 19 2 5 1 Assumptions The schedulability analysis rules for RMS were developed based on the following assump tions e The requests for all tasks for which hard deadlines exist are periodic with a constant interval between requests e Each task must complete before the next request for it occurs e The tasks are independent in that a task does not depend on the initiation or completion of requests for other tasks e The execution time for each task without preemption or interruption is constant and does not vary e Any non periodic tasks in the system are special These tasks displace periodic tasks while executing and do not have hard critical deadlines Once the basic schedulability analysis is understood some of the above assumptions can be relaxed and the side effects accounted for 19 2 5 2 Processor Utilization Rule The Processor Utilization Rule requires that processor utilization be calculated based upon the period and execution time of each task The fraction of processor time spent executing task index is Time index Period index The processor utilization can be calculated as follows Utilization 0 for index 1 to maximum_tasks Utilization Utilization Time index Period index To ensure schedulability even under transient overload the processor utilization must adhere to the following rul
387. vice routines are invoked by either the rtems_clock_tick directive or a special Timer Server task when the timer fires Timer ser vice routines may perform any operations or directives which normally would be performed by the application code which invoked the rtems_clock_tick directive The timer can be used to implement watchdog routines which only fire to denote that an application error has occurred The timer is reset at specific points in the application to ensure that the watchdog does not fire Thus if the application does not reset the watchdog timer then the timer service routine will fire to indicate that the application has failed to reach a reset point This use of a timer is sometimes referred to as a keep alive or a deadman timer 8 2 3 Timer Server The Timer Server task is responsible for executing the timer service routines associated with all task based timers This task executes at a priority higher than any RTEMS application task and is created non preemptible and thus can be viewed logically as the lowest priority interrupt By providing a mechanism where timer service routines execute in task rather than interrupt space the application is allowed a bit more flexibility in what operations a timer service 86 RTEMS C User s Guide routine can perform For example the Timer Server can be configured to have a floating point context in which case it would be safe to perform floating point operations from a task base
388. void rtems chain prepend rtems chain control the chain rtems chain node the node 2s RETURNS Returns nothing DESCRIPTION This routine prepends a node to the front of the chain NOTES Interrupts are disabled during the prepend to ensure the atomicity of the operation Chapter 28 Chains 331 28 4 19 Prepend a Node unprotected CALLING SEQUENCE void rtems_chain_prepend_unprotected rtems_chain_control the_chain rtems_chain_node the_node 2s RETURNS Returns nothing DESCRIPTION This routine prepends a node to the front of the chain NOTES Interrupts are NOT disabled during the prepend to ensure the atomicity of the operation Chapter 29 Directive Status Codes 333 29 Directive Status Codes RTEMS_SUCCESSFUL successful completion RTEMS_TASK_EXITTED returned from a task RTEMS_MP_NOT_CONFIGURED multiprocessing not configured RTEMS_INVALID_NAME invalid object name RTEMS_INVALID_ID invalid object id RTEMS_TOO_MANY too many RTEMS_TIMEOUT timed out waiting RTEMS_OBJECT_WAS_DELETED object was deleted while waiting RTEMS INVALID SIZE invalid specified size RTEMS INVALID ADDRESS invalid address specified RTEMS INVALID NUMBER number was invalid RTEMS NOT DEFINED item not initialized RTEMS RESOURCE IN USE resources outstanding RTEMS UNSATISFIED request not satisfied RTEMS INCORRECT STATE task is in wrong state RTEMS ALREADY SUSPENDED task already i
389. waiters 1 tasks waiting at the barrier When the maximum waiters task invokes the rtems barrier wait directive the previous maximum waiters 1 tasks are automatically released and the caller returns In contrast when the RTEMS BARRIER MANUAL RELEASE attribute is specified there is no limit on the number of tasks that will block at the barrier Only when the rtems barrier release directive is invoked are the tasks waiting at the barrier unblocked NOTES This directive will not cause the calling task to be preempted The following barrier attribute constants are defined by RTEMS e RTEMS BARRIER AUTOMATIC RELEASE automatically release the barrier when the configured number of tasks are blocked e RTEMS BARRIER MANUAL RELEASE only release the barrier when the application invokes the rtems barrier release directive default Chapter 20 Barrier Manager 221 20 4 2 BARRIER IDENT Get ID of a barrier CALLING SEQUENCE rtems status code rtems barrier ident rtems name name rtems id id DIRECTIVE STATUS CODES RTEMS SUCCESSFUL barrier identified successfully RTEMS INVALID NAME barrier name not found RTEMS INVALID NODE invalid node id DESCRIPTION This directive obtains the barrier id associated with the barrier name If the barrier name is not unique then the barrier id will match one of the barriers with that name However this barrier id is not guaranteed to correspond to the desired barrier
390. y coupled system is a multiprocessor configuration in which the processors commu nicate solely via shared global memory The MPCI can simply place the RTEMS packets in the shared memory space The two primary considerations when designing an MPCI for a tightly coupled system are data consistency and informing another node of a packet The data consistency problem may be solved using atomic test and set operations to provide a lock in the shared memory It is important to minimize the length of time any particular processor locks a shared data structure The problem of informing another node of a packet can be addressed using one of two techniques The first technique is to use an interprocessor interrupt capability to cause an interrupt on the receiving node This technique requires that special support hardware be provided by either the processor itself or the target platform The second technique is to have a node poll for arrival of packets The drawback to this technique is the overhead associated with polling 21 5 2 Loosely Coupled Systems A loosely coupled system is a multiprocessor configuration in which the processors com municate via some type of communications link which is not shared global memory The MPCI sends the RTEMS packets across the communications link to the destination node The characteristics of the communications link vary widely and have a significant impact on the MPCI layer For example the bandwidth of the communi
391. y extend the CPU instruction set to support efficient multitasking By causing tasks to travel through well defined state transitions system calls permit an application to demand switch between tasks in response to real time events By proper grouping of responses to stimuli into separate tasks a system can now asyn chronously switch between independent streams of execution directly responding to ex ternal stimuli as they occur This allows the system design to meet critical performance specifications which are typically measured by guaranteed response time and transaction throughput The multiprocessor extensions of RTEMS provide the features necessary to manage the extra requirements introduced by a system distributed across several proces sors It removes the physical barriers of processor boundaries from the world of the system designer enabling more critical aspects of the system to receive the required attention Such a system based on an efficient real time multiprocessor executive is a more realistic model of the outside world or environment for which it is designed As a result the system will always be more logical efficient and reliable By using the directives provided by RTEMS the real time applications developer is freed from the problem of controlling and synchronizing multiple tasks and processors In addi tion one need not develop test debug and document routines to manage memory pass messages or provide mutual exclus
392. y point must be invoked The information passed by the application to RTEMS is then passed to the correct device driver entry point RTEMS will invoke each device driver entry point assuming it is compatible with the following prototype rtems_device_driver io_entry rtems_device_major_number major rtems_device_minor_number minor void argument block 33 The format and contents of the parameter block are device driver and entry point dependent It is recommended that a device driver avoid generating error codes which conflict with those used by application components A common technique used to generate driver specific error codes is to make the most significant part of the status indicate a driver specific code 16 2 7 Device Driver Initialization RTEMS automatically initializes all device drivers when multitasking is initiated via the rtems initialize executive directive RTEMS initializes the device drivers by invoking each device driver initialization entry point with the following parameters major the major device number for this device driver minor Zero argument block will point to the Configuration Table The returned status will be ignored by RTEMS If the driver cannot successfully initialize the device then it should invoke the fatal error occurred directive 16 3 Operations 16 3 1 Register and Lookup Name The rtems io register directive associates a name with the specified device i e ma jor minor number pa
393. ystem 241 23 1 Introduction ii be Sader RR RIA P RE QUEE 241 23 2 Automatic Generation of System Configuration 241 23 2 1 Library Support Definitions 00000 242 23 2 2 Basic System Information 0 00 2 e eee eee eee 243 23 2 3 Idle Task Configuration 0 00 c eee eee eee 244 23 2 4 Device Driver Table 0 00 cece eee eee ee 245 23 2 5 Multiprocessing Configuration 000 eee 246 23 2 6 Classic API Configuration 0c eee eee 246 23 2 7 Classic API Initialization Tasks Table Configuration 247 23 2 8 POSIX API Configuration 0 2 cece eee 248 23 2 9 POSIX Initialization Threads Table Configuration 248 23 2 10 ITRON API Configuration 20 cee eee 249 23 2 11 ITRON Initialization Task Table Configuration 249 23 2 12 Ada Tasks dacamactneiiieeeeesbecodeaeiaenneet 250 23 8 Configuration Table ci ssa sese eben 250 23 4 RTEMS API Configuration Table ssessseeeeeese 254 23 5 POSIX API Configuration Table ssseeesssesse 257 23 6 CPU Dependent Information Table 0 000 eee 259 23 7 Initialization Task Table 0 cee eee eee 259 23 8 Driver Address Table 0 cece cece eee ees 260 23 9 User Extensions Table 20 c cece eee eens 261 23 10 Multiprocessor Configuration Table
394. zation code are highly processor and target dependent the logical functionality of these actions are similar across a variety of processors and target platforms Normally the BSP and some of the application initialization is intertwined in the RTEMS initialization sequence controlled by the shared function boot_card The reset application initialization code is executed first when the processor is reset All of the hardware must be initialized to a quiescent state by this software before initializing RTEMS When in quiescent state devices do not generate any interrupts or require any servicing by the application Some of the hardware components may be initialized in this code as well as any application initialization that does not involve calls to RTEMS directives The processor s Interrupt Vector Table which will be used by the application may need to be set to the required value by the reset application initialization code Because interrupts are enabled automatically by RTEMS as part of the context switch to the first task the Interrupt Vector Table MUST be set before this directive is invoked to ensure correct interrupt vectoring The processor s Interrupt Vector Table must be accessible by RTEMS as it will be modified by the when installing user Interrupt Service Routines ISRs On some CPUs RTEMS installs it s own Interrupt Vector Table as part of initialization and thus these requirements are met automatically The reset code which i

RTEMS C User's Guide - RTEMS Documentation

Contents

Download Pdf Manuals

Related Search

Related Contents