source: rtems/cpukit/score/include/rtems/score/scheduler.h @ 9c238e1

5
Last change on this file since 9c238e1 was 9c238e1, checked in by Sebastian Huber <sebastian.huber@…>, on Oct 21, 2016 at 12:33:01 PM

score: Simplify update priority scheduler op

Remove unused return status.

  • Property mode set to 100644
File size: 14.7 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 Thread_Control * Scheduler_Void_or_thread;
47
48  #define SCHEDULER_RETURN_VOID_OR_NULL return NULL
49#else
50  typedef void Scheduler_Void_or_thread;
51
52  #define SCHEDULER_RETURN_VOID_OR_NULL 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_thread ( *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_thread ( *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   * Ask for help operation.
154   *
155   * @param[in] scheduler The scheduler of the thread offering help.
156   * @param[in] offers_help The thread offering help.
157   * @param[in] needs_help The thread needing help.
158   *
159   * @retval needs_help It was not possible to schedule the thread needing
160   *   help, so it is returned to continue the search for help.
161   * @retval next_needs_help It was possible to schedule the thread needing
162   *   help, but this displaced another thread eligible to ask for help.  So
163   *   this thread is returned to start a new search for help.
164   * @retval NULL It was possible to schedule the thread needing help, and no
165   *   other thread needs help as a result.
166   *
167   * @see _Scheduler_Ask_for_help_X().
168   */
169  Thread_Control *( *ask_for_help_X )(
170    const Scheduler_Control *scheduler,
171    Thread_Control          *offers_help,
172    Thread_Control          *needs_help
173  );
174#endif
175
176  /** @see _Scheduler_Node_initialize() */
177  void ( *node_initialize )(
178    const Scheduler_Control *,
179    Scheduler_Node *,
180    Thread_Control *,
181    Priority_Control
182  );
183
184  /** @see _Scheduler_Node_destroy() */
185  void ( *node_destroy )( const Scheduler_Control *, Scheduler_Node * );
186
187  /** @see _Scheduler_Release_job() */
188  void ( *release_job ) (
189    const Scheduler_Control *,
190    Thread_Control *,
191    Priority_Node *,
192    uint64_t,
193    Thread_queue_Context *
194  );
195
196  /** @see _Scheduler_Cancel_job() */
197  void ( *cancel_job ) (
198    const Scheduler_Control *,
199    Thread_Control *,
200    Priority_Node *,
201    Thread_queue_Context *
202  );
203
204  /** @see _Scheduler_Tick() */
205  void ( *tick )( const Scheduler_Control *, Thread_Control * );
206
207  /** @see _Scheduler_Start_idle() */
208  void ( *start_idle )(
209    const Scheduler_Control *,
210    Thread_Control *,
211    struct Per_CPU_Control *
212  );
213
214#if defined(__RTEMS_HAVE_SYS_CPUSET_H__) && defined(RTEMS_SMP)
215  /** @see _Scheduler_Get_affinity() */
216  bool ( *get_affinity )(
217    const Scheduler_Control *,
218    Thread_Control *,
219    size_t,
220    cpu_set_t *
221  );
222 
223  /** @see _Scheduler_Set_affinity() */
224  bool ( *set_affinity )(
225    const Scheduler_Control *,
226    Thread_Control *,
227    size_t,
228    const cpu_set_t *
229  );
230#endif
231} Scheduler_Operations;
232
233/**
234 * @brief Scheduler context.
235 *
236 * The scheduler context of a particular scheduler implementation must place
237 * this structure at the begin of its context structure.
238 */
239typedef struct Scheduler_Context {
240  /**
241   * @brief Lock to protect this scheduler instance.
242   */
243  ISR_LOCK_MEMBER( Lock )
244
245#if defined(RTEMS_SMP)
246  /**
247   * @brief Count of processors owned by this scheduler instance.
248   */
249  uint32_t processor_count;
250#endif
251} Scheduler_Context;
252
253/**
254 * @brief Scheduler control.
255 */
256struct Scheduler_Control {
257  /**
258   * @brief Reference to a statically allocated scheduler context.
259   */
260  Scheduler_Context *context;
261
262  /**
263   * @brief The scheduler operations.
264   */
265  Scheduler_Operations Operations;
266
267  /**
268   * @brief The maximum priority value of this scheduler.
269   *
270   * It defines the lowest (least important) thread priority for this
271   * scheduler.  For example the idle threads have this priority.
272   */
273  Priority_Control maximum_priority;
274
275  /**
276   * @brief The scheduler name.
277   */
278  uint32_t name;
279};
280
281/**
282 * @brief Registered schedulers.
283 *
284 * Application provided via <rtems/confdefs.h>.
285 *
286 * @see _Scheduler_Count.
287 */
288extern const Scheduler_Control _Scheduler_Table[];
289
290/**
291 * @brief Count of registered schedulers.
292 *
293 * Application provided via <rtems/confdefs.h> on SMP configurations.
294 *
295 * It is very important that this is a compile-time constant on uni-processor
296 * configurations (in this case RTEMS_SMP is not defined) so that the compiler
297 * can optimize the some loops away
298 *
299 * @see _Scheduler_Table.
300 */
301#if defined(RTEMS_SMP)
302  extern const size_t _Scheduler_Count;
303#else
304  #define _Scheduler_Count ( (size_t) 1 )
305#endif
306
307#if defined(RTEMS_SMP)
308  /**
309   * @brief The scheduler assignment default attributes.
310   */
311  #define SCHEDULER_ASSIGN_DEFAULT UINT32_C(0x0)
312
313  /**
314   * @brief The presence of this processor is optional.
315   */
316  #define SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL SCHEDULER_ASSIGN_DEFAULT
317
318  /**
319   * @brief The presence of this processor is mandatory.
320   */
321  #define SCHEDULER_ASSIGN_PROCESSOR_MANDATORY UINT32_C(0x1)
322
323  /**
324   * @brief Scheduler assignment.
325   */
326  typedef struct {
327    /**
328     * @brief The scheduler for this processor.
329     */
330    const Scheduler_Control *scheduler;
331
332    /**
333     * @brief The scheduler assignment attributes.
334     *
335     * Use @ref SCHEDULER_ASSIGN_DEFAULT to select default attributes.
336     *
337     * The presence of a processor can be
338     * - @ref SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL, or
339     * - @ref SCHEDULER_ASSIGN_PROCESSOR_MANDATORY.
340     */
341    uint32_t attributes;
342  } Scheduler_Assignment;
343
344  /**
345   * @brief The scheduler assignments.
346   *
347   * The length of this array must be equal to the maximum processors.
348   *
349   * Application provided via <rtems/confdefs.h>.
350   *
351   * @see _Scheduler_Table and rtems_configuration_get_maximum_processors().
352   */
353  extern const Scheduler_Assignment _Scheduler_Assignments[];
354#endif
355
356/**
357 * @brief Returns the thread priority.
358 *
359 * @param[in] scheduler Unused.
360 * @param[in] priority The thread priority.
361 *
362 * @return priority The thread priority.
363 */
364Priority_Control _Scheduler_default_Map_priority(
365  const Scheduler_Control *scheduler,
366  Priority_Control         priority
367);
368
369#define _Scheduler_default_Unmap_priority _Scheduler_default_Map_priority
370
371#if defined(RTEMS_SMP)
372  /**
373   * @brief Does nothing.
374   *
375   * @param[in] scheduler Unused.
376   * @param[in] the_thread Unused.
377   * @param[in] node Unused.
378   *
379   * @retval false Always.
380   */
381  bool _Scheduler_default_Ask_for_help(
382    const Scheduler_Control *scheduler,
383    Thread_Control          *the_thread,
384    Scheduler_Node          *node
385  );
386
387  /**
388   * @brief Does nothing.
389   *
390   * @param[in] scheduler Unused.
391   * @param[in] the_thread Unused.
392   * @param[in] node Unused.
393   */
394  void _Scheduler_default_Reconsider_help_request(
395    const Scheduler_Control *scheduler,
396    Thread_Control          *the_thread,
397    Scheduler_Node          *node
398  );
399
400  /**
401   * @brief Does nothing.
402   *
403   * @param[in] scheduler Unused.
404   * @param[in] the_thread Unused.
405   * @param[in] node Unused.
406   * @param[in] next_state Unused.
407   */
408  void _Scheduler_default_Withdraw_node(
409    const Scheduler_Control *scheduler,
410    Thread_Control          *the_thread,
411    Scheduler_Node          *node,
412    Thread_Scheduler_state   next_state
413  );
414
415  /**
416   * @brief Does nothing.
417   *
418   * @param[in] scheduler Unused.
419   * @param[in] offers_help Unused.
420   * @param[in] needs_help Unused.
421   *
422   * @retval NULL Always.
423   */
424  Thread_Control *_Scheduler_default_Ask_for_help_X(
425    const Scheduler_Control *scheduler,
426    Thread_Control          *offers_help,
427    Thread_Control          *needs_help
428  );
429
430  #define SCHEDULER_OPERATION_DEFAULT_ASK_FOR_HELP \
431    _Scheduler_default_Ask_for_help, \
432    _Scheduler_default_Reconsider_help_request, \
433    _Scheduler_default_Withdraw_node, \
434    _Scheduler_default_Ask_for_help_X,
435#else
436  #define SCHEDULER_OPERATION_DEFAULT_ASK_FOR_HELP
437#endif
438
439/**
440 * @brief Does nothing.
441 *
442 * @param[in] scheduler Unused.
443 * @param[in] the_thread Unused.
444 */
445void _Scheduler_default_Schedule(
446  const Scheduler_Control *scheduler,
447  Thread_Control          *the_thread
448);
449
450/**
451 * @brief Performs the scheduler base node initialization.
452 *
453 * @param[in] scheduler Unused.
454 * @param[in] node The node to initialize.
455 * @param[in] the_thread Unused.
456 * @param[in] priority The thread priority.
457 */
458void _Scheduler_default_Node_initialize(
459  const Scheduler_Control *scheduler,
460  Scheduler_Node          *node,
461  Thread_Control          *the_thread,
462  Priority_Control         priority
463);
464
465/**
466 * @brief Does nothing.
467 *
468 * @param[in] scheduler Unused.
469 * @param[in] node Unused.
470 */
471void _Scheduler_default_Node_destroy(
472  const Scheduler_Control *scheduler,
473  Scheduler_Node          *node
474);
475
476/**
477 * @brief Does nothing.
478 *
479 * @param[in] scheduler Unused.
480 * @param[in] the_thread Unused.
481 * @param[in] priority_node Unused.
482 * @param[in] deadline Unused.
483 * @param[in] queue_context Unused.
484 *
485 * @retval NULL Always.
486 */
487void _Scheduler_default_Release_job(
488  const Scheduler_Control *scheduler,
489  Thread_Control          *the_thread,
490  Priority_Node           *priority_node,
491  uint64_t                 deadline,
492  Thread_queue_Context    *queue_context
493);
494
495/**
496 * @brief Does nothing.
497 *
498 * @param[in] scheduler Unused.
499 * @param[in] the_thread Unused.
500 * @param[in] priority_node Unused.
501 * @param[in] queue_context Unused.
502 *
503 * @retval NULL Always.
504 */
505void _Scheduler_default_Cancel_job(
506  const Scheduler_Control *scheduler,
507  Thread_Control          *the_thread,
508  Priority_Node           *priority_node,
509  Thread_queue_Context    *queue_context
510);
511
512/**
513 * @brief Performs tick operations depending on the CPU budget algorithm for
514 * each executing thread.
515 *
516 * This routine is invoked as part of processing each clock tick.
517 *
518 * @param[in] scheduler The scheduler.
519 * @param[in] executing An executing thread.
520 */
521void _Scheduler_default_Tick(
522  const Scheduler_Control *scheduler,
523  Thread_Control          *executing
524);
525
526/**
527 * @brief Starts an idle thread.
528 *
529 * @param[in] scheduler The scheduler.
530 * @param[in] the_thread An idle thread.
531 * @param[in] cpu This parameter is unused.
532 */
533void _Scheduler_default_Start_idle(
534  const Scheduler_Control *scheduler,
535  Thread_Control          *the_thread,
536  struct Per_CPU_Control  *cpu
537);
538
539#if defined(__RTEMS_HAVE_SYS_CPUSET_H__) && defined(RTEMS_SMP)
540  /**
541   * @brief Get affinity for the default scheduler.
542   *
543   * @param[in] scheduler The scheduler instance.
544   * @param[in] thread The associated thread.
545   * @param[in] cpusetsize The size of the cpuset.
546   * @param[out] cpuset Affinity set containing all CPUs.
547   *
548   * @retval 0 Successfully got cpuset
549   * @retval -1 The cpusetsize is invalid for the system
550   */
551  bool _Scheduler_default_Get_affinity(
552    const Scheduler_Control *scheduler,
553    Thread_Control          *thread,
554    size_t                   cpusetsize,
555    cpu_set_t               *cpuset
556  );
557
558  /**
559   * @brief Set affinity for the default scheduler.
560   *
561   * @param[in] scheduler The scheduler instance.
562   * @param[in] thread The associated thread.
563   * @param[in] cpusetsize The size of the cpuset.
564   * @param[in] cpuset Affinity new affinity set.
565   *
566   * @retval 0 Successful
567   *
568   *  This method always returns successful and does not save
569   *  the cpuset.
570   */
571  bool _Scheduler_default_Set_affinity(
572    const Scheduler_Control *scheduler,
573    Thread_Control          *thread,
574    size_t                   cpusetsize,
575    const cpu_set_t         *cpuset
576  );
577
578  #define SCHEDULER_OPERATION_DEFAULT_GET_SET_AFFINITY \
579    , _Scheduler_default_Get_affinity \
580    , _Scheduler_default_Set_affinity
581#else
582  #define SCHEDULER_OPERATION_DEFAULT_GET_SET_AFFINITY
583#endif
584
585/**
586 * @brief This defines the lowest (least important) thread priority of the
587 * first scheduler instance.
588 */
589#define PRIORITY_MAXIMUM ( _Scheduler_Table[ 0 ].maximum_priority )
590
591/**@}*/
592
593#ifdef __cplusplus
594}
595#endif
596
597#endif
598/* end of include file */
Note: See TracBrowser for help on using the repository browser.