rtems/posix/priorityimpl.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @brief POSIX Priority Support
0007  *
0008  * This include file defines the interface to the POSIX priority
0009  * implementation.
0010  */
0011
0012 /*
0013  *  COPYRIGHT (c) 1989-2011.
0014  *  On-Line Applications Research Corporation (OAR).
0015  *
0016  * Redistribution and use in source and binary forms, with or without
0017  * modification, are permitted provided that the following conditions
0018  * are met:
0019  * 1. Redistributions of source code must retain the above copyright
0020  *    notice, this list of conditions and the following disclaimer.
0021  * 2. Redistributions in binary form must reproduce the above copyright
0022  *    notice, this list of conditions and the following disclaimer in the
0023  *    documentation and/or other materials provided with the distribution.
0024  *
0025  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0026  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0027  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0028  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0029  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0030  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0031  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0032  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0033  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0034  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0035  * POSSIBILITY OF SUCH DAMAGE.
0036  */
0037
0038 #ifndef _RTEMS_POSIX_PRIORITYIMPL_H
0039 #define _RTEMS_POSIX_PRIORITYIMPL_H
0040
0041 #include <rtems/score/scheduler.h>
0042 #include <rtems/score/assert.h>
0043
0044 #ifdef __cplusplus
0045 extern "C" {
0046 #endif
0047
0048 /**
0049  * @defgroup POSIX_PRIORITY POSIX Priority Support
0050  *
0051  * @ingroup POSIXAPI
0052  *
0053  * @brief Interface to the POSIX Priority Implementation.
0054  *
0055  * @{
0056  */
0057
0058 /**
0059  *  This is the numerically least important POSIX priority.
0060  */
0061 #define POSIX_SCHEDULER_MINIMUM_PRIORITY (1)
0062
0063 /**
0064  * @brief Gets the maximum POSIX API priority for this scheduler instance.
0065  *
0066  * Such a priority is valid.  A scheduler instance may support priority values
0067  * that are not representable as an integer.
0068  *
0069  * @return The maximum POSIX API priority for this scheduler instance.
0070  */
0071 static inline int _POSIX_Priority_Get_maximum(
0072   const Scheduler_Control *scheduler
0073 )
0074 {
0075   _Assert( (int) scheduler->maximum_priority > 1 );
0076   return (int) scheduler->maximum_priority - 1;
0077 }
0078
0079 /**
0080  * @brief Converts the POSIX API priority to the corresponding SuperCore
0081  * priority and validates it.
0082  *
0083  * According to POSIX, numerically higher values represent higher priorities.
0084  * Thus, SuperCore has priorities run in the opposite sense of the POSIX API.
0085  *
0086  * Let N be the maximum priority of this scheduler instance.   The SuperCore
0087  * priority zero is system reserved (PRIORITY_MINIMUM).  There are only
0088  * N - 1 POSIX API priority levels since a thread at SuperCore priority N would
0089  * never run because of the idle threads.  This is necessary because GNAT maps
0090  * the lowest Ada task priority to the lowest thread priority.  The lowest
0091  * priority Ada task should get to run, so there is a fundamental conflict with
0092  * having N priorities.
0093  *
0094  * @param[in] scheduler The scheduler instance.
0095  * @param[in] priority The POSIX API priority to convert and validate.
0096  * @param[out] valid Indicates if the POSIX API priority is valid and a
0097  *   corresponding SuperCore priority in the specified scheduler instance
0098  *   exists.
0099  *
0100  * @return The corresponding SuperCore priority.
0101  */
0102 Priority_Control _POSIX_Priority_To_core(
0103   const Scheduler_Control *scheduler,
0104   int                      priority,
0105   bool                    *valid
0106 );
0107
0108 /**
0109  * @brief Converts the SuperCore priority to the corresponding POSIX API
0110  * priority.
0111  *
0112  * @param[in] scheduler The scheduler instance.
0113  * @param[in] priority The SuperCore priority to convert.
0114  *
0115  * @return The corresponding POSIX API priority.
0116  */
0117 int _POSIX_Priority_From_core(
0118   const Scheduler_Control *scheduler,
0119   Priority_Control         priority
0120 );
0121
0122 /** @} */
0123
0124 #ifdef __cplusplus
0125 }
0126 #endif
0127
0128 #endif