/** * @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). * * The license and distribution terms for this file may be * found in the file LICENSE in this distribution or at * http://www.rtems.org/license/LICENSE. */ #ifndef _RTEMS_SCORE_SCHEDULERCBS_H #define _RTEMS_SCORE_SCHEDULERCBS_H #include #include #include #include #include #include #include #include #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_OPERATION_DEFAULT_ASK_FOR_HELP \ _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_Tick, /* tick entry point */ \ _Scheduler_default_Start_idle /* start idle entry point */ \ SCHEDULER_OPERATION_DEFAULT_GET_SET_AFFINITY \ } /* 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 Invoked when a limited time quantum is exceeded. * * This routine is invoked when a limited time quantum is exceeded. * * @param the_thread The thread that exceeded a limited time quantum. */ void _Scheduler_CBS_Budget_callout( Thread_Control *the_thread ); /** * @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 */