source: rtems/cpukit/score/include/rtems/score/scheduler.h @ 0e754fac

5
Last change on this file since 0e754fac was 0e754fac, checked in by Sebastian Huber <sebastian.huber@…>, on Oct 21, 2016 at 12:41:19 PM

score: Delete unused scheduler ask for help X op

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