source: rtems/cpukit/score/include/rtems/score/scheduler.h @ 05ca53d

5
Last change on this file since 05ca53d was 05ca53d, checked in by Sebastian Huber <sebastian.huber@…>, on 10/31/16 at 12:08:33

rtems: Add scheduler processor add/remove

Update #2797.

  • Property mode set to 100644
File size: 14.1 KB
Line 
1/**
2 *  @file  rtems/score/scheduler.h
3 *
4 *  @brief Constants and Structures Associated with the Scheduler
5 *
6 *  This include file contains all the constants and structures associated
7 *  with the scheduler.
8 */
9
10/*
11 *  Copyright (C) 2010 Gedare Bloom.
12 *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
13 *
14 *  The license and distribution terms for this file may be
15 *  found in the file LICENSE in this distribution or at
16 *  http://www.rtems.org/license/LICENSE.
17 */
18
19#ifndef _RTEMS_SCORE_SCHEDULER_H
20#define _RTEMS_SCORE_SCHEDULER_H
21
22#include <rtems/score/thread.h>
23#if defined(__RTEMS_HAVE_SYS_CPUSET_H__) && defined(RTEMS_SMP)
24  #include <sys/cpuset.h>
25#endif
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31struct Per_CPU_Control;
32
33/**
34 *  @defgroup ScoreScheduler Scheduler Handler
35 *
36 *  @ingroup Score
37 *
38 *  This handler encapsulates functionality related to managing sets of threads
39 *  that are ready for execution.
40 */
41/**@{*/
42
43typedef struct Scheduler_Control Scheduler_Control;
44
45#if defined(RTEMS_SMP)
46  typedef bool Scheduler_Void_or_bool;
47
48  #define SCHEDULER_RETURN_VOID_OR_BOOL return false
49#else
50  typedef void Scheduler_Void_or_bool;
51
52  #define SCHEDULER_RETURN_VOID_OR_BOOL return
53#endif
54
55/**
56 * @brief The scheduler operations.
57 */
58typedef struct {
59  /** @see _Scheduler_Handler_initialization() */
60  void ( *initialize )( const Scheduler_Control * );
61
62  /** @see _Scheduler_Schedule() */
63  void ( *schedule )( const Scheduler_Control *, Thread_Control *);
64
65  /** @see _Scheduler_Yield() */
66  Scheduler_Void_or_bool ( *yield )(
67    const Scheduler_Control *,
68    Thread_Control *,
69    Scheduler_Node *
70  );
71
72  /** @see _Scheduler_Block() */
73  void ( *block )(
74    const Scheduler_Control *,
75    Thread_Control *,
76    Scheduler_Node *
77  );
78
79  /** @see _Scheduler_Unblock() */
80  Scheduler_Void_or_bool ( *unblock )(
81    const Scheduler_Control *,
82    Thread_Control *,
83    Scheduler_Node *
84  );
85
86  /** @see _Scheduler_Update_priority() */
87  void ( *update_priority )(
88    const Scheduler_Control *,
89    Thread_Control *,
90    Scheduler_Node *
91  );
92
93  /** @see _Scheduler_Map_priority() */
94  Priority_Control ( *map_priority )(
95    const Scheduler_Control *,
96    Priority_Control
97  );
98
99  /** @see _Scheduler_Unmap_priority() */
100  Priority_Control ( *unmap_priority )(
101    const Scheduler_Control *,
102    Priority_Control
103  );
104
105#if defined(RTEMS_SMP)
106  /**
107   * @brief Ask for help operation.
108   *
109   * @param[in] scheduler The scheduler instance to ask for help.
110   * @param[in] the_thread The thread needing help.
111   * @param[in] node The scheduler node.
112   *
113   * @retval true Ask for help was successful.
114   * @retval false Otherwise.
115   */
116  bool ( *ask_for_help )(
117    const Scheduler_Control *scheduler,
118    Thread_Control          *the_thread,
119    Scheduler_Node          *node
120  );
121
122  /**
123   * @brief Reconsider help operation.
124   *
125   * @param[in] scheduler The scheduler instance to reconsider the help
126   *   request.
127   * @param[in] the_thread The thread reconsidering a help request.
128   * @param[in] node The scheduler node.
129   */
130  void ( *reconsider_help_request )(
131    const Scheduler_Control *scheduler,
132    Thread_Control          *the_thread,
133    Scheduler_Node          *node
134  );
135
136  /**
137   * @brief Withdraw node operation.
138   *
139   * @param[in] scheduler The scheduler instance to withdraw the node.
140   * @param[in] the_thread The thread using the node.
141   * @param[in] node The scheduler node to withdraw.
142   * @param[in] next_state The next thread scheduler state in case the node is
143   *   scheduled.
144   */
145  void ( *withdraw_node )(
146    const Scheduler_Control *scheduler,
147    Thread_Control          *the_thread,
148    Scheduler_Node          *node,
149    Thread_Scheduler_state   next_state
150  );
151
152  /**
153   * @brief Add processor operation.
154   *
155   * @param[in] scheduler The scheduler instance to add the processor.
156   * @param[in] idle The idle thread of the processor to add.
157   */
158  void ( *add_processor )(
159    const Scheduler_Control *scheduler,
160    Thread_Control          *idle
161  );
162
163  /**
164   * @brief Remove processor operation.
165   *
166   * @param[in] scheduler The scheduler instance to remove the processor.
167   * @param[in] cpu The processor to remove.
168   *
169   * @return The idle thread of the removed processor.
170   */
171  Thread_Control *( *remove_processor )(
172    const Scheduler_Control *scheduler,
173    struct Per_CPU_Control  *cpu
174  );
175#endif
176
177  /** @see _Scheduler_Node_initialize() */
178  void ( *node_initialize )(
179    const Scheduler_Control *,
180    Scheduler_Node *,
181    Thread_Control *,
182    Priority_Control
183  );
184
185  /** @see _Scheduler_Node_destroy() */
186  void ( *node_destroy )( const Scheduler_Control *, Scheduler_Node * );
187
188  /** @see _Scheduler_Release_job() */
189  void ( *release_job ) (
190    const Scheduler_Control *,
191    Thread_Control *,
192    Priority_Node *,
193    uint64_t,
194    Thread_queue_Context *
195  );
196
197  /** @see _Scheduler_Cancel_job() */
198  void ( *cancel_job ) (
199    const Scheduler_Control *,
200    Thread_Control *,
201    Priority_Node *,
202    Thread_queue_Context *
203  );
204
205  /** @see _Scheduler_Tick() */
206  void ( *tick )( const Scheduler_Control *, Thread_Control * );
207
208  /** @see _Scheduler_Start_idle() */
209  void ( *start_idle )(
210    const Scheduler_Control *,
211    Thread_Control *,
212    struct Per_CPU_Control *
213  );
214
215#if defined(__RTEMS_HAVE_SYS_CPUSET_H__) && defined(RTEMS_SMP)
216  /** @see _Scheduler_Get_affinity() */
217  bool ( *get_affinity )(
218    const Scheduler_Control *,
219    Thread_Control *,
220    size_t,
221    cpu_set_t *
222  );
223 
224  /** @see _Scheduler_Set_affinity() */
225  bool ( *set_affinity )(
226    const Scheduler_Control *,
227    Thread_Control *,
228    size_t,
229    const cpu_set_t *
230  );
231#endif
232} Scheduler_Operations;
233
234/**
235 * @brief Scheduler context.
236 *
237 * The scheduler context of a particular scheduler implementation must place
238 * this structure at the begin of its context structure.
239 */
240typedef struct Scheduler_Context {
241  /**
242   * @brief Lock to protect this scheduler instance.
243   */
244  ISR_LOCK_MEMBER( Lock )
245
246#if defined(RTEMS_SMP)
247  /**
248   * @brief Count of processors owned by this scheduler instance.
249   */
250  uint32_t processor_count;
251#endif
252} Scheduler_Context;
253
254/**
255 * @brief Scheduler control.
256 */
257struct Scheduler_Control {
258  /**
259   * @brief Reference to a statically allocated scheduler context.
260   */
261  Scheduler_Context *context;
262
263  /**
264   * @brief The scheduler operations.
265   */
266  Scheduler_Operations Operations;
267
268  /**
269   * @brief The maximum priority value of this scheduler.
270   *
271   * It defines the lowest (least important) thread priority for this
272   * scheduler.  For example the idle threads have this priority.
273   */
274  Priority_Control maximum_priority;
275
276  /**
277   * @brief The scheduler name.
278   */
279  uint32_t name;
280};
281
282/**
283 * @brief Registered schedulers.
284 *
285 * Application provided via <rtems/confdefs.h>.
286 *
287 * @see _Scheduler_Count.
288 */
289extern const Scheduler_Control _Scheduler_Table[];
290
291/**
292 * @brief Count of registered schedulers.
293 *
294 * Application provided via <rtems/confdefs.h> on SMP configurations.
295 *
296 * It is very important that this is a compile-time constant on uni-processor
297 * configurations (in this case RTEMS_SMP is not defined) so that the compiler
298 * can optimize the some loops away
299 *
300 * @see _Scheduler_Table.
301 */
302#if defined(RTEMS_SMP)
303  extern const size_t _Scheduler_Count;
304#else
305  #define _Scheduler_Count ( (size_t) 1 )
306#endif
307
308#if defined(RTEMS_SMP)
309  /**
310   * @brief The scheduler assignment default attributes.
311   */
312  #define SCHEDULER_ASSIGN_DEFAULT UINT32_C(0x0)
313
314  /**
315   * @brief The presence of this processor is optional.
316   */
317  #define SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL SCHEDULER_ASSIGN_DEFAULT
318
319  /**
320   * @brief The presence of this processor is mandatory.
321   */
322  #define SCHEDULER_ASSIGN_PROCESSOR_MANDATORY UINT32_C(0x1)
323
324  /**
325   * @brief Scheduler assignment.
326   */
327  typedef struct {
328    /**
329     * @brief The scheduler for this processor.
330     */
331    const Scheduler_Control *scheduler;
332
333    /**
334     * @brief The scheduler assignment attributes.
335     *
336     * Use @ref SCHEDULER_ASSIGN_DEFAULT to select default attributes.
337     *
338     * The presence of a processor can be
339     * - @ref SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL, or
340     * - @ref SCHEDULER_ASSIGN_PROCESSOR_MANDATORY.
341     */
342    uint32_t attributes;
343  } Scheduler_Assignment;
344
345  /**
346   * @brief The scheduler assignments.
347   *
348   * The length of this array must be equal to the maximum processors.
349   *
350   * Application provided via <rtems/confdefs.h>.
351   *
352   * @see _Scheduler_Table and rtems_configuration_get_maximum_processors().
353   */
354  extern const Scheduler_Assignment _Scheduler_Initial_assignments[];
355#endif
356
357/**
358 * @brief Returns the thread priority.
359 *
360 * @param[in] scheduler Unused.
361 * @param[in] priority The thread priority.
362 *
363 * @return priority The thread priority.
364 */
365Priority_Control _Scheduler_default_Map_priority(
366  const Scheduler_Control *scheduler,
367  Priority_Control         priority
368);
369
370#define _Scheduler_default_Unmap_priority _Scheduler_default_Map_priority
371
372#if defined(RTEMS_SMP)
373  /**
374   * @brief Does nothing.
375   *
376   * @param[in] scheduler Unused.
377   * @param[in] the_thread Unused.
378   * @param[in] node Unused.
379   *
380   * @retval false Always.
381   */
382  bool _Scheduler_default_Ask_for_help(
383    const Scheduler_Control *scheduler,
384    Thread_Control          *the_thread,
385    Scheduler_Node          *node
386  );
387
388  /**
389   * @brief Does nothing.
390   *
391   * @param[in] scheduler Unused.
392   * @param[in] the_thread Unused.
393   * @param[in] node Unused.
394   */
395  void _Scheduler_default_Reconsider_help_request(
396    const Scheduler_Control *scheduler,
397    Thread_Control          *the_thread,
398    Scheduler_Node          *node
399  );
400
401  /**
402   * @brief Does nothing.
403   *
404   * @param[in] scheduler Unused.
405   * @param[in] the_thread Unused.
406   * @param[in] node Unused.
407   * @param[in] next_state Unused.
408   */
409  void _Scheduler_default_Withdraw_node(
410    const Scheduler_Control *scheduler,
411    Thread_Control          *the_thread,
412    Scheduler_Node          *node,
413    Thread_Scheduler_state   next_state
414  );
415
416  #define SCHEDULER_OPERATION_DEFAULT_ASK_FOR_HELP \
417    _Scheduler_default_Ask_for_help, \
418    _Scheduler_default_Reconsider_help_request, \
419    _Scheduler_default_Withdraw_node, \
420    NULL, \
421    NULL,
422#else
423  #define SCHEDULER_OPERATION_DEFAULT_ASK_FOR_HELP
424#endif
425
426/**
427 * @brief Does nothing.
428 *
429 * @param[in] scheduler Unused.
430 * @param[in] the_thread Unused.
431 */
432void _Scheduler_default_Schedule(
433  const Scheduler_Control *scheduler,
434  Thread_Control          *the_thread
435);
436
437/**
438 * @brief Performs the scheduler base node initialization.
439 *
440 * @param[in] scheduler Unused.
441 * @param[in] node The node to initialize.
442 * @param[in] the_thread Unused.
443 * @param[in] priority The thread priority.
444 */
445void _Scheduler_default_Node_initialize(
446  const Scheduler_Control *scheduler,
447  Scheduler_Node          *node,
448  Thread_Control          *the_thread,
449  Priority_Control         priority
450);
451
452/**
453 * @brief Does nothing.
454 *
455 * @param[in] scheduler Unused.
456 * @param[in] node Unused.
457 */
458void _Scheduler_default_Node_destroy(
459  const Scheduler_Control *scheduler,
460  Scheduler_Node          *node
461);
462
463/**
464 * @brief Does nothing.
465 *
466 * @param[in] scheduler Unused.
467 * @param[in] the_thread Unused.
468 * @param[in] priority_node Unused.
469 * @param[in] deadline Unused.
470 * @param[in] queue_context Unused.
471 *
472 * @retval NULL Always.
473 */
474void _Scheduler_default_Release_job(
475  const Scheduler_Control *scheduler,
476  Thread_Control          *the_thread,
477  Priority_Node           *priority_node,
478  uint64_t                 deadline,
479  Thread_queue_Context    *queue_context
480);
481
482/**
483 * @brief Does nothing.
484 *
485 * @param[in] scheduler Unused.
486 * @param[in] the_thread Unused.
487 * @param[in] priority_node Unused.
488 * @param[in] queue_context Unused.
489 *
490 * @retval NULL Always.
491 */
492void _Scheduler_default_Cancel_job(
493  const Scheduler_Control *scheduler,
494  Thread_Control          *the_thread,
495  Priority_Node           *priority_node,
496  Thread_queue_Context    *queue_context
497);
498
499/**
500 * @brief Performs tick operations depending on the CPU budget algorithm for
501 * each executing thread.
502 *
503 * This routine is invoked as part of processing each clock tick.
504 *
505 * @param[in] scheduler The scheduler.
506 * @param[in] executing An executing thread.
507 */
508void _Scheduler_default_Tick(
509  const Scheduler_Control *scheduler,
510  Thread_Control          *executing
511);
512
513/**
514 * @brief Starts an idle thread.
515 *
516 * @param[in] scheduler The scheduler.
517 * @param[in] the_thread An idle thread.
518 * @param[in] cpu This parameter is unused.
519 */
520void _Scheduler_default_Start_idle(
521  const Scheduler_Control *scheduler,
522  Thread_Control          *the_thread,
523  struct Per_CPU_Control  *cpu
524);
525
526#if defined(__RTEMS_HAVE_SYS_CPUSET_H__) && defined(RTEMS_SMP)
527  /**
528   * @brief Get affinity for the default scheduler.
529   *
530   * @param[in] scheduler The scheduler instance.
531   * @param[in] thread The associated thread.
532   * @param[in] cpusetsize The size of the cpuset.
533   * @param[out] cpuset Affinity set containing all CPUs.
534   *
535   * @retval 0 Successfully got cpuset
536   * @retval -1 The cpusetsize is invalid for the system
537   */
538  bool _Scheduler_default_Get_affinity(
539    const Scheduler_Control *scheduler,
540    Thread_Control          *thread,
541    size_t                   cpusetsize,
542    cpu_set_t               *cpuset
543  );
544
545  /**
546   * @brief Set affinity for the default scheduler.
547   *
548   * @param[in] scheduler The scheduler instance.
549   * @param[in] thread The associated thread.
550   * @param[in] cpusetsize The size of the cpuset.
551   * @param[in] cpuset Affinity new affinity set.
552   *
553   * @retval 0 Successful
554   *
555   *  This method always returns successful and does not save
556   *  the cpuset.
557   */
558  bool _Scheduler_default_Set_affinity(
559    const Scheduler_Control *scheduler,
560    Thread_Control          *thread,
561    size_t                   cpusetsize,
562    const cpu_set_t         *cpuset
563  );
564
565  #define SCHEDULER_OPERATION_DEFAULT_GET_SET_AFFINITY \
566    , _Scheduler_default_Get_affinity \
567    , _Scheduler_default_Set_affinity
568#else
569  #define SCHEDULER_OPERATION_DEFAULT_GET_SET_AFFINITY
570#endif
571
572/**
573 * @brief This defines the lowest (least important) thread priority of the
574 * first scheduler instance.
575 */
576#define PRIORITY_MAXIMUM ( _Scheduler_Table[ 0 ].maximum_priority )
577
578/**@}*/
579
580#ifdef __cplusplus
581}
582#endif
583
584#endif
585/* end of include file */
Note: See TracBrowser for help on using the repository browser.