From 0d86b7111e378286bd61613c363c06cec39d0538 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 18 Feb 2016 15:29:28 +1100 Subject: Clean up. --- c_user/constant_bandwidth_server.rst | 557 ++++++++++++++++++++--------------- 1 file changed, 324 insertions(+), 233 deletions(-) (limited to 'c_user/constant_bandwidth_server.rst') diff --git a/c_user/constant_bandwidth_server.rst b/c_user/constant_bandwidth_server.rst index 69e2db9..d17524e 100644 --- a/c_user/constant_bandwidth_server.rst +++ b/c_user/constant_bandwidth_server.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1989-2011. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Constant Bandwidth Server Scheduler API ####################################### @@ -6,33 +10,33 @@ Constant Bandwidth Server Scheduler API 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: +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: -- ``rtems_cbs_initialize`` - Initialize the CBS library +- rtems_cbs_initialize_ - Initialize the CBS library -- ``rtems_cbs_cleanup`` - Cleanup the CBS library +- rtems_cbs_cleanup_ - Cleanup the CBS library -- ``rtems_cbs_create_server`` - Create a new bandwidth server +- rtems_cbs_create_server_ - Create a new bandwidth server -- ``rtems_cbs_attach_thread`` - Attach a thread to server +- rtems_cbs_attach_thread_ - Attach a thread to server -- ``rtems_cbs_detach_thread`` - Detach a thread from server +- rtems_cbs_detach_thread_ - Detach a thread from server -- ``rtems_cbs_destroy_server`` - Destroy a bandwidth server +- rtems_cbs_destroy_server_ - Destroy a bandwidth server -- ``rtems_cbs_get_server_id`` - Get an ID of a server +- rtems_cbs_get_server_id_ - Get an ID of a server -- ``rtems_cbs_get_parameters`` - Get scheduling parameters of a server +- rtems_cbs_get_parameters_ - Get scheduling parameters of a server -- ``rtems_cbs_set_parameters`` - Set scheduling parameters of a server +- rtems_cbs_set_parameters_ - Set scheduling parameters of a server -- ``rtems_cbs_get_execution_time`` - Get elapsed execution time +- rtems_cbs_get_execution_time_ - Get elapsed execution time -- ``rtems_cbs_get_remaining_budget`` - Get remainig execution time +- rtems_cbs_get_remaining_budget_ - Get remainig execution time -- ``rtems_cbs_get_approved_budget`` - Get scheduler approved execution time +- rtems_cbs_get_approved_budget_ - Get scheduler approved execution time Background ========== @@ -43,71 +47,69 @@ Constant Bandwidth Server Definitions .. index:: 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 ``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``rtems_cbs_parameters`` determines the behavior of -a server. It contains ``deadline`` which is equal to period, -and ``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``rtems_cbs_server_id`` is a type denoting an id of a server -and ``rtems_id`` a type for id of tasks. +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 ``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 +``rtems_cbs_parameters`` determines the behavior of a server. It contains +``deadline`` which is equal to period, and ``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 ``rtems_cbs_server_id`` is a type denoting an id +of a server and ``rtems_id`` a type for id of tasks. Handling Periodic Tasks ----------------------- .. index:: 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 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 ``rtems_rate_monotonic_period``. Registering a Callback Function ------------------------------- .. index:: 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 -(``rtems_cbs_budget_overrun``) might be optionally registered upon -a server creation (``rtems_cbs_create_server``). +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 (``rtems_cbs_budget_overrun``) might be +optionally registered upon a server creation (``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 ``printk()`` instead of ``printf()``. +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 ``printk()`` instead of +``printf()``. + +The calling convention of the callback function is: -The calling convention of the callback function is:.. index:: rtems_asr +.. index:: rtems_asr -.. code:: c +.. code-block:: c void overrun_handler( - rtems_cbs_server_id server_id + rtems_cbs_server_id server_id ); Limitations @@ -118,17 +120,16 @@ When using this scheduler you have to keep in mind several things: - it_limitations -- In the current implementation it is possible to attach only - a single task to each server. +- In the current implementation it is possible to attach only a single task to + each server. -- 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. +- 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. Operations ========== @@ -136,36 +137,33 @@ Operations Setting up a server ------------------- -The directive ``rtems_cbs_create_server`` is used to create a new -server that is characterized by ``rtems_cbs_parameters``. You also -might want to register the ``rtems_cbs_budget_overrun`` callback -routine. After this step tasks can be attached to the server. The directive``rtems_cbs_set_parameters`` can change the scheduling parameters -to avoid destroying and creating a new server again. +The directive ``rtems_cbs_create_server`` is used to create a new server that +is characterized by ``rtems_cbs_parameters``. You also might want to register +the ``rtems_cbs_budget_overrun`` callback routine. After this step tasks can be +attached to the server. The directive ``rtems_cbs_set_parameters`` can change +the scheduling parameters to avoid destroying and creating a new server again. Attaching Task to a Server -------------------------- -If a task is attached to a server using ``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 ``rate_monotonic_period``, -the length of next period is always determined by the server's property. +If a task is attached to a server using ``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 ``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 ``rtems_cbs_budget_overrun`` callback -function is invoked. +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 ``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. +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. Detaching Task from a Server ---------------------------- -The directive ``rtems_cbs_detach_thread`` is just an inverse -operation to the previous one, the task continues its execution with -the initial priority. +The directive ``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. @@ -174,56 +172,62 @@ 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. +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 ``NULL``. This handler just prints -a message to terminal, what else may be done here depends on a specific -application. +instead of which there could be ``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. -.. code:: c +During the periodic execution, remaining budget should be watched to avoid +overrun. + +.. code-block:: c void overrun_handler ( - rtems_cbs_server_id server_id + rtems_cbs_server_id server_id ) { - printk( "Budget overrun, fixing the task\\n" ); - return; + printk( "Budget overrun, fixing the task\\n" ); + return; } + rtems_task Tasks_Periodic( - rtems_task_argument argument + 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 ); + 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 ); } 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. +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. + +.. _rtems_cbs_initialize: CBS_INITIALIZE - Initialize the CBS library ------------------------------------------- @@ -233,26 +237,35 @@ CBS_INITIALIZE - Initialize the CBS library .. index:: rtems_cbs_initialize -.. code:: c +.. code-block:: c int rtems_cbs_initialize( void ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - successful initialization -``RTEMS_CBS_ERROR_NO_MEMORY`` - not enough memory for data +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successful initialization + * - ``RTEMS_CBS_ERROR_NO_MEMORY`` + - not enough memory for data **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,``RTEMS_CBS_ERROR_NO_MEMORY`` is returned, otherwise``RTEMS_CBS_OK``. +for the servers. In case not enough memory is available in the system, +``RTEMS_CBS_ERROR_NO_MEMORY`` is returned, otherwise ``RTEMS_CBS_OK``. **NOTES:** -Additional memory per each server is allocated upon invocation of``rtems_cbs_create_server``. +Additional memory per each server is allocated upon invocation of +``rtems_cbs_create_server``. -Tasks in the system are not influenced, they still keep executing -with their initial parameters. +Tasks in the system are not influenced, they still keep executing with their +initial parameters. + +.. _rtems_cbs_cleanup: CBS_CLEANUP - Cleanup the CBS library ------------------------------------- @@ -262,23 +275,29 @@ CBS_CLEANUP - Cleanup the CBS library .. index:: rtems_cbs_cleanup -.. code:: c +.. code-block:: c int rtems_cbs_cleanup( void ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - always successful +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - always successful **DESCRIPTION:** -This routine detaches all tasks from their servers, destroys all servers -and returns memory back to the system. +This routine detaches all tasks from their servers, destroys all servers and +returns memory back to the system. **NOTES:** All tasks continue executing with their initial priorities. +.. _rtems_cbs_create_server: + CBS_CREATE_SERVER - Create a new bandwidth server ------------------------------------------------- .. index:: create a new bandwidth server @@ -287,36 +306,46 @@ CBS_CREATE_SERVER - Create a new bandwidth server .. index:: rtems_cbs_create_server -.. code:: c +.. code-block:: c int rtems_cbs_create_server ( - rtems_cbs_parameters \*params, - rtems_cbs_budget_overrun budget_overrun_callback, - rtems_cbs_server_id \*server_id + rtems_cbs_parameters *params, + rtems_cbs_budget_overrun budget_overrun_callback, + rtems_cbs_server_id *server_id ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - successfully created -``RTEMS_CBS_ERROR_NO_MEMORY`` - not enough memory for data -``RTEMS_CBS_ERROR_FULL`` - maximum servers exceeded -``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successfully created + * - ``RTEMS_CBS_ERROR_NO_MEMORY`` + - not enough memory for data + * - ``RTEMS_CBS_ERROR_FULL`` + - maximum servers exceeded + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument **DESCRIPTION:** -This routine prepares an instance of a constant bandwidth server. -The input parameter ``rtems_cbs_parameters`` specifies scheduling -parameters of the server (period and budget). If these are not valid,``RTEMS_CBS_ERROR_INVALID_PARAMETER`` is returned. -The ``budget_overrun_callback`` is an optional callback function, which is -invoked in case the server's budget within one period is exceeded. -Output parameter ``server_id`` becomes an id of the newly created server. -If there is not enough memory, the ``RTEMS_CBS_ERROR_NO_MEMORY`` -is returned. If the maximum server count in the system is exceeded,``RTEMS_CBS_ERROR_FULL`` is returned. +This routine prepares an instance of a constant bandwidth server. The input +parameter ``rtems_cbs_parameters`` specifies scheduling parameters of the +server (period and budget). If these are not valid, +``RTEMS_CBS_ERROR_INVALID_PARAMETER`` is returned. The +``budget_overrun_callback`` is an optional callback function, which is invoked +in case the server's budget within one period is exceeded. Output parameter +``server_id`` becomes an id of the newly created server. If there is not +enough memory, the ``RTEMS_CBS_ERROR_NO_MEMORY`` is returned. If the maximum +server count in the system is exceeded, ``RTEMS_CBS_ERROR_FULL`` is returned. **NOTES:** No task execution is being influenced so far. +.. _rtems_cbs_attach_thread: + CBS_ATTACH_THREAD - Attach a thread to server --------------------------------------------- .. index:: attach a thread to server @@ -325,33 +354,41 @@ CBS_ATTACH_THREAD - Attach a thread to server .. index:: rtems_cbs_attach_thread -.. code:: c +.. code-block:: c int rtems_cbs_attach_thread ( - rtems_cbs_server_id server_id, - rtems_id task_id + rtems_cbs_server_id server_id, + rtems_id task_id ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - successfully attached -``RTEMS_CBS_ERROR_FULL`` - server maximum tasks exceeded -``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument -``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successfully attached + * - ``RTEMS_CBS_ERROR_FULL`` + - server maximum tasks exceeded + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid **DESCRIPTION:** -Attaches a task (``task_id``) to a server (``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 +Attaches a task (``task_id``) to a server (``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, ``RTEMS_CBS_ERROR_FULL`` is returned. **NOTES:** Tasks attached to servers become preemptible. +.. _rtems_cbs_detach_thread: + CBS_DETACH_THREAD - Detach a thread from server ----------------------------------------------- .. index:: detach a thread from server @@ -360,28 +397,36 @@ CBS_DETACH_THREAD - Detach a thread from server .. index:: rtems_cbs_detach_thread -.. code:: c +.. code-block:: c int rtems_cbs_detach_thread ( - rtems_cbs_server_id server_id, - rtems_id task_id + rtems_cbs_server_id server_id, + rtems_id task_id ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - successfully detached -``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument -``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successfully detached + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid **DESCRIPTION:** -This directive detaches a thread from server. The task continues its -execution with initial priority. +This directive detaches a thread from server. The task continues its execution +with initial priority. **NOTES:** The server can be reused for any other task. +.. _rtems_cbs_destroy_server: + CBS_DESTROY_SERVER - Destroy a bandwidth server ----------------------------------------------- .. index:: destroy a bandwidth server @@ -390,28 +435,36 @@ CBS_DESTROY_SERVER - Destroy a bandwidth server .. index:: rtems_cbs_destroy_server -.. code:: c +.. code-block:: c int rtems_cbs_destroy_server ( - rtems_cbs_server_id server_id + rtems_cbs_server_id server_id ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - successfully destroyed -``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument -``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successfully destroyed + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid **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. +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. **NOTES:** This again enables one more task to be created. +.. _rtems_cbs_get_server_id: + CBS_GET_SERVER_ID - Get an ID of a server ----------------------------------------- .. index:: get an ID of a server @@ -420,22 +473,29 @@ CBS_GET_SERVER_ID - Get an ID of a server .. index:: rtems_cbs_get_server_id -.. code:: c +.. code-block:: c int rtems_cbs_get_server_id ( - rtems_id task_id, - rtems_cbs_server_id \*server_id + rtems_id task_id, + rtems_cbs_server_id *server_id ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - successful -``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid **DESCRIPTION:** This directive returns an id of server belonging to a given task. +.. _rtems_cbs_get_parameters: + CBS_GET_PARAMETERS - Get scheduling parameters of a server ---------------------------------------------------------- .. index:: get scheduling parameters of a server @@ -444,18 +504,24 @@ CBS_GET_PARAMETERS - Get scheduling parameters of a server .. index:: rtems_cbs_get_parameters -.. code:: c +.. code-block:: c rtems_cbs_get_parameters ( - rtems_cbs_server_id server_id, - rtems_cbs_parameters \*params + rtems_cbs_server_id server_id, + rtems_cbs_parameters *params ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - successful -``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument -``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid **DESCRIPTION:** @@ -466,6 +532,8 @@ of a given server (period and execution time). It makes no difference if any task is assigned or not. +.. _rtems_cbs_set_parameters: + CBS_SET_PARAMETERS - Set scheduling parameters ---------------------------------------------- .. index:: set scheduling parameters @@ -474,30 +542,38 @@ CBS_SET_PARAMETERS - Set scheduling parameters .. index:: rtems_cbs_set_parameters -.. code:: c +.. code-block:: c int rtems_cbs_set_parameters ( - rtems_cbs_server_id server_id, - rtems_cbs_parameters \*params + rtems_cbs_server_id server_id, + rtems_cbs_parameters *params ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - successful -``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument -``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid **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. +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. **NOTES:** There is an upper limit on both period and budget equal to (2^31)-1 ticks. +.. _rtems_cbs_get_execution_time: + CBS_GET_EXECUTION_TIME - Get elapsed execution time --------------------------------------------------- .. index:: get elapsed execution time @@ -506,29 +582,37 @@ CBS_GET_EXECUTION_TIME - Get elapsed execution time .. index:: rtems_cbs_get_execution_time -.. code:: c +.. code-block:: c int rtems_cbs_get_execution_time ( - rtems_cbs_server_id server_id, - time_t \*exec_time, - time_t \*abs_time + rtems_cbs_server_id server_id, + time_t *exec_time, + time_t *abs_time ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - successful -``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument -``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid **DESCRIPTION:** -This routine returns consumed execution time (``exec_time``) of a server -during the current period. +This routine returns consumed execution time (``exec_time``) of a server during +the current period. **NOTES:** Absolute time (``abs_time``) not supported now. +.. _rtems_cbs_get_remaining_budget: + CBS_GET_REMAINING_BUDGET - Get remaining execution time ------------------------------------------------------- .. index:: get remaining execution time @@ -537,29 +621,37 @@ CBS_GET_REMAINING_BUDGET - Get remaining execution time .. index:: rtems_cbs_get_remaining_budget -.. code:: c +.. code-block:: c int rtems_cbs_get_remaining_budget ( - rtems_cbs_server_id server_id, - time_t \*remaining_budget + rtems_cbs_server_id server_id, + time_t *remaining_budget ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - successful -``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument -``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid **DESCRIPTION:** -This directive returns remaining execution time of a given server for -current period. +This directive returns remaining execution time of a given server for current +period. **NOTES:** If the execution time approaches zero, the assigned task should finish computations of the current period. +.. _rtems_cbs_get_approved_budget: + CBS_GET_APPROVED_BUDGET - Get scheduler approved execution time --------------------------------------------------------------- .. index:: get scheduler approved execution time @@ -568,26 +660,25 @@ CBS_GET_APPROVED_BUDGET - Get scheduler approved execution time .. index:: rtems_cbs_get_approved_budget -.. code:: c +.. code-block:: c int rtems_cbs_get_approved_budget ( - rtems_cbs_server_id server_id, - time_t \*appr_budget + rtems_cbs_server_id server_id, + time_t *appr_budget ); **DIRECTIVE STATUS CODES:** -``RTEMS_CBS_OK`` - successful -``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - invalid input argument -``RTEMS_CBS_ERROR_NOSERVER`` - server is not valid +.. list-table:: + :class: rtems-table + + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid **DESCRIPTION:** This directive returns server's approved budget for subsequent periods. - -.. COMMENT: COPYRIGHT (c) 1989-2011. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - -- cgit v1.2.3