source: rtems/cpukit/include/rtems/score/priority.h @ c5b7942

5
Last change on this file since c5b7942 was c5b7942, checked in by Chris Johns <chrisj@…>, on 08/19/22 at 05:22:17

cpukit/include: Fix including in C++

Closes #4709

  • Property mode set to 100644
File size: 5.4 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup RTEMSScorePriority
5 *
6 * @brief Priority Handler API
7 */
8
9/*
10 *  COPYRIGHT (c) 1989-2011.
11 *  On-Line Applications Research Corporation (OAR).
12 *
13 *  Copyright (c) 2016, 2017 embedded brains GmbH.
14 *
15 *  The license and distribution terms for this file may be
16 *  found in the file LICENSE in this distribution or at
17 *  http://www.rtems.org/license/LICENSE.
18 */
19
20#ifndef _RTEMS_SCORE_PRIORITY_H
21#define _RTEMS_SCORE_PRIORITY_H
22
23#include <rtems/score/chain.h>
24#include <rtems/score/cpu.h>
25#include <rtems/score/rbtree.h>
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31struct _Scheduler_Control;
32
33/**
34 * @defgroup RTEMSScorePriority Priority Handler
35 *
36 * @ingroup RTEMSScore
37 *
38 * @brief Priority Handler
39 *
40 * This handler encapsulates functionality which is used to manage thread
41 * priorities.  The actual priority of a thread is an aggregation of priority
42 * nodes.  The thread priority aggregation for the home scheduler instance of a
43 * thread consists of at least one priority node, which is normally the real
44 * priority of the thread.  The locking protocols (e.g. priority ceiling and
45 * priority inheritance), rate-monotonic period objects and the POSIX sporadic
46 * server add, change and remove priority nodes.
47 *
48 * @{
49 */
50
51/**
52 * @brief The thread priority control.
53 *
54 * Lower values represent higher priorities.  So, a priority value of zero
55 * represents the highest priority thread.  This value is reserved for internal
56 * threads and the priority ceiling protocol.
57 *
58 * The format of the thread priority control depends on the context.  A thread
59 * priority control may contain a user visible priority for API import/export.
60 * It may also contain a scheduler internal priority value.  Values are
61 * translated via the scheduler map/unmap priority operations.  The format of
62 * scheduler interal values depend on the particular scheduler implementation.
63 * It may for example encode a deadline in case of the EDF scheduler.
64 *
65 * The thread priority control value contained in the scheduler node
66 * (Scheduler_Node::Priority::value) uses the least-significant bit to indicate
67 * if the thread should be appended or prepended to its priority group, see
68 * SCHEDULER_PRIORITY_APPEND().
69 */
70typedef uint64_t Priority_Control;
71
72/**
73 * @brief The highest (most important) thread priority value.
74 */
75#define PRIORITY_MINIMUM      0
76
77/**
78 * @brief The priority value of pseudo-ISR threads.
79 *
80 * Examples are the MPCI and timer server threads.
81 */
82#define PRIORITY_PSEUDO_ISR   PRIORITY_MINIMUM
83
84/**
85 * @brief The default lowest (least important) thread priority value.
86 *
87 * This value is CPU port dependent.
88 */
89#if defined (CPU_PRIORITY_MAXIMUM)
90  #define PRIORITY_DEFAULT_MAXIMUM      CPU_PRIORITY_MAXIMUM
91#else
92  #define PRIORITY_DEFAULT_MAXIMUM      255
93#endif
94
95/**
96 * @brief The priority node to build up a priority aggregation.
97 */
98typedef struct {
99  /**
100   * @brief Node component for a chain or red-black tree.
101   */
102  union {
103    Chain_Node Chain;
104    RBTree_Node RBTree;
105  } Node;
106
107  /**
108   * @brief The priority value of this node.
109   */
110  Priority_Control priority;
111} Priority_Node;
112
113/**
114 * @brief The priority action type.
115 */
116typedef enum {
117  PRIORITY_ACTION_ADD,
118  PRIORITY_ACTION_CHANGE,
119  PRIORITY_ACTION_REMOVE,
120  PRIORITY_ACTION_INVALID
121} Priority_Action_type;
122
123typedef struct Priority_Aggregation Priority_Aggregation;
124
125/**
126 * @brief The priority aggregation.
127 *
128 * This structure serves two purposes.  Firstly, it provides a place to
129 * register priority nodes and reflects the overall priority of its
130 * contributors.  Secondly, it provides an action block to signal addition,
131 * change and removal of a priority node.
132 */
133struct Priority_Aggregation {
134  /**
135   * @brief This priority node reflects the overall priority of the aggregation.
136   *
137   * The overall priority of the aggregation is the minimum priority of the
138   * priority nodes in the contributors tree.
139   *
140   * This priority node may be used to add this aggregation to another
141   * aggregation to build up a recursive priority scheme.
142   *
143   * In case priority nodes of the contributors tree are added, changed or
144   * removed the priority of this node may change.  To signal such changes to a
145   * priority aggregation the action block may be used.
146   */
147  Priority_Node Node;
148
149  /**
150   * @brief A red-black tree to contain priority nodes contributing to the
151   * overall priority of this priority aggregation.
152   */
153  RBTree_Control Contributors;
154
155#if defined(RTEMS_SMP)
156  /**
157   * @brief The scheduler instance of this priority aggregation.
158   */
159  const struct _Scheduler_Control *scheduler;
160#endif
161
162  /**
163   * @brief A priority action block to manage priority node additions, changes
164   * and removals.
165   */
166  struct {
167#if defined(RTEMS_SMP)
168    /**
169     * @brief The next priority aggregation in the action list.
170     */
171    Priority_Aggregation *next;
172#endif
173
174    /**
175     * @brief The priority node of the action.
176     */
177    Priority_Node *node;
178
179    /**
180     * @brief The type of the action.
181     */
182    Priority_Action_type type;
183  } Action;
184};
185
186/**
187 * @brief A list of priority actions.
188 *
189 * Actions are only added to the list.  The action lists reside on the stack
190 * and have a short life-time.  They are moved, processed or destroyed as a
191 * whole.
192 */
193typedef struct {
194  /**
195   * @brief The first action of a priority action list.
196   */
197  Priority_Aggregation *actions;
198} Priority_Actions;
199
200#ifdef __cplusplus
201}
202#endif
203
204/** @} */
205
206#endif
207/* end of include file */
Note: See TracBrowser for help on using the repository browser.