LXR 6.1/​cpukit/​include/​rtems/​score/​schedulercbs.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:13

 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
  * @file
  *
  * @ingroup RTEMSScoreSchedulerCBS
  *
  * @brief This header file provides interfaces of the
  *   @ref RTEMSScoreSchedulerCBS which are used by the implementation and the
  *   @ref RTEMSImplApplConfig.
  */
 
 /*
  *  Copryight (c) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
  *    documentation and/or other materials provided with the distribution.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
 #ifndef _RTEMS_SCORE_SCHEDULERCBS_H
 #define _RTEMS_SCORE_SCHEDULERCBS_H
 
 #include <rtems/score/chain.h>
 #include <rtems/score/priority.h>
 #include <rtems/score/scheduler.h>
 #include <rtems/score/rbtree.h>
 #include <rtems/score/scheduleredf.h>
 #include <rtems/rtems/signal.h>
 #include <rtems/rtems/timer.h>
 #include <rtems/score/thread.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
  * @defgroup RTEMSScoreSchedulerCBS Constant Bandwidth Server (CBS) Scheduler
  *
  * @ingroup RTEMSScoreScheduler
  *
  * @brief This group contains the Constant Bandwidth Server (CBS) Scheduler
  *   implementation.
  *
  * @{
  */
 
 #define SCHEDULER_CBS_MAXIMUM_PRIORITY SCHEDULER_EDF_MAXIMUM_PRIORITY
 
 /**
  *  Entry points for the Constant Bandwidth Server Scheduler.
  *
  *  @note: The CBS scheduler is an enhancement of EDF scheduler,
  *         therefor some routines are similar.
  */
 #define SCHEDULER_CBS_ENTRY_POINTS \
   { \
     _Scheduler_EDF_Initialize,       /* initialize entry point */ \
     _Scheduler_EDF_Schedule,         /* schedule entry point */ \
     _Scheduler_EDF_Yield,            /* yield entry point */ \
     _Scheduler_EDF_Block,            /* block entry point */ \
     _Scheduler_CBS_Unblock,          /* unblock entry point */ \
     _Scheduler_EDF_Update_priority,  /* update priority entry point */ \
     _Scheduler_EDF_Map_priority,     /* map priority entry point */ \
     _Scheduler_EDF_Unmap_priority,   /* unmap priority entry point */ \
     SCHEDULER_DEFAULT_SMP_OPERATIONS \
     _Scheduler_CBS_Node_initialize,  /* node initialize entry point */ \
     _Scheduler_default_Node_destroy, /* node destroy entry point */ \
     _Scheduler_CBS_Release_job,      /* new period of task */ \
     _Scheduler_CBS_Cancel_job,       /* cancel period of task */ \
     _Scheduler_default_Start_idle    /* start idle entry point */ \
     SCHEDULER_DEFAULT_SET_AFFINITY_OPERATION \
   }
 
 /* Return values for CBS server. */
 #define SCHEDULER_CBS_OK                        0
 #define SCHEDULER_CBS_ERROR_GENERIC            -16
 #define SCHEDULER_CBS_ERROR_NO_MEMORY          -17
 #define SCHEDULER_CBS_ERROR_INVALID_PARAMETER  -18
 #define SCHEDULER_CBS_ERROR_UNAUTHORIZED       -19
 #define SCHEDULER_CBS_ERROR_UNIMPLEMENTED      -20
 #define SCHEDULER_CBS_ERROR_MISSING_COMPONENT  -21
 #define SCHEDULER_CBS_ERROR_INCONSISTENT_STATE -22
 #define SCHEDULER_CBS_ERROR_SYSTEM_OVERLOAD    -23
 #define SCHEDULER_CBS_ERROR_INTERNAL_ERROR     -24
 #define SCHEDULER_CBS_ERROR_NOT_FOUND          -25
 #define SCHEDULER_CBS_ERROR_FULL               -26
 #define SCHEDULER_CBS_ERROR_EMPTY              -27
 #define SCHEDULER_CBS_ERROR_NOSERVER           SCHEDULER_CBS_ERROR_NOT_FOUND
 
 /** Maximum number of simultaneous servers. */
 extern const uint32_t _Scheduler_CBS_Maximum_servers;
 
 /** Server id. */
 typedef uint32_t Scheduler_CBS_Server_id;
 
 /** Callback function invoked when a budget overrun of a task occurs. */
 typedef void (*Scheduler_CBS_Budget_overrun)(
     Scheduler_CBS_Server_id server_id
 );
 
 /**
  * This structure handles server parameters.
  */
 typedef struct {
   /** Relative deadline of the server. */
   time_t deadline;
   /** Budget (computation time) of the server. */
   time_t budget;
 } Scheduler_CBS_Parameters;
 
 /**
  * This structure represents a time server.
  */
 typedef struct {
   /**
    * Task id.
    *
    * @note: The current implementation of CBS handles only one task per server.
    */
   rtems_id                 task_id;
   /** Server paramenters. */
   Scheduler_CBS_Parameters parameters;
   /** Callback function invoked when a budget overrun occurs. */
   Scheduler_CBS_Budget_overrun  cbs_budget_overrun;
 
   /**
    * @brief Indicates if this CBS server is initialized.
    *
    * @see _Scheduler_CBS_Create_server() and _Scheduler_CBS_Destroy_server().
    */
   bool initialized;
 } Scheduler_CBS_Server;
 
 /**
  * This structure handles CBS specific data of a thread.
  */
 typedef struct {
   /** EDF scheduler specific data of a task. */
   Scheduler_EDF_Node            Base;
   /** CBS server specific data of a task. */
   Scheduler_CBS_Server         *cbs_server;
 
   Priority_Node                *deadline_node;
 } Scheduler_CBS_Node;
 
 
 /**
  * List of servers. The @a Scheduler_CBS_Server is the index to the array
  * of pointers to @a _Scheduler_CBS_Server_list.
  */
 extern Scheduler_CBS_Server _Scheduler_CBS_Server_list[];
 
 /**
  * @brief Unblocks a thread.
  *
  * @param scheduler The scheduler control.
  * @param the_thread The thread to unblock.
  * @param node The scheduler node.
  */
 void _Scheduler_CBS_Unblock(
   const Scheduler_Control *scheduler,
   Thread_Control          *the_thread,
   Scheduler_Node          *node
 );
 
 /**
  * @brief Releases a job.
  *
  * @param scheduler The scheduler for the operation.
  * @param the_thread The corresponding thread.
  * @param priority_node The priority node for the operation.
  * @param deadline The deadline for the job.
  * @param queue_context The thread queue context.
  */
 void _Scheduler_CBS_Release_job(
   const Scheduler_Control *scheduler,
   Thread_Control          *the_thread,
   Priority_Node           *priority_node,
   uint64_t                 deadline,
   Thread_queue_Context    *queue_context
 );
 
 /**
  * @brief Cancels a job.
  *
  * @param scheduler The scheduler for the operation.
  * @param the_thread The corresponding thread.
  * @param priority_node The priority node for the operation.
  * @param queue_context The thread queue context.
  */
 void _Scheduler_CBS_Cancel_job(
   const Scheduler_Control *scheduler,
   Thread_Control          *the_thread,
   Priority_Node           *priority_node,
   Thread_queue_Context    *queue_context
 );
 
 /**
  * @brief _Scheduler_CBS_Initialize
  *
  * Initializes the CBS library.
  *
  * @return SCHEDULER_CBS_OK This method always returns this status.
  */
 int _Scheduler_CBS_Initialize(void);
 
 /**
  * @brief Attaches a task to an already existing server.
  *
  * Attach a task to an already existing server.
  *
  * @param server_id The id of the existing server.
  * @param task_id The id of the task to attach.
  *
  * @retval SCHEDULER_CBS_OK The operation was successful.
  * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is so big
  *      or there is no thread for this task id.
  * @retval SCHEDULER_CBS_ERROR_NOSERVER The server is not yet initialized.
  * @retval SCHEDULER_CBS_ERROR_FULL The server already has a task.
  */
 int _Scheduler_CBS_Attach_thread (
   Scheduler_CBS_Server_id server_id,
   rtems_id                task_id
 );
 
 /**
  * @brief Detaches from the CBS Server.
  *
  * Detach from the CBS Server.
  *
  * @param server_id The id of the existing server.
  * @param task_id The id of the task to attach.
  *
  * @retval SCHEDULER_CBS_OK The operation was successful.
  * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is to big,
  *      or the task with this id is not attached to this server or there is
  *      no thread with this task.
  * @retval SCHEDULER_CBS_ERROR_NOSERVER The server is not yet initialized.
  */
 int _Scheduler_CBS_Detach_thread (
   Scheduler_CBS_Server_id server_id,
   rtems_id                task_id
 );
 
 /**
  * @brief Cleans up resources associated to the CBS Library.
  *
  * Cleanup resources associated to the CBS Library.
  *
  * @return This method always returns SCHEDULER_CBS_OK.
  */
 int _Scheduler_CBS_Cleanup (void);
 
 /**
  * @brief Creates a new server with specified parameters.
  *
  * Create a new server with specified parameters.
  *
  * @param params The parameters for the server.
  * @param budget_overrun_callback The budget overrun for the new server.
  * @param[out] server_id In the case of success, this parameter contains the
  *      id of the newly created server.
  *
  * @retval SCHEDULER_CBS_OK The operation succeeded.
  * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The given parameters are invalid.
  * @retval SCHEDULER_CBS_ERROR_FULL The maximum number of servers was already
  *      created, a new server cannot be created.
  */
 int _Scheduler_CBS_Create_server (
   Scheduler_CBS_Parameters     *params,
   Scheduler_CBS_Budget_overrun  budget_overrun_callback,
   rtems_id                     *server_id
 );
 
 /**
  * @brief Detaches all tasks from a server and destroys it.
  *
  * Detach all tasks from a server and destroy it.
  *
  * @param server_id The id of the server to destroy.
  *
  * @retval SCHEDULER_CBS_OK The operation was successful.
  * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big.
  * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no initialized server with this id.
  */
 int _Scheduler_CBS_Destroy_server (
   Scheduler_CBS_Server_id server_id
 );
 
 /**
  * @brief Retrieves the approved budget.
  *
  * Retrieve the budget that has been approved for the subsequent
  * server instances.
  *
  * @param server_id The id of the server instance of which the budget is wanted.
  * @param[out] approved_budget Contains the approved budget after a successful method call.
  *
  * @retval SCHEDULER_CBS_OK The operation was successful.
  * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big.
  * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no initialized server with this id.
  */
 int _Scheduler_CBS_Get_approved_budget (
   Scheduler_CBS_Server_id  server_id,
   time_t                  *approved_budget
 );
 
 /**
  * @brief Retrieves remaining budget for the current server instance.
  *
  * Retrieve remaining budget for the current server instance.
  *
  * @param server_id The id of the server instance of which the remaining budget is wanted.
  * @param[out] remaining_budget Contains the remaining budget after a successful method call.
  *
  * @retval SCHEDULER_CBS_OK The operation was successful.
  * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big.
  * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no initialized server with this id.
  */
 int _Scheduler_CBS_Get_remaining_budget (
   Scheduler_CBS_Server_id  server_id,
   time_t                  *remaining_budget
 );
 
 /**
  * @brief Gets relative time info.
  *
  * Retrieve time info relative to @a server_id. The server status code is returned.
  *
  * @param server_id is the server to get the status code from.
  * @param[out] exec_time Contains the execution time after a successful method call.
  * @param abs_time Not apparently used.
  *
  * @retval SCHEDULER_CBS_OK The operation was successful.
  * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big.
  * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no initialized server with this id.
  */
 int _Scheduler_CBS_Get_execution_time (
   Scheduler_CBS_Server_id   server_id,
   time_t                   *exec_time,
   time_t                   *abs_time
 );
 
 /**
  * @brief Retrieves CBS scheduling parameters.
  *
  * Retrieve CBS scheduling parameters.
  *
  * @param server_id The id of the server to get the scheduling parameters from.
  * @param[out] params Will contain the scheduling parameters after successful method call.
  *
  * @retval SCHEDULER_CBS_OK The operation was successful.
  * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big.
  * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no initialized server with this id.
  */
 int _Scheduler_CBS_Get_parameters (
   Scheduler_CBS_Server_id   server_id,
   Scheduler_CBS_Parameters *params
 );
 
 /**
  * @brief Gets a thread server id.
  *
  * Get a thread server id, or SCHEDULER_CBS_ERROR_NOT_FOUND if it is not
  * attached to any server.
  *
  * @param task_id The id of the task to get the corresponding server.
  * @param[out] server_id Will contain the server id after successful method call.
  * @retval SCHEDULER_CBS_OK The operation was successful
  * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no server with this task attached.
  */
 int _Scheduler_CBS_Get_server_id (
   rtems_id                 task_id,
   Scheduler_CBS_Server_id *server_id
 );
 
 /**
  * @brief Sets parameters for CBS scheduling.
  *
  * Change CBS scheduling parameters.
  *
  * @param server_id The id of the server.
  * @param parameters The parameters to set.
  *
  * @retval SCHEDULER_CBS_OK The operation was successful.
  * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big or the
  *      given parameters are invalid.
  * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no server with this id.
  */
 int _Scheduler_CBS_Set_parameters (
   Scheduler_CBS_Server_id   server_id,
   Scheduler_CBS_Parameters *parameters
 );
 
 /**
  * @brief These are the CBS CPU budget operations.
  */
 extern const Thread_CPU_budget_operations _Scheduler_CBS_Budget;
 
 /**
  * @brief Initializes a CBS specific scheduler node of @a the_thread.
  *
  * @param scheduler The scheduler control for the operation.
  * @param[out] node The scheduler node to initalize.
  * @param the_thread The thread to initialize a scheduler node for.
  * @param priority The priority for the node.
  */
 void _Scheduler_CBS_Node_initialize(
   const Scheduler_Control *scheduler,
   Scheduler_Node          *node,
   Thread_Control          *the_thread,
   Priority_Control         priority
 );
 
 #ifdef __cplusplus
 }
 #endif
 
 /** @} */
 
 #endif
 /* end of include file */

This page was automatically generated by the 2.3.7 LXR engine. The LXR team