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

5
Last change on this file since e52906b was e52906b, checked in by Sebastian Huber <sebastian.huber@…>, on 01/09/19 at 15:14:06

Simplify SPDX-License-Identifier comment

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