path: root/cpukit/include/rtems/score/schedulercbs.h

/**
 * @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 <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_Tick,         /* tick entry point */ \
    _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 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 */