rtems/score/priority.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSScorePriority
0007  *
0008  * @brief This header file provides interfaces of the
0009  *   @ref RTEMSScorePriority which are used by the implementation and the
0010  *   @ref RTEMSImplApplConfig.
0011  */
0012
0013 /*
0014  *  COPYRIGHT (c) 1989-2011.
0015  *  On-Line Applications Research Corporation (OAR).
0016  *
0017  *  Copyright (C) 2016, 2017 embedded brains GmbH & Co. KG
0018  *
0019  * Redistribution and use in source and binary forms, with or without
0020  * modification, are permitted provided that the following conditions
0021  * are met:
0022  * 1. Redistributions of source code must retain the above copyright
0023  *    notice, this list of conditions and the following disclaimer.
0024  * 2. Redistributions in binary form must reproduce the above copyright
0025  *    notice, this list of conditions and the following disclaimer in the
0026  *    documentation and/or other materials provided with the distribution.
0027  *
0028  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0029  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0030  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0031  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0032  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0033  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0034  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0035  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0036  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0037  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0038  * POSSIBILITY OF SUCH DAMAGE.
0039  */
0040
0041 #ifndef _RTEMS_SCORE_PRIORITY_H
0042 #define _RTEMS_SCORE_PRIORITY_H
0043
0044 #include <rtems/score/chain.h>
0045 #include <rtems/score/cpu.h>
0046 #include <rtems/score/rbtree.h>
0047
0048 #ifdef __cplusplus
0049 extern "C" {
0050 #endif
0051
0052 struct _Scheduler_Control;
0053
0054 /**
0055  * @defgroup RTEMSScorePriority Priority Handler
0056  *
0057  * @ingroup RTEMSScore
0058  *
0059  * @brief This group contains the Priority Handler implementation.
0060  *
0061  * This handler encapsulates functionality which is used to manage thread
0062  * priorities.  The actual priority of a thread is an aggregation of priority
0063  * nodes.  The thread priority aggregation for the home scheduler instance of a
0064  * thread consists of at least one priority node, which is normally the real
0065  * priority of the thread.  The locking protocols (e.g. priority ceiling and
0066  * priority inheritance), rate-monotonic period objects and the POSIX sporadic
0067  * server add, change and remove priority nodes.
0068  *
0069  * @{
0070  */
0071
0072 /**
0073  * @brief The thread priority control.
0074  *
0075  * Lower values represent higher priorities.  So, a priority value of zero
0076  * represents the highest priority thread.  This value is reserved for internal
0077  * threads and the priority ceiling protocol.
0078  *
0079  * The format of the thread priority control depends on the context.  A thread
0080  * priority control may contain a user visible priority for API import/export.
0081  * It may also contain a scheduler internal priority value.  Values are
0082  * translated via the scheduler map/unmap priority operations.  The format of
0083  * scheduler interal values depend on the particular scheduler implementation.
0084  * It may for example encode a deadline in case of the EDF scheduler.
0085  *
0086  * The thread priority control value contained in the scheduler node
0087  * (Scheduler_Node::Priority::value) uses the least-significant bit to indicate
0088  * if the thread should be appended or prepended to its priority group, see
0089  * SCHEDULER_PRIORITY_APPEND().
0090  */
0091 typedef uint64_t Priority_Control;
0092
0093 /**
0094  * @brief The highest (most important) thread priority value.
0095  */
0096 #define PRIORITY_MINIMUM      0
0097
0098 /**
0099  * @brief The default lowest (least important) thread priority value.
0100  *
0101  * This value is CPU port dependent.
0102  */
0103 #if defined (CPU_PRIORITY_MAXIMUM)
0104   #define PRIORITY_DEFAULT_MAXIMUM      CPU_PRIORITY_MAXIMUM
0105 #else
0106   #define PRIORITY_DEFAULT_MAXIMUM      255
0107 #endif
0108
0109 /**
0110  * @brief The priority node to build up a priority aggregation.
0111  */
0112 typedef struct {
0113   /**
0114    * @brief Node component for a chain or red-black tree.
0115    */
0116   union {
0117     Chain_Node Chain;
0118     RBTree_Node RBTree;
0119   } Node;
0120
0121   /**
0122    * @brief The priority value of this node.
0123    */
0124   Priority_Control priority;
0125 } Priority_Node;
0126
0127 /**
0128  * @brief The priority action type.
0129  */
0130 typedef enum {
0131   PRIORITY_ACTION_ADD,
0132   PRIORITY_ACTION_CHANGE,
0133   PRIORITY_ACTION_REMOVE,
0134   PRIORITY_ACTION_INVALID
0135 } Priority_Action_type;
0136
0137 typedef struct Priority_Aggregation Priority_Aggregation;
0138
0139 /**
0140  * @brief The priority aggregation.
0141  *
0142  * This structure serves two purposes.  Firstly, it provides a place to
0143  * register priority nodes and reflects the overall priority of its
0144  * contributors.  Secondly, it provides an action block to signal addition,
0145  * change and removal of a priority node.
0146  */
0147 struct Priority_Aggregation {
0148   /**
0149    * @brief This priority node reflects the overall priority of the aggregation.
0150    *
0151    * The overall priority of the aggregation is the minimum priority of the
0152    * priority nodes in the contributors tree.
0153    *
0154    * This priority node may be used to add this aggregation to another
0155    * aggregation to build up a recursive priority scheme.
0156    *
0157    * In case priority nodes of the contributors tree are added, changed or
0158    * removed the priority of this node may change.  To signal such changes to a
0159    * priority aggregation the action block may be used.
0160    */
0161   Priority_Node Node;
0162
0163   /**
0164    * @brief A red-black tree to contain priority nodes contributing to the
0165    * overall priority of this priority aggregation.
0166    */
0167   RBTree_Control Contributors;
0168
0169 #if defined(RTEMS_SMP)
0170   /**
0171    * @brief The scheduler instance of this priority aggregation.
0172    */
0173   const struct _Scheduler_Control *scheduler;
0174 #endif
0175
0176   /**
0177    * @brief A priority action block to manage priority node additions, changes
0178    * and removals.
0179    */
0180   struct {
0181 #if defined(RTEMS_SMP)
0182     /**
0183      * @brief The next priority aggregation in the action list.
0184      */
0185     Priority_Aggregation *next;
0186 #endif
0187
0188     /**
0189      * @brief The priority node of the action.
0190      */
0191     Priority_Node *node;
0192
0193     /**
0194      * @brief The type of the action.
0195      */
0196     Priority_Action_type type;
0197   } Action;
0198 };
0199
0200 /**
0201  * @brief A list of priority actions.
0202  *
0203  * Actions are only added to the list.  The action lists reside on the stack
0204  * and have a short life-time.  They are moved, processed or destroyed as a
0205  * whole.
0206  */
0207 typedef struct {
0208   /**
0209    * @brief The first action of a priority action list.
0210    */
0211   Priority_Aggregation *actions;
0212 } Priority_Actions;
0213
0214 #ifdef __cplusplus
0215 }
0216 #endif
0217
0218 /** @} */
0219
0220 #endif
0221 /* end of include file */