source: rtems-docs/c-user/constant_bandwidth_server.rst @ c65aeed

5
Last change on this file since c65aeed was 3384994, checked in by Chris Johns <chrisj@…>, on 11/13/17 at 02:25:18

Clean up sphinx warnings.

  • Fix minor formatting issues.
  • Fix reference the gloassary TLS using ':term:'.
  • Make sure nothing is between an anchor and the heading where ':ref:' references the anchor. This meant moving all the recently added '.. index::' entries.

Update #3232.
Update #3229.

  • Property mode set to 100644
File size: 19.6 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. COMMENT: COPYRIGHT (c) 1989-2011.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
6
7.. index:: cbs
8
9Constant Bandwidth Server Scheduler API
10***************************************
11
12Introduction
13============
14
15Unlike simple schedulers, the Constant Bandwidth Server (CBS) requires a
16special API for tasks to indicate their scheduling parameters.  The directives
17provided by the CBS API are:
18
19- rtems_cbs_initialize_ - Initialize the CBS library
20
21- rtems_cbs_cleanup_ - Cleanup the CBS library
22
23- rtems_cbs_create_server_ - Create a new bandwidth server
24
25- rtems_cbs_attach_thread_ - Attach a thread to server
26
27- rtems_cbs_detach_thread_ - Detach a thread from server
28
29- rtems_cbs_destroy_server_ - Destroy a bandwidth server
30
31- rtems_cbs_get_server_id_ - Get an ID of a server
32
33- rtems_cbs_get_parameters_ - Get scheduling parameters of a server
34
35- rtems_cbs_set_parameters_ - Set scheduling parameters of a server
36
37- rtems_cbs_get_execution_time_ - Get elapsed execution time
38
39- rtems_cbs_get_remaining_budget_ - Get remainig execution time
40
41- rtems_cbs_get_approved_budget_ - Get scheduler approved execution time
42
43.. index:: CBS parameters
44.. index:: rtems_cbs_parameters
45
46Background
47==========
48
49Constant Bandwidth Server Definitions
50-------------------------------------
51
52The Constant Bandwidth Server API enables tasks to communicate with the
53scheduler and indicate its scheduling parameters. The scheduler has to be set
54up first (by defining ``CONFIGURE_SCHEDULER_CBS`` macro).
55
56The difference to a plain EDF is the presence of servers.  It is a budget aware
57extention of the EDF scheduler, therefore, tasks attached to servers behave in
58a similar way as with EDF unless they exceed their budget.
59
60The intention of servers is reservation of a certain computation time (budget)
61of the processor for all subsequent periods. The structure
62``rtems_cbs_parameters`` determines the behavior of a server. It contains
63``deadline`` which is equal to period, and ``budget`` which is the time the
64server is allowed to spend on CPU per each period. The ratio between those two
65parameters yields the maximum percentage of the CPU the server can use
66(bandwidth). Moreover, thanks to this limitation the overall utilization of CPU
67is under control, and the sum of bandwidths of all servers in the system yields
68the overall reserved portion of processor. The rest is still available for
69ordinary tasks that are not attached to any server.
70
71In order to make the server effective to the executing tasks, tasks have to be
72attached to the servers. The ``rtems_cbs_server_id`` is a type denoting an id
73of a server and ``rtems_id`` a type for id of tasks.
74.. index:: CBS periodic tasks
75
76Handling Periodic Tasks
77-----------------------
78
79Each task's execution begins with a default background priority (see the
80chapter Scheduling Concepts to understand the concept of priorities in
81EDF). Once you decide the tasks should start periodic execution, you have two
82possibilities. Either you use only the Rate Monotonic manager which takes care
83of periodic behavior, or you declare deadline and budget using the CBS API in
84which case these properties are constant for all subsequent periods, unless you
85change them using the CBS API again. Task now only has to indicate and end of
86each period using ``rtems_rate_monotonic_period``.
87.. index:: CBS overrun handler
88
89Registering a Callback Function
90-------------------------------
91
92In case tasks attached to servers are not aware of their execution time and
93happen to exceed it, the scheduler does not guarantee execution any more and
94pulls the priority of the task to background, which would possibly lead to
95immediate preemption (if there is at least one ready task with a higher
96pirority). However, the task is not blocked but a callback function is
97invoked. The callback function (``rtems_cbs_budget_overrun``) might be
98optionally registered upon a server creation (``rtems_cbs_create_server``).
99
100This enables the user to define what should happen in case of budget
101overrun. There is obviously no space for huge operations because the priority
102is down and not real time any more, however, you still can at least in release
103resources for other tasks, restart the task or log an error information. Since
104the routine is called directly from kernel, use ``printk()`` instead of
105``printf()``.
106
107The calling convention of the callback function is:
108
109.. index:: rtems_asr
110
111.. code-block:: c
112
113    void overrun_handler(
114        rtems_cbs_server_id server_id
115    );
116.. index:: CBS limitations
117
118Limitations
119-----------
120
121When using this scheduler you have to keep in mind several things:
122
123- it_limitations
124
125- In the current implementation it is possible to attach only a single task to
126  each server.
127
128- If you have a task attached to a server and you voluntatily block it in the
129  beginning of its execution, its priority will be probably pulled to
130  background upon unblock, thus not guaranteed deadline any more. This is
131  because you are effectively raising computation time of the task. When
132  unbocking, you should be always sure that the ratio between remaining
133  computation time and remaining deadline is not higher that the utilization
134  you have agreed with the scheduler.
135
136Operations
137==========
138
139Setting up a server
140-------------------
141
142The directive ``rtems_cbs_create_server`` is used to create a new server that
143is characterized by ``rtems_cbs_parameters``. You also might want to register
144the ``rtems_cbs_budget_overrun`` callback routine. After this step tasks can be
145attached to the server. The directive ``rtems_cbs_set_parameters`` can change
146the scheduling parameters to avoid destroying and creating a new server again.
147
148Attaching Task to a Server
149--------------------------
150
151If a task is attached to a server using ``rtems_cbs_attach_thread``, the task's
152computation time per period is limited by the server and the deadline (period)
153of task is equal to deadline of the server which means if you conclude a period
154using ``rate_monotonic_period``, the length of next period is always determined
155by the server's property.
156
157The task has a guaranteed bandwidth given by the server but should not exceed
158it, otherwise the priority is pulled to background until the start of next
159period and the ``rtems_cbs_budget_overrun`` callback function is invoked.
160
161When attaching a task to server, the preemptability flag of the task is raised,
162otherwise it would not be possible to control the execution of the task.
163
164Detaching Task from a Server
165----------------------------
166
167The directive ``rtems_cbs_detach_thread`` is just an inverse operation to the
168previous one, the task continues its execution with the initial priority.
169
170Preemptability of the task is restored to the initial value.
171
172Examples
173--------
174
175The following example presents a simple common use of the API.
176
177You can see the initialization and cleanup call here, if there are multiple
178tasks in the system, it is obvious that the initialization should be called
179before creating the task.
180
181Notice also that in this case we decided to register an overrun handler,
182instead of which there could be ``NULL``. This handler just prints a message to
183terminal, what else may be done here depends on a specific application.
184
185During the periodic execution, remaining budget should be watched to avoid
186overrun.
187
188.. code-block:: c
189
190    void overrun_handler (
191        rtems_cbs_server_id server_id
192    )
193    {
194        printk( "Budget overrun, fixing the task\\n" );
195        return;
196    }
197
198    rtems_task Tasks_Periodic(
199        rtems_task_argument argument
200    )
201    {
202        rtems_id             rmid;
203        rtems_cbs_server_id  server_id;
204        rtems_cbs_parameters params;
205
206        params.deadline = 10;
207        params.budget = 4;
208
209        rtems_cbs_initialize();
210        rtems_cbs_create_server( &params, &overrun_handler, &server_id )
211        rtems_cbs_attach_thread( server_id, SELF );
212        rtems_rate_monotonic_create( argument, &rmid );
213
214        while ( 1 ) {
215            if (rtems_rate_monotonic_period(rmid, params.deadline) == RTEMS_TIMEOUT)
216                break;
217            /* Perform some periodic action */
218        }
219
220        rtems_rate_monotonic_delete( rmid );
221        rtems_cbs_cleanup();
222        exit( 1 );
223    }
224
225Directives
226==========
227
228This section details the Constant Bandwidth Server's directives.  A subsection
229is dedicated to each of this manager's directives and describes the calling
230sequence, related constants, usage, and status codes.
231
232.. raw:: latex
233
234   \clearpage
235
236.. index:: initialize the CBS library
237.. index:: rtems_cbs_initialize
238.. _rtems_cbs_initialize:
239
240CBS_INITIALIZE - Initialize the CBS library
241-------------------------------------------
242
243CALLING SEQUENCE:
244    .. code-block:: c
245
246        int rtems_cbs_initialize( void );
247
248DIRECTIVE STATUS CODES:
249    .. list-table::
250     :class: rtems-table
251
252     * - ``RTEMS_CBS_OK``
253       - successful initialization
254     * - ``RTEMS_CBS_ERROR_NO_MEMORY``
255       - not enough memory for data
256
257DESCRIPTION:
258    This routine initializes the library in terms of allocating necessary
259    memory for the servers. In case not enough memory is available in the
260    system, ``RTEMS_CBS_ERROR_NO_MEMORY`` is returned, otherwise
261    ``RTEMS_CBS_OK``.
262
263NOTES:
264    Additional memory per each server is allocated upon invocation of
265    ``rtems_cbs_create_server``.
266
267    Tasks in the system are not influenced, they still keep executing with
268    their initial parameters.
269
270.. raw:: latex
271
272   \clearpage
273
274.. index:: cleanup the CBS library
275.. index:: rtems_cbs_cleanup
276
277.. _rtems_cbs_cleanup:
278
279CBS_CLEANUP - Cleanup the CBS library
280-------------------------------------
281
282CALLING SEQUENCE:
283    .. code-block:: c
284
285        int rtems_cbs_cleanup( void );
286
287DIRECTIVE STATUS CODES:
288    .. list-table::
289     :class: rtems-table
290
291     * - ``RTEMS_CBS_OK``
292       - always successful
293
294DESCRIPTION:
295    This routine detaches all tasks from their servers, destroys all servers
296    and returns memory back to the system.
297
298NOTES:
299    All tasks continue executing with their initial priorities.
300
301.. raw:: latex
302
303   \clearpage
304
305.. index:: create a new bandwidth server
306.. index:: rtems_cbs_create_server
307
308.. _rtems_cbs_create_server:
309
310CBS_CREATE_SERVER - Create a new bandwidth server
311-------------------------------------------------
312
313CALLING SEQUENCE:
314    .. code-block:: c
315
316        int rtems_cbs_create_server (
317            rtems_cbs_parameters     *params,
318            rtems_cbs_budget_overrun  budget_overrun_callback,
319            rtems_cbs_server_id      *server_id
320        );
321
322DIRECTIVE STATUS CODES:
323    .. list-table::
324     :class: rtems-table
325
326     * - ``RTEMS_CBS_OK``
327       - successfully created
328     * - ``RTEMS_CBS_ERROR_NO_MEMORY``
329       - not enough memory for data
330     * - ``RTEMS_CBS_ERROR_FULL``
331       - maximum servers exceeded
332     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
333       - invalid input argument
334
335DESCRIPTION:
336    This routine prepares an instance of a constant bandwidth server.  The
337    input parameter ``rtems_cbs_parameters`` specifies scheduling parameters of
338    the server (period and budget). If these are not valid,
339    ``RTEMS_CBS_ERROR_INVALID_PARAMETER`` is returned.  The
340    ``budget_overrun_callback`` is an optional callback function, which is
341    invoked in case the server's budget within one period is exceeded.  Output
342    parameter ``server_id`` becomes an id of the newly created server.  If
343    there is not enough memory, the ``RTEMS_CBS_ERROR_NO_MEMORY`` is
344    returned. If the maximum server count in the system is exceeded,
345    ``RTEMS_CBS_ERROR_FULL`` is returned.
346
347NOTES:
348    No task execution is being influenced so far.
349
350.. raw:: latex
351
352   \clearpage
353
354.. index:: attach a thread to server
355.. index:: rtems_cbs_attach_thread
356
357.. _rtems_cbs_attach_thread:
358
359CBS_ATTACH_THREAD - Attach a thread to server
360---------------------------------------------
361
362CALLING SEQUENCE:
363    .. code-block:: c
364
365        int rtems_cbs_attach_thread (
366            rtems_cbs_server_id server_id,
367            rtems_id            task_id
368        );
369
370DIRECTIVE STATUS CODES:
371    .. list-table::
372     :class: rtems-table
373
374     * - ``RTEMS_CBS_OK``
375       - successfully attached
376     * - ``RTEMS_CBS_ERROR_FULL``
377       - server maximum tasks exceeded
378     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
379       - invalid input argument
380     * - ``RTEMS_CBS_ERROR_NOSERVER``
381       - server is not valid
382
383DESCRIPTION:
384    Attaches a task (``task_id``) to a server (``server_id``).  The server has
385    to be previously created. Now, the task starts to be scheduled according to
386    the server parameters and not using initial priority. This implementation
387    allows only one task per server, if the user tries to bind another task to
388    the same server, ``RTEMS_CBS_ERROR_FULL`` is returned.
389
390NOTES:
391    Tasks attached to servers become preemptible.
392
393.. raw:: latex
394
395   \clearpage
396
397.. index:: detach a thread from server
398.. index:: rtems_cbs_detach_thread
399
400.. _rtems_cbs_detach_thread:
401
402CBS_DETACH_THREAD - Detach a thread from server
403-----------------------------------------------
404
405CALLING SEQUENCE:
406    .. code-block:: c
407
408        int rtems_cbs_detach_thread (
409            rtems_cbs_server_id server_id,
410            rtems_id            task_id
411        );
412
413DIRECTIVE STATUS CODES:
414    .. list-table::
415     :class: rtems-table
416
417     * - ``RTEMS_CBS_OK``
418       - successfully detached
419     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
420       - invalid input argument
421     * - ``RTEMS_CBS_ERROR_NOSERVER``
422       - server is not valid
423
424DESCRIPTION:
425    This directive detaches a thread from server. The task continues its
426    execution with initial priority.
427
428NOTES:
429    The server can be reused for any other task.
430
431.. raw:: latex
432
433   \clearpage
434
435.. index:: destroy a bandwidth server
436.. index:: rtems_cbs_destroy_server
437
438.. _rtems_cbs_destroy_server:
439
440CBS_DESTROY_SERVER - Destroy a bandwidth server
441-----------------------------------------------
442
443CALLING SEQUENCE:
444    .. code-block:: c
445
446        int rtems_cbs_destroy_server (
447            rtems_cbs_server_id server_id
448        );
449
450DIRECTIVE STATUS CODES:
451    .. list-table::
452     :class: rtems-table
453
454     * - ``RTEMS_CBS_OK``
455       - successfully destroyed
456     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
457       - invalid input argument
458     * - ``RTEMS_CBS_ERROR_NOSERVER``
459       - server is not valid
460
461DESCRIPTION:
462    This directive destroys a server. If any task was attached to the server,
463    the task is detached and continues its execution according to EDF rules
464    with initial properties.
465
466NOTES:
467    This again enables one more task to be created.
468
469.. raw:: latex
470
471   \clearpage
472
473.. index:: get an ID of a server
474.. index:: rtems_cbs_get_server_id
475
476.. _rtems_cbs_get_server_id:
477
478CBS_GET_SERVER_ID - Get an ID of a server
479-----------------------------------------
480
481CALLING SEQUENCE:
482    .. code-block:: c
483
484        int rtems_cbs_get_server_id (
485            rtems_id             task_id,
486            rtems_cbs_server_id *server_id
487        );
488
489DIRECTIVE STATUS CODES:
490    .. list-table::
491     :class: rtems-table
492
493     * - ``RTEMS_CBS_OK``
494       - successful
495     * - ``RTEMS_CBS_ERROR_NOSERVER``
496       - server is not valid
497
498DESCRIPTION:
499    This directive returns an id of server belonging to a given task.
500
501.. raw:: latex
502
503   \clearpage
504
505.. index:: get scheduling parameters of a server
506.. index:: rtems_cbs_get_parameters
507
508.. _rtems_cbs_get_parameters:
509
510CBS_GET_PARAMETERS - Get scheduling parameters of a server
511----------------------------------------------------------
512
513CALLING SEQUENCE:
514    .. code-block:: c
515
516        rtems_cbs_get_parameters (
517            rtems_cbs_server_id   server_id,
518            rtems_cbs_parameters *params
519        );
520
521DIRECTIVE STATUS CODES:
522    .. list-table::
523     :class: rtems-table
524
525     * - ``RTEMS_CBS_OK``
526       - successful
527     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
528       - invalid input argument
529     * - ``RTEMS_CBS_ERROR_NOSERVER``
530       - server is not valid
531
532DESCRIPTION:
533    This directive returns a structure with current scheduling parameters of a
534    given server (period and execution time).
535
536NOTES:
537    It makes no difference if any task is assigned or not.
538
539.. raw:: latex
540
541   \clearpage
542
543.. index:: set scheduling parameters
544.. index:: rtems_cbs_set_parameters
545
546.. _rtems_cbs_set_parameters:
547
548CBS_SET_PARAMETERS - Set scheduling parameters
549----------------------------------------------
550
551CALLING SEQUENCE:
552    .. code-block:: c
553
554        int rtems_cbs_set_parameters (
555            rtems_cbs_server_id   server_id,
556            rtems_cbs_parameters *params
557        );
558
559DIRECTIVE STATUS CODES:
560    .. list-table::
561     :class: rtems-table
562
563     * - ``RTEMS_CBS_OK``
564       - successful
565     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
566       - invalid input argument
567     * - ``RTEMS_CBS_ERROR_NOSERVER``
568       - server is not valid
569
570DESCRIPTION:
571    This directive sets new scheduling parameters to the server. This operation
572    can be performed regardless of whether a task is assigned or not.  If a
573    task is assigned, the parameters become effective imediately, therefore it
574    is recommended to apply the change between two subsequent periods.
575
576NOTES:
577    There is an upper limit on both period and budget equal to (2^31)-1 ticks.
578
579.. raw:: latex
580
581   \clearpage
582
583.. index:: get elapsed execution time
584.. index:: rtems_cbs_get_execution_time
585
586.. _rtems_cbs_get_execution_time:
587
588CBS_GET_EXECUTION_TIME - Get elapsed execution time
589---------------------------------------------------
590
591CALLING SEQUENCE:
592    .. code-block:: c
593
594        int rtems_cbs_get_execution_time (
595            rtems_cbs_server_id    server_id,
596            time_t                *exec_time,
597            time_t                *abs_time
598        );
599
600DIRECTIVE STATUS CODES:
601    .. list-table::
602     :class: rtems-table
603
604     * - ``RTEMS_CBS_OK``
605       - successful
606     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
607       - invalid input argument
608     * - ``RTEMS_CBS_ERROR_NOSERVER``
609       - server is not valid
610
611DESCRIPTION:
612    This routine returns consumed execution time (``exec_time``) of a server
613    during the current period.
614
615NOTES:
616    Absolute time (``abs_time``) not supported now.
617
618.. raw:: latex
619
620   \clearpage
621
622.. index:: get remaining execution time
623.. index:: rtems_cbs_get_remaining_budget
624
625.. _rtems_cbs_get_remaining_budget:
626
627CBS_GET_REMAINING_BUDGET - Get remaining execution time
628-------------------------------------------------------
629
630CALLING SEQUENCE:
631    .. code-block:: c
632
633        int rtems_cbs_get_remaining_budget (
634            rtems_cbs_server_id  server_id,
635            time_t              *remaining_budget
636        );
637
638DIRECTIVE STATUS CODES:
639    .. list-table::
640     :class: rtems-table
641
642     * - ``RTEMS_CBS_OK``
643       - successful
644     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
645       - invalid input argument
646     * - ``RTEMS_CBS_ERROR_NOSERVER``
647       - server is not valid
648
649DESCRIPTION:
650    This directive returns remaining execution time of a given server for
651    current period.
652
653NOTES:
654    If the execution time approaches zero, the assigned task should finish
655    computations of the current period.
656
657.. raw:: latex
658
659   \clearpage
660
661.. index:: get scheduler approved execution time
662.. index:: rtems_cbs_get_approved_budget
663
664.. _rtems_cbs_get_approved_budget:
665
666CBS_GET_APPROVED_BUDGET - Get scheduler approved execution time
667---------------------------------------------------------------
668
669CALLING SEQUENCE:
670    .. code-block:: c
671
672        int rtems_cbs_get_approved_budget (
673            rtems_cbs_server_id  server_id,
674            time_t              *appr_budget
675        );
676
677DIRECTIVE STATUS CODES:
678    .. list-table::
679     :class: rtems-table
680
681     * - ``RTEMS_CBS_OK``
682       - successful
683     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
684       - invalid input argument
685     * - ``RTEMS_CBS_ERROR_NOSERVER``
686       - server is not valid
687
688DESCRIPTION:
689    This directive returns server's approved budget for subsequent periods.
Note: See TracBrowser for help on using the repository browser.