source: rtems/doc/user/smp.t @ d1f2f22

4.11
Last change on this file since d1f2f22 was d1f2f22, checked in by Sebastian Huber <sebastian.huber@…>, on Apr 16, 2014 at 1:59:21 PM

doc: rtems_scheduler_get_processor_set()

  • Property mode set to 100644
File size: 14.5 KB
Line 
1@c
2@c  COPYRIGHT (c) 2014.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6
7@chapter Symmetric Multiprocessing Services
8
9@section Introduction
10
11This chapter describes the services related to Symmetric Multiprocessing
12provided by RTEMS.
13
14The application level services currently provided are:
15
16@itemize @bullet
17@item @code{rtems_get_processor_count} - Get processor count
18@item @code{rtems_get_current_processor} - Get current processor index
19@item @code{rtems_scheduler_ident} - Get ID of a scheduler
20@item @code{rtems_scheduler_get_processor_set} - Get processor set of a scheduler
21@item @code{rtems_task_get_affinity} - Get task processor affinity
22@item @code{rtems_task_set_affinity} - Set task processor affinity
23@end itemize
24
25@c
26@c
27@c
28@section Background
29
30@subsection Uniprocessor versus SMP Parallelism
31
32Uniprocessor systems have long been used in embedded systems. In this hardware
33model, there are some system execution characteristics which have long been
34taken for granted:
35
36@itemize @bullet
37@item one task executes at a time
38@item hardware events result in interrupts
39@end itemize
40
41There is no true parallelism. Even when interrupts appear to occur
42at the same time, they are processed in largely a serial fashion.
43This is true even when the interupt service routines are allowed to
44nest.  From a tasking viewpoint,  it is the responsibility of the real-time
45operatimg system to simulate parallelism by switching between tasks.
46These task switches occur in response to hardware interrupt events and explicit
47application events such as blocking for a resource or delaying.
48
49With symmetric multiprocessing, the presence of multiple processors
50allows for true concurrency and provides for cost-effective performance
51improvements. Uniprocessors tend to increase performance by increasing
52clock speed and complexity. This tends to lead to hot, power hungry
53microprocessors which are poorly suited for many embedded applications.
54
55The true concurrency is in sharp contrast to the single task and
56interrupt model of uniprocessor systems. This results in a fundamental
57change to uniprocessor system characteristics listed above. Developers
58are faced with a different set of characteristics which, in turn, break
59some existing assumptions and result in new challenges. In an SMP system
60with N processors, these are the new execution characteristics.
61
62@itemize @bullet
63@item N tasks execute in parallel
64@item hardware events result in interrupts
65@end itemize
66
67There is true parallelism with a task executing on each processor and
68the possibility of interrupts occurring on each processor. Thus in contrast
69to their being one task and one interrupt to consider on a uniprocessor,
70there are N tasks and potentially N simultaneous interrupts to consider
71on an SMP system.
72
73This increase in hardware complexity and presence of true parallelism
74results in the application developer needing to be even more cautious
75about mutual exclusion and shared data access than in a uniprocessor
76embedded system. Race conditions that never or rarely happened when an
77application executed on a uniprocessor system, become much more likely
78due to multiple threads executing in parallel. On a uniprocessor system,
79these race conditions would only happen when a task switch occurred at
80just the wrong moment. Now there are N-1 tasks executing in parallel
81all the time and this results in many more opportunities for small
82windows in critical sections to be hit.
83
84@subsection Task Affinity
85
86@cindex task affinity
87@cindex thread affinity
88
89RTEMS provides services to manipulate the affinity of a task. Affinity
90is used to specify the subset of processors in an SMP system on which
91a particular task can execute.
92
93By default, tasks have an affinity which allows them to execute on any
94available processor.
95
96Task affinity is a possible feature to be supported by SMP-aware
97schedulers. However, only a subset of the available schedulers support
98affinity. Although the behavior is scheduler specific, if the scheduler
99does not support affinity, it is likely to ignore all attempts to set
100affinity.
101
102@subsection Critical Section Techniques and SMP
103
104As discussed earlier, SMP systems have opportunities for true parallelism
105which was not possible on uniprocessor systems. Consequently, multiple
106techniques that provided adequate critical sections on uniprocessor
107systems are unsafe on SMP systems. In this section, some of these
108unsafe techniques will be discussed.
109
110In general, applications must use proper operating system provided mutual
111exclusion mechanisms to ensure correct behavior. This primarily means
112the use of binary semaphores or mutexes to implement critical sections.
113
114@subsubsection Disable Interrupts
115
116Again on a uniprocessor system, there is only a single processor which
117logically executes a single task and takes interrupts. On an SMP system,
118each processor may take an interrupt. When the application disables
119interrupts, it generally does so by altering a processor register to
120mask interrupts and later to re-enable them. On a uniprocessor system,
121changing this in the single processor is sufficient. However, on an SMP
122system, this register in @strong{ALL} processors must be changed. There
123are no comparable capabilities in an SMP system to disable all interrupts
124across all processors.
125
126@subsubsection Highest Priority Task Assumption
127
128On a uniprocessor system, it is safe to assume that when the highest
129priority task in an application executes, it will execute without being
130preempted until it voluntarily blocks. Interrupts may occur while it is
131executing, but there will be no context switch to another task unless
132the highest priority task voluntarily initiates it.
133
134Given the assumption that no other tasks will have their execution
135interleaved with the highest priority task, it is possible for this
136task to be constructed such that it does not need to acquire a binary
137semaphore or mutex for protected access to shared data.
138
139In an SMP system, it cannot be assumed there will never be a single task
140executing. It should be assumed that every processor is executing another
141application task. Further, those tasks will be ones which would not have
142been executed in a uniprocessor configuration and should be assumed to
143have data synchronization conflicts with what was formerly the highest
144priority task which executed without conflict.
145
146@subsubsection Disable Preemption
147
148On a uniprocessor system, disabling preemption in a task is very similar
149to making the highest priority task assumption. While preemption is
150disabled, no task context switches will occur unless the task initiates
151them voluntarily. And, just as with the highest priority task assumption,
152there are N-1 processors also running tasks. Thus the assumption that no
153other tasks will run while the task has preemption disabled is violated.
154
155@subsection Task Unique Data and SMP
156
157Per task variables are a service commonly provided by real-time operating
158systems for application use. They work by allowing the application
159to specify a location in memory (typically a @code{void *}) which is
160logically added to the context of a task. On each task switch, the
161location in memory is stored and each task can have a unique value in
162the same memory location. This memory location is directly accessed as a
163variable in a program.
164
165This works well in a uniprocessor environment because there is one task
166executing and one memory location containing a task-specific value. But
167it is fundamentally broken on an SMP system because there are always N
168tasks executing. With only one location in memory, N-1 tasks will not
169have the correct value.
170
171This paradigm for providing task unique data values is fundamentally
172broken on SMP systems.
173
174@subsubsection Classic API Per Task Variables
175
176The Classic API provides three directives to support per task variables. These are:
177
178@itemize @bullet
179@item @code{@value{DIRPREFIX}task_variable_add} - Associate per task variable
180@item @code{@value{DIRPREFIX}task_variable_get} - Obtain value of a a per task variable
181@item @code{@value{DIRPREFIX}task_variable_delete} - Remove per task variable
182@end itemize
183
184As task variables are unsafe for use on SMP systems, the use of these
185services should be eliminated in all software that is to be used in
186an SMP environment. It is recommended that the application developer
187consider the use of POSIX Keys or Thread Local Storage (TLS). POSIX Keys
188are not enabled in all RTEMS configurations.
189
190@b{STATUS}: As of March 2014, some support services in the
191@code{rtems/cpukit} use per task variables. When these uses are
192eliminated, the per task variable directives will be disabled when
193building RTEMS in SMP configuration.
194
195@c
196@c
197@c
198@section Operations
199
200@subsection Setting Affinity to a Single Processor
201
202In many embedded applications targeting SMP systems, it is common to lock individual tasks to specific cores. In this way, one can designate a core for I/O tasks, another for computation, etc.. The following illustrates the code sequence necessary to assign a task an affinity for processor zero (0).
203
204@example
205rtems_status_code sc;
206cpu_set_t         set;
207
208CPU_EMPTY( &set );
209CPU_SET( 0, &set );
210
211sc = rtems_task_set_affinity(rtems_task_self(), sizeof(set), &set);
212assert(sc == RTEMS_SUCCESSFUL);
213@end example
214
215It is important to note that the @code{cpu_set_t} is not validated until the
216@code{@value{DIRPREFIX}task_set_affinity} call is made. At that point,
217it is validated against the current system configuration.
218
219@c
220@c
221@c
222@section Directives
223
224This section details the symmetric multiprocessing services.  A subsection
225is dedicated to each of these services and describes the calling sequence,
226related constants, usage, and status codes.
227
228@c
229@c rtems_get_processor_count
230@c
231@page
232@subsection GET_PROCESSOR_COUNT - Get processor count
233
234@subheading CALLING SEQUENCE:
235
236@ifset is-C
237@example
238uint32_t rtems_get_processor_count(void);
239@end example
240@end ifset
241
242@ifset is-Ada
243@end ifset
244
245@subheading DIRECTIVE STATUS CODES:
246
247The count of processors in the system.
248
249@subheading DESCRIPTION:
250
251On uni-processor configurations a value of one will be returned.
252
253On SMP configurations this returns the value of a global variable set during
254system initialization to indicate the count of utilized processors.  The
255processor count depends on the physically or virtually available processors and
256application configuration.  The value will always be less than or equal to the
257maximum count of application configured processors.
258
259@subheading NOTES:
260
261None.
262
263@c
264@c rtems_get_current_processor
265@c
266@page
267@subsection GET_CURRENT_PROCESSOR - Get current processor index
268
269@subheading CALLING SEQUENCE:
270
271@ifset is-C
272@example
273uint32_t rtems_get_current_processor(void);
274@end example
275@end ifset
276
277@ifset is-Ada
278@end ifset
279
280@subheading DIRECTIVE STATUS CODES:
281
282The index of the current processor.
283
284@subheading DESCRIPTION:
285
286On uni-processor configurations a value of zero will be returned.
287
288On SMP configurations an architecture specific method is used to obtain the
289index of the current processor in the system.  The set of processor indices is
290the range of integers starting with zero up to the processor count minus one.
291
292Outside of sections with disabled thread dispatching the current processor
293index may change after every instruction since the thread may migrate from one
294processor to another.  Sections with disabled interrupts are sections with
295thread dispatching disabled.
296
297@subheading NOTES:
298
299None.
300
301@c
302@c rtems_scheduler_ident
303@c
304@page
305@subsection SCHEDULER_IDENT - Get ID of a scheduler
306
307@subheading CALLING SEQUENCE:
308
309@ifset is-C
310@example
311rtems_status_code rtems_scheduler_ident(
312  rtems_name  name,
313  rtems_id   *id
314);
315@end example
316@end ifset
317
318@ifset is-Ada
319@end ifset
320
321@subheading DIRECTIVE STATUS CODES:
322
323@code{@value{RPREFIX}SUCCESSFUL} - successful operation@*
324@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
325@code{@value{RPREFIX}INVALID_NAME} - invalid scheduler name
326
327@subheading DESCRIPTION:
328
329Identifies a scheduler by its name.  The scheduler name is determined by the
330scheduler configuration.  @xref{Configuring a System Configuring
331Clustered/Partitioned Schedulers}.
332
333@subheading NOTES:
334
335None.
336
337@c
338@c rtems_scheduler_get_processor_set
339@c
340@page
341@subsection SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler
342
343@subheading CALLING SEQUENCE:
344
345@ifset is-C
346@example
347rtems_status_code rtems_scheduler_get_processor_set(
348  rtems_id   scheduler_id,
349  size_t     cpusetsize,
350  cpu_set_t *cpuset
351);
352@end example
353@end ifset
354
355@ifset is-Ada
356@end ifset
357
358@subheading DIRECTIVE STATUS CODES:
359
360@code{@value{RPREFIX}SUCCESSFUL} - successful operation@*
361@code{@value{RPREFIX}INVALID_ADDRESS} - @code{cpuset} is NULL@*
362@code{@value{RPREFIX}INVALID_ID} - invalid scheduler id@*
363@code{@value{RPREFIX}INVALID_NUMBER} - the affinity set buffer is too small for
364set of processors owned by the scheduler
365
366@subheading DESCRIPTION:
367
368Returns the processor set owned by the scheduler in @code{cpuset}.  A set bit
369in the processor set means that this processor is owned by the scheduler and a
370cleared bit means the opposite.
371
372@subheading NOTES:
373
374None.
375
376@c
377@c rtems_task_get_affinity
378@c
379@page
380@subsection TASK_GET_AFFINITY - Get task processor affinity
381
382@subheading CALLING SEQUENCE:
383
384@ifset is-C
385@example
386rtems_status_code rtems_task_get_affinity(
387  rtems_id   id,
388  size_t     cpusetsize,
389  cpu_set_t *cpuset
390);
391@end example
392@end ifset
393
394@ifset is-Ada
395@end ifset
396
397@subheading DIRECTIVE STATUS CODES:
398
399@code{@value{RPREFIX}SUCCESSFUL} - successful operation@*
400@code{@value{RPREFIX}INVALID_ADDRESS} - @code{cpuset} is NULL@*
401@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
402@code{@value{RPREFIX}INVALID_NUMBER} - the affinity set buffer is too small for
403the current processor affinity set of the task
404
405@subheading DESCRIPTION:
406
407Returns the current processor affinity set of the task in @code{cpuset}.  A set
408bit in the affinity set means that the task can execute on this processor and a
409cleared bit means the opposite.
410
411@subheading NOTES:
412
413None.
414
415@c
416@c rtems_task_set_affinity
417@c
418@page
419@subsection TASK_SET_AFFINITY - Set task processor affinity
420
421@subheading CALLING SEQUENCE:
422
423@ifset is-C
424@example
425rtems_status_code rtems_task_set_affinity(
426  rtems_id         id,
427  size_t           cpusetsize,
428  const cpu_set_t *cpuset
429);
430@end example
431@end ifset
432
433@ifset is-Ada
434@end ifset
435
436@subheading DIRECTIVE STATUS CODES:
437
438@code{@value{RPREFIX}SUCCESSFUL} - successful operation@*
439@code{@value{RPREFIX}INVALID_ADDRESS} - @code{cpuset} is NULL@*
440@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
441@code{@value{RPREFIX}INVALID_NUMBER} - invalid processor affinity set
442
443@subheading DESCRIPTION:
444
445Sets the processor affinity set for the task specified by @code{cpuset}.  A set
446bit in the affinity set means that the task can execute on this processor and a
447cleared bit means the opposite.
448
449@subheading NOTES:
450
451None.
Note: See TracBrowser for help on using the repository browser.