diff options
author | Chris Johns <chrisj@rtems.org> | 2016-11-08 15:26:50 +1100 |
---|---|---|
committer | Chris Johns <chrisj@rtems.org> | 2016-11-08 15:28:32 +1100 |
commit | 53bb72e99669750ecbd7a418047711a21e32ac40 (patch) | |
tree | b0cd10cb72041c45696ae9540c406b83ed1e62cb /c-user/constant_bandwidth_server.rst | |
parent | pdf: Format lists for directives to sit on the next line. (diff) | |
download | rtems-docs-53bb72e99669750ecbd7a418047711a21e32ac40.tar.bz2 |
c-user: Format the directives as descriptions.
This change combined with the element list change in latex generates
a much better looking PDF.
Add a page break before each directive to like th previous versions of the
manuals.
Diffstat (limited to '')
-rw-r--r-- | c-user/constant_bandwidth_server.rst | 564 |
1 files changed, 278 insertions, 286 deletions
diff --git a/c-user/constant_bandwidth_server.rst b/c-user/constant_bandwidth_server.rst index 135dfdb..7f45e26 100644 --- a/c-user/constant_bandwidth_server.rst +++ b/c-user/constant_bandwidth_server.rst @@ -229,458 +229,450 @@ 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. +.. raw:: latex + + \clearpage + .. _rtems_cbs_initialize: CBS_INITIALIZE - Initialize the CBS library ------------------------------------------- .. index:: initialize the CBS library - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_initialize -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_initialize( void ); + int rtems_cbs_initialize( void ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_CBS_OK`` + - successful initialization + * - ``RTEMS_CBS_ERROR_NO_MEMORY`` + - not enough memory for data - * - ``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``. -**DESCRIPTION:** +NOTES: + Additional memory per each server is allocated upon invocation of + ``rtems_cbs_create_server``. -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``. + Tasks in the system are not influenced, they still keep executing with + their initial parameters. -**NOTES:** +.. raw:: latex -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. + \clearpage .. _rtems_cbs_cleanup: CBS_CLEANUP - Cleanup the CBS library ------------------------------------- .. index:: cleanup the CBS library - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_cleanup -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_cleanup( void ); + int rtems_cbs_cleanup( void ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_CBS_OK`` + - always successful - * - ``RTEMS_CBS_OK`` - - always successful +DESCRIPTION: + This routine detaches all tasks from their servers, destroys all servers + and returns memory back to the system. -**DESCRIPTION:** +NOTES: + All tasks continue executing with their initial priorities. -This routine detaches all tasks from their servers, destroys all servers and -returns memory back to the system. +.. raw:: latex -**NOTES:** - -All tasks continue executing with their initial priorities. + \clearpage .. _rtems_cbs_create_server: CBS_CREATE_SERVER - Create a new bandwidth server ------------------------------------------------- .. index:: create a new bandwidth server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_create_server -.. 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 - ); - -**DIRECTIVE STATUS CODES:** - -.. 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. - -**NOTES:** - -No task execution is being influenced so far. +CALLING SEQUENCE: + .. 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 + ); + +DIRECTIVE STATUS CODES: + .. 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. + +NOTES: + No task execution is being influenced so far. + +.. raw:: latex + + \clearpage .. _rtems_cbs_attach_thread: CBS_ATTACH_THREAD - Attach a thread to server --------------------------------------------- .. index:: attach a thread to server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_attach_thread -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_attach_thread ( - rtems_cbs_server_id server_id, - rtems_id task_id - ); + int rtems_cbs_attach_thread ( + rtems_cbs_server_id server_id, + rtems_id task_id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 - * - ``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 server, ``RTEMS_CBS_ERROR_FULL`` is returned. -**DESCRIPTION:** +NOTES: + Tasks attached to servers become preemptible. -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. +.. raw:: latex -**NOTES:** - -Tasks attached to servers become preemptible. + \clearpage .. _rtems_cbs_detach_thread: CBS_DETACH_THREAD - Detach a thread from server ----------------------------------------------- .. index:: detach a thread from server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_detach_thread -.. code-block:: c - - int rtems_cbs_detach_thread ( - rtems_cbs_server_id server_id, - rtems_id task_id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + int rtems_cbs_detach_thread ( + rtems_cbs_server_id server_id, + rtems_id task_id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. 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 + * - ``RTEMS_CBS_OK`` + - successfully detached + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid -**DESCRIPTION:** +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. -**NOTES:** +.. raw:: latex -The server can be reused for any other task. + \clearpage .. _rtems_cbs_destroy_server: CBS_DESTROY_SERVER - Destroy a bandwidth server ----------------------------------------------- .. index:: destroy a bandwidth server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_destroy_server -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_destroy_server ( - rtems_cbs_server_id server_id - ); + int rtems_cbs_destroy_server ( + rtems_cbs_server_id server_id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 - * - ``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. -**DESCRIPTION:** +NOTES: + This again enables one more task to be created. -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. +.. raw:: latex -**NOTES:** - -This again enables one more task to be created. + \clearpage .. _rtems_cbs_get_server_id: CBS_GET_SERVER_ID - Get an ID of a server ----------------------------------------- .. index:: get an ID of a server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_get_server_id -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_get_server_id ( - rtems_id task_id, - rtems_cbs_server_id *server_id - ); + int rtems_cbs_get_server_id ( + rtems_id task_id, + rtems_cbs_server_id *server_id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid - * - ``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. -**DESCRIPTION:** +.. raw:: latex -This directive returns an id of server belonging to a given task. + \clearpage .. _rtems_cbs_get_parameters: CBS_GET_PARAMETERS - Get scheduling parameters of a server ---------------------------------------------------------- .. index:: get scheduling parameters of a server - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_get_parameters -.. code-block:: c - - rtems_cbs_get_parameters ( - rtems_cbs_server_id server_id, - rtems_cbs_parameters *params - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_cbs_get_parameters ( + rtems_cbs_server_id server_id, + rtems_cbs_parameters *params + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. 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 + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid -**DESCRIPTION:** +DESCRIPTION: + This directive returns a structure with current scheduling parameters of a + given server (period and execution time). -This directive returns a structure with current scheduling parameters -of a given server (period and execution time). +NOTES: + It makes no difference if any task is assigned or not. -**NOTES:** +.. raw:: latex -It makes no difference if any task is assigned or not. + \clearpage .. _rtems_cbs_set_parameters: CBS_SET_PARAMETERS - Set scheduling parameters ---------------------------------------------- .. index:: set scheduling parameters - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_set_parameters -.. code-block:: c - - int rtems_cbs_set_parameters ( - rtems_cbs_server_id server_id, - rtems_cbs_parameters *params - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + int rtems_cbs_set_parameters ( + rtems_cbs_server_id server_id, + rtems_cbs_parameters *params + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. 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 + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid -**DESCRIPTION:** +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. -**NOTES:** +.. raw:: latex -There is an upper limit on both period and budget equal to (2^31)-1 ticks. + \clearpage .. _rtems_cbs_get_execution_time: CBS_GET_EXECUTION_TIME - Get elapsed execution time --------------------------------------------------- .. index:: get elapsed execution time - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_get_execution_time -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_get_execution_time ( - rtems_cbs_server_id server_id, - time_t *exec_time, - time_t *abs_time - ); + int rtems_cbs_get_execution_time ( + rtems_cbs_server_id server_id, + time_t *exec_time, + time_t *abs_time + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 - * - ``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. -**DESCRIPTION:** +NOTES: + Absolute time (``abs_time``) not supported now. -This routine returns consumed execution time (``exec_time``) of a server during -the current period. +.. raw:: latex -**NOTES:** - -Absolute time (``abs_time``) not supported now. + \clearpage .. _rtems_cbs_get_remaining_budget: CBS_GET_REMAINING_BUDGET - Get remaining execution time ------------------------------------------------------- .. index:: get remaining execution time - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_get_remaining_budget -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - int rtems_cbs_get_remaining_budget ( - rtems_cbs_server_id server_id, - time_t *remaining_budget - ); - -**DIRECTIVE STATUS CODES:** + int rtems_cbs_get_remaining_budget ( + rtems_cbs_server_id server_id, + time_t *remaining_budget + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. 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 + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid -**DESCRIPTION:** +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. -**NOTES:** +.. raw:: latex -If the execution time approaches zero, the assigned task should finish -computations of the current period. + \clearpage .. _rtems_cbs_get_approved_budget: CBS_GET_APPROVED_BUDGET - Get scheduler approved execution time --------------------------------------------------------------- .. index:: get scheduler approved execution time - -**CALLING SEQUENCE:** - .. index:: rtems_cbs_get_approved_budget -.. code-block:: c - - int rtems_cbs_get_approved_budget ( - rtems_cbs_server_id server_id, - time_t *appr_budget - ); - -**DIRECTIVE STATUS CODES:** +CALLING SEQUENCE: + .. code-block:: c -.. list-table:: - :class: rtems-table + int rtems_cbs_get_approved_budget ( + rtems_cbs_server_id server_id, + time_t *appr_budget + ); - * - ``RTEMS_CBS_OK`` - - successful - * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` - - invalid input argument - * - ``RTEMS_CBS_ERROR_NOSERVER`` - - server is not valid +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -**DESCRIPTION:** + * - ``RTEMS_CBS_OK`` + - successful + * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` + - invalid input argument + * - ``RTEMS_CBS_ERROR_NOSERVER`` + - server is not valid -This directive returns server's approved budget for subsequent periods. +DESCRIPTION: + This directive returns server's approved budget for subsequent periods. |