diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/user/cbs.t | 643 |
1 files changed, 0 insertions, 643 deletions
diff --git a/doc/user/cbs.t b/doc/user/cbs.t deleted file mode 100644 index 52eec94780..0000000000 --- a/doc/user/cbs.t +++ /dev/null @@ -1,643 +0,0 @@ -@c -@c COPYRIGHT (c) 2011. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Constant Bandwidth Server Scheduler API - -@cindex cbs - -@section Introduction - -Unlike simple schedulers, the Constant Bandwidth Server (CBS) requires -a special API for tasks to indicate their scheduling parameters. -The directives provided by the CBS API are: - -@itemize @bullet -@item @code{@value{DIRPREFIX}cbs_initialize} - Initialize the CBS library -@item @code{@value{DIRPREFIX}cbs_cleanup} - Cleanup the CBS library -@item @code{@value{DIRPREFIX}cbs_create_server} - Create a new bandwidth server -@item @code{@value{DIRPREFIX}cbs_attach_thread} - Attach a thread to server -@item @code{@value{DIRPREFIX}cbs_detach_thread} - Detach a thread from server -@item @code{@value{DIRPREFIX}cbs_destroy_server} - Destroy a bandwidth server -@item @code{@value{DIRPREFIX}cbs_get_server_id} - Get an ID of a server -@item @code{@value{DIRPREFIX}cbs_get_parameters} - Get scheduling parameters of a server -@item @code{@value{DIRPREFIX}cbs_set_parameters} - Set scheduling parameters of a server -@item @code{@value{DIRPREFIX}cbs_get_execution_time} - Get elapsed execution time -@item @code{@value{DIRPREFIX}cbs_get_remaining_budget} - Get remainig execution time -@item @code{@value{DIRPREFIX}cbs_get_approved_budget} - Get scheduler approved execution time -@end itemize - -@section Background - -@subsection Constant Bandwidth Server Definitions - -@cindex CBS parameters - -@findex rtems_cbs_parameters - -The Constant Bandwidth Server API enables tasks to communicate with -the scheduler and indicate its scheduling parameters. The scheduler -has to be set up first (by defining @code{CONFIGURE_SCHEDULER_CBS} macro). - -The difference to a plain EDF is the presence of servers. -It is a budget aware extention of the EDF scheduler, therefore, tasks -attached to servers behave in a similar way as with EDF unless they -exceed their budget. - -The intention of servers is reservation of a certain computation -time (budget) of the processor for all subsequent periods. The structure -@code{rtems_cbs_parameters} determines the behavior of -a server. It contains @code{deadline} which is equal to period, -and @code{budget} which is the time the server is allowed to -spend on CPU per each period. The ratio between those two parameters -yields the maximum percentage of the CPU the server can use -(bandwidth). Moreover, thanks to this limitation the overall -utilization of CPU is under control, and the sum of bandwidths -of all servers in the system yields the overall reserved portion -of processor. The rest is still available for ordinary tasks that -are not attached to any server. - -In order to make the server effective to the executing tasks, -tasks have to be attached to the servers. The -@code{rtems_cbs_server_id} is a type denoting an id of a server -and @code{rtems_id} a type for id of tasks. - -@subsection Handling Periodic Tasks - -@cindex CBS periodic tasks - -Each task's execution begins with a default background priority -(see the chapter Scheduling Concepts to understand the concept of -priorities in EDF). Once you decide the tasks should start periodic -execution, you have two possibilities. Either you use only the Rate -Monotonic manager which takes care of periodic behavior, or you declare -deadline and budget using the CBS API in which case these properties -are constant for all subsequent periods, unless you change them using -the CBS API again. Task now only has to indicate and end of -each period using @code{rtems_rate_monotonic_period}. - -@subsection Registering a Callback Function - -@cindex CBS overrun handler - -In case tasks attached to servers are not aware of their execution time -and happen to exceed it, the scheduler does not guarantee execution any -more and pulls the priority of the task to background, which would -possibly lead to immediate preemption (if there is at least one ready -task with a higher pirority). However, the task is not blocked but a -callback function is invoked. The callback function -(@code{rtems_cbs_budget_overrun}) might be optionally registered upon -a server creation (@code{rtems_cbs_create_server}). - -This enables the user to define what should happen in case of budget -overrun. There is obviously no space for huge operations because the -priority is down and not real time any more, however, you still can at -least in release resources for other tasks, restart the task or log an -error information. Since the routine is called directly from kernel, -use @code{printk()} instead of @code{printf()}. - -The calling convention of the callback function is: -@ifset is-C -@findex rtems_asr -@example -void overrun_handler( - rtems_cbs_server_id server_id -); -@end example -@end ifset - -@subsection Limitations - -@cindex CBS limitations - -When using this scheduler you have to keep in mind several things: - -@itemize @bullet -@c it_limitations -@item In the current implementation it is possible to attach only -a single task to each server. -@item If you have a task attached to a server and you voluntatily -block it in the beginning of its execution, its priority will be -probably pulled to background upon unblock, thus not guaranteed -deadline any more. This is because you are effectively raising -computation time of the task. When unbocking, you should be always -sure that the ratio between remaining computation time and remaining -deadline is not higher that the utilization you have agreed with the -scheduler. -@end itemize - -@section Operations - -@subsection Setting up a server - -The directive @code{rtems_cbs_create_server} is used to create a new -server that is characterized by @code{rtems_cbs_parameters}. You also -might want to register the @code{rtems_cbs_budget_overrun} callback -routine. After this step tasks can be attached to the server. The directive -@code{rtems_cbs_set_parameters} can change the scheduling parameters -to avoid destroying and creating a new server again. - -@subsection Attaching Task to a Server - -If a task is attached to a server using @code{rtems_cbs_attach_thread}, -the task's computation time per period is limited by the server and -the deadline (period) of task is equal to deadline of the server which -means if you conclude a period using @code{rate_monotonic_period}, -the length of next period is always determined by the server's property. - -The task has a guaranteed bandwidth given by the server but should not -exceed it, otherwise the priority is pulled to background until the -start of next period and the @code{rtems_cbs_budget_overrun} callback -function is invoked. - -When attaching a task to server, the preemptability flag of the task -is raised, otherwise it would not be possible to control the execution -of the task. - -@subsection Detaching Task from a Server - -The directive @code{rtems_cbs_detach_thread} is just an inverse -operation to the previous one, the task continues its execution with -the initial priority. - -Preemptability of the task is restored to the initial value. - -@subsection Examples - -The following example presents a simple common use of the API. - -You can see the initialization and cleanup call here, if there are -multiple tasks in the system, it is obvious that the initialization -should be called before creating the task. - -Notice also that in this case we decided to register an overrun handler, -instead of which there could be @code{NULL}. This handler just prints -a message to terminal, what else may be done here depends on a specific -application. - -During the periodic execution, remaining budget should be watched -to avoid overrun. - -@example -void overrun_handler ( - rtems_cbs_server_id server_id -) -@{ - printk( "Budget overrun, fixing the task\n" ); - return; -@} - -rtems_task Tasks_Periodic( - rtems_task_argument argument -) -@{ - rtems_id rmid; - - rtems_cbs_server_id server_id; - rtems_cbs_parameters params; - - params.deadline = 10; - params.budget = 4; - - rtems_cbs_initialize(); - - rtems_cbs_create_server( ¶ms, &overrun_handler, &server_id ) - - rtems_cbs_attach_thread( server_id, SELF ); - - rtems_rate_monotonic_create( argument, &rmid ); - - while ( 1 ) @{ - if (rtems_rate_monotonic_period(rmid, params.deadline)==RTEMS_TIMEOUT) - break; - - /* Perform some periodic action */ - @} - - rtems_rate_monotonic_delete( rmid ); - - rtems_cbs_cleanup(); - exit( 1 ); -@} -@end example - -@section Directives - -This section details the Constant Bandwidth Server's directives. -A subsection is dedicated to each of this manager's directives -and describes the calling sequence, related constants, usage, -and status codes. - -@c -@c -@c -@page -@subsection CBS_INITIALIZE - Initialize the CBS library - -@cindex initialize the CBS library - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_initialize -@example -int rtems_cbs_initialize( void ); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - successful initialization@* -@code{@value{RPREFIX}CBS_ERROR_NO_MEMORY} - not enough memory for data@* - -@subheading DESCRIPTION: - -This routine initializes the library in terms of allocating necessary memory -for the servers. In case not enough memory is available in the system, -@code{@value{RPREFIX}CBS_ERROR_NO_MEMORY} is returned, otherwise -@code{@value{RPREFIX}CBS_OK}. - -@subheading NOTES: - -Additional memory per each server is allocated upon invocation of -@code{rtems_cbs_create_server}. - -Tasks in the system are not influenced, they still keep executing -with their initial parameters. - -@c -@c -@c -@page -@subsection CBS_CLEANUP - Cleanup the CBS library - -@cindex cleanup the CBS library - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_cleanup -@example -int rtems_cbs_cleanup( void ); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - always successful - -@subheading DESCRIPTION: - -This routine detaches all tasks from their servers, destroys all servers -and returns memory back to the system. - -@subheading NOTES: - -All tasks continue executing with their initial priorities. - -@c -@c -@c -@page -@subsection CBS_CREATE_SERVER - Create a new bandwidth server - -@cindex create a new bandwidth server - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_create_server -@example -int rtems_cbs_create_server ( - rtems_cbs_parameters *params, - rtems_cbs_budget_overrun budget_overrun_callback, - rtems_cbs_server_id *server_id -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - successfully created@* -@code{@value{RPREFIX}CBS_ERROR_NO_MEMORY} - not enough memory for data@* -@code{@value{RPREFIX}CBS_ERROR_FULL} - maximum servers exceeded@* -@code{@value{RPREFIX}CBS_ERROR_INVALID_PARAMETER} - invalid input argument@* - -@subheading DESCRIPTION: - -This routine prepares an instance of a constant bandwidth server. -The input parameter @code{rtems_cbs_parameters} specifies scheduling -parameters of the server (period and budget). If these are not valid, -@code{@value{RPREFIX}CBS_ERROR_INVALID_PARAMETER} is returned. -The @code{budget_overrun_callback} is an optional callback function, which is -invoked in case the server's budget within one period is exceeded. -Output parameter @code{server_id} becomes an id of the newly created server. -If there is not enough memory, the @code{@value{RPREFIX}CBS_ERROR_NO_MEMORY} -is returned. If the maximum server count in the system is exceeded, -@code{@value{RPREFIX}CBS_ERROR_FULL} is returned. - -@subheading NOTES: - -No task execution is being influenced so far. - -@c -@c -@c -@page -@subsection CBS_ATTACH_THREAD - Attach a thread to server - -@cindex attach a thread to server - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_attach_thread -@example -int rtems_cbs_attach_thread ( - rtems_cbs_server_id server_id, - rtems_id task_id -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - successfully attached@* -@code{@value{RPREFIX}CBS_ERROR_FULL} - server maximum tasks exceeded@* -@code{@value{RPREFIX}CBS_ERROR_INVALID_PARAMETER} - invalid input argument@* -@code{@value{RPREFIX}CBS_ERROR_NOSERVER} - server is not valid@* - -@subheading DESCRIPTION: - -Attaches a task (@code{task_id}) to a server (@code{server_id}). -The server has to be previously created. Now, the task starts -to be scheduled according to the server parameters and not -using initial priority. This implementation allows only one task -per server, if the user tries to bind another task to the same -server, @code{@value{RPREFIX}CBS_ERROR_FULL} is returned. - -@subheading NOTES: - -Tasks attached to servers become preemptible. - -@c -@c -@c -@page -@subsection CBS_DETACH_THREAD - Detach a thread from server - -@cindex detach a thread from server - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_detach_thread -@example -int rtems_cbs_detach_thread ( - rtems_cbs_server_id server_id, - rtems_id task_id -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - successfully detached@* -@code{@value{RPREFIX}CBS_ERROR_INVALID_PARAMETER} - invalid input argument@* -@code{@value{RPREFIX}CBS_ERROR_NOSERVER} - server is not valid@* - -@subheading DESCRIPTION: - -This directive detaches a thread from server. The task continues its -execution with initial priority. - -@subheading NOTES: - -The server can be reused for any other task. - -@c -@c -@c -@page -@subsection CBS_DESTROY_SERVER - Destroy a bandwidth server - -@cindex destroy a bandwidth server - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_destroy_server -@example -int rtems_cbs_destroy_server ( - rtems_cbs_server_id server_id -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - successfully destroyed@* -@code{@value{RPREFIX}CBS_ERROR_INVALID_PARAMETER} - invalid input argument@* -@code{@value{RPREFIX}CBS_ERROR_NOSERVER} - server is not valid@* - -@subheading DESCRIPTION: - -This directive destroys a server. If any task was attached to the server, -the task is detached and continues its execution according to EDF rules -with initial properties. - -@subheading NOTES: - -This again enables one more task to be created. - -@c -@c -@c -@page -@subsection CBS_GET_SERVER_ID - Get an ID of a server - -@cindex get an ID of a server - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_get_server_id -@example -int rtems_cbs_get_server_id ( - rtems_id task_id, - rtems_cbs_server_id *server_id -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - successful@* -@code{@value{RPREFIX}CBS_ERROR_NOSERVER} - server is not valid@* - -@subheading DESCRIPTION: - -This directive returns an id of server belonging to a given task. - -@c -@c -@c -@page -@subsection CBS_GET_PARAMETERS - Get scheduling parameters of a server - -@cindex get scheduling parameters of a server - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_get_parameters -@example -rtems_cbs_get_parameters ( - rtems_cbs_server_id server_id, - rtems_cbs_parameters *params -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - successful@* -@code{@value{RPREFIX}CBS_ERROR_INVALID_PARAMETER} - invalid input argument@* -@code{@value{RPREFIX}CBS_ERROR_NOSERVER} - server is not valid@* - -@subheading DESCRIPTION: - -This directive returns a structure with current scheduling parameters -of a given server (period and execution time). - -@subheading NOTES: - -It makes no difference if any task is assigned or not. - -@c -@c -@c -@page -@subsection CBS_SET_PARAMETERS - Set scheduling parameters - -@cindex set scheduling parameters - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_set_parameters -@example -int rtems_cbs_set_parameters ( - rtems_cbs_server_id server_id, - rtems_cbs_parameters *params -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - successful@* -@code{@value{RPREFIX}CBS_ERROR_INVALID_PARAMETER} - invalid input argument@* -@code{@value{RPREFIX}CBS_ERROR_NOSERVER} - server is not valid@* - -@subheading DESCRIPTION: - -This directive sets new scheduling parameters to the server. This operation -can be performed regardless of whether a task is assigned or not. -If a task is assigned, the parameters become effective imediately, therefore it -is recommended to apply the change between two subsequent periods. - -@subheading NOTES: - -There is an upper limit on both period and budget equal to (2^31)-1 ticks. - -@c -@c -@c -@page -@subsection CBS_GET_EXECUTION_TIME - Get elapsed execution time - -@cindex get elapsed execution time - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_get_execution_time -@example -int rtems_cbs_get_execution_time ( - rtems_cbs_server_id server_id, - time_t *exec_time, - time_t *abs_time -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - successful@* -@code{@value{RPREFIX}CBS_ERROR_INVALID_PARAMETER} - invalid input argument@* -@code{@value{RPREFIX}CBS_ERROR_NOSERVER} - server is not valid@* - -@subheading DESCRIPTION: - -This routine returns consumed execution time (@code{exec_time}) of a server -during the current period. - -@subheading NOTES: - -Absolute time (@code{abs_time}) not supported now. - -@c -@c -@c -@page -@subsection CBS_GET_REMAINING_BUDGET - Get remaining execution time - -@cindex get remaining execution time - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_get_remaining_budget -@example -int rtems_cbs_get_remaining_budget ( - rtems_cbs_server_id server_id, - time_t *remaining_budget -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - successful@* -@code{@value{RPREFIX}CBS_ERROR_INVALID_PARAMETER} - invalid input argument@* -@code{@value{RPREFIX}CBS_ERROR_NOSERVER} - server is not valid@* - -@subheading DESCRIPTION: - -This directive returns remaining execution time of a given server for -current period. - -@subheading NOTES: - -If the execution time approaches zero, the assigned task should finish -computations of the current period. - -@c -@c -@c -@page -@subsection CBS_GET_APPROVED_BUDGET - Get scheduler approved execution time - -@cindex get scheduler approved execution time - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_cbs_get_approved_budget -@example -int rtems_cbs_get_approved_budget ( - rtems_cbs_server_id server_id, - time_t *appr_budget -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}CBS_OK} - successful@* -@code{@value{RPREFIX}CBS_ERROR_INVALID_PARAMETER} - invalid input argument@* -@code{@value{RPREFIX}CBS_ERROR_NOSERVER} - server is not valid@* - -@subheading DESCRIPTION: - -This directive returns server's approved budget for subsequent periods. |