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

5
Last change on this file since 39773ce was 4da4a15, checked in by Chris Johns <chrisj@…>, on 11/09/16 at 00:42:10

c-user: Fix header levels. Minor fixes.

  • Property mode set to 100644
File size: 19.5 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
7Constant Bandwidth Server Scheduler API
8***************************************
9
10.. index:: cbs
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
43Background
44==========
45
46Constant Bandwidth Server Definitions
47-------------------------------------
48.. index:: CBS parameters
49
50.. index:: rtems_cbs_parameters
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
75Handling Periodic Tasks
76-----------------------
77.. index:: CBS periodic tasks
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
88Registering a Callback Function
89-------------------------------
90.. index:: CBS overrun handler
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
117Limitations
118-----------
119.. index:: CBS limitations
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.. _rtems_cbs_initialize:
237
238CBS_INITIALIZE - Initialize the CBS library
239-------------------------------------------
240.. index:: initialize the CBS library
241.. index:: rtems_cbs_initialize
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.. _rtems_cbs_cleanup:
275
276CBS_CLEANUP - Cleanup the CBS library
277-------------------------------------
278.. index:: cleanup the CBS library
279.. index:: rtems_cbs_cleanup
280
281CALLING SEQUENCE:
282    .. code-block:: c
283
284        int rtems_cbs_cleanup( void );
285
286DIRECTIVE STATUS CODES:
287    .. list-table::
288     :class: rtems-table
289
290     * - ``RTEMS_CBS_OK``
291       - always successful
292
293DESCRIPTION:
294    This routine detaches all tasks from their servers, destroys all servers
295    and returns memory back to the system.
296
297NOTES:
298    All tasks continue executing with their initial priorities.
299
300.. raw:: latex
301
302   \clearpage
303
304.. _rtems_cbs_create_server:
305
306CBS_CREATE_SERVER - Create a new bandwidth server
307-------------------------------------------------
308.. index:: create a new bandwidth server
309.. index:: rtems_cbs_create_server
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.. _rtems_cbs_attach_thread:
353
354CBS_ATTACH_THREAD - Attach a thread to server
355---------------------------------------------
356.. index:: attach a thread to server
357.. index:: rtems_cbs_attach_thread
358
359CALLING SEQUENCE:
360    .. code-block:: c
361
362        int rtems_cbs_attach_thread (
363            rtems_cbs_server_id server_id,
364            rtems_id            task_id
365        );
366
367DIRECTIVE STATUS CODES:
368    .. list-table::
369     :class: rtems-table
370
371     * - ``RTEMS_CBS_OK``
372       - successfully attached
373     * - ``RTEMS_CBS_ERROR_FULL``
374       - server maximum tasks exceeded
375     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
376       - invalid input argument
377     * - ``RTEMS_CBS_ERROR_NOSERVER``
378       - server is not valid
379
380DESCRIPTION:
381    Attaches a task (``task_id``) to a server (``server_id``).  The server has
382    to be previously created. Now, the task starts to be scheduled according to
383    the server parameters and not using initial priority. This implementation
384    allows only one task per server, if the user tries to bind another task to
385    the same server, ``RTEMS_CBS_ERROR_FULL`` is returned.
386
387NOTES:
388    Tasks attached to servers become preemptible.
389
390.. raw:: latex
391
392   \clearpage
393
394.. _rtems_cbs_detach_thread:
395
396CBS_DETACH_THREAD - Detach a thread from server
397-----------------------------------------------
398.. index:: detach a thread from server
399.. index:: rtems_cbs_detach_thread
400
401CALLING SEQUENCE:
402    .. code-block:: c
403
404        int rtems_cbs_detach_thread (
405            rtems_cbs_server_id server_id,
406            rtems_id            task_id
407        );
408
409DIRECTIVE STATUS CODES:
410    .. list-table::
411     :class: rtems-table
412
413     * - ``RTEMS_CBS_OK``
414       - successfully detached
415     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
416       - invalid input argument
417     * - ``RTEMS_CBS_ERROR_NOSERVER``
418       - server is not valid
419
420DESCRIPTION:
421    This directive detaches a thread from server. The task continues its
422    execution with initial priority.
423
424NOTES:
425    The server can be reused for any other task.
426
427.. raw:: latex
428
429   \clearpage
430
431.. _rtems_cbs_destroy_server:
432
433CBS_DESTROY_SERVER - Destroy a bandwidth server
434-----------------------------------------------
435.. index:: destroy a bandwidth server
436.. index:: rtems_cbs_destroy_server
437
438CALLING SEQUENCE:
439    .. code-block:: c
440
441        int rtems_cbs_destroy_server (
442            rtems_cbs_server_id server_id
443        );
444
445DIRECTIVE STATUS CODES:
446    .. list-table::
447     :class: rtems-table
448
449     * - ``RTEMS_CBS_OK``
450       - successfully destroyed
451     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
452       - invalid input argument
453     * - ``RTEMS_CBS_ERROR_NOSERVER``
454       - server is not valid
455
456DESCRIPTION:
457    This directive destroys a server. If any task was attached to the server,
458    the task is detached and continues its execution according to EDF rules
459    with initial properties.
460
461NOTES:
462    This again enables one more task to be created.
463
464.. raw:: latex
465
466   \clearpage
467
468.. _rtems_cbs_get_server_id:
469
470CBS_GET_SERVER_ID - Get an ID of a server
471-----------------------------------------
472.. index:: get an ID of a server
473.. index:: rtems_cbs_get_server_id
474
475CALLING SEQUENCE:
476    .. code-block:: c
477
478        int rtems_cbs_get_server_id (
479            rtems_id             task_id,
480            rtems_cbs_server_id *server_id
481        );
482
483DIRECTIVE STATUS CODES:
484    .. list-table::
485     :class: rtems-table
486
487     * - ``RTEMS_CBS_OK``
488       - successful
489     * - ``RTEMS_CBS_ERROR_NOSERVER``
490       - server is not valid
491
492DESCRIPTION:
493    This directive returns an id of server belonging to a given task.
494
495.. raw:: latex
496
497   \clearpage
498
499.. _rtems_cbs_get_parameters:
500
501CBS_GET_PARAMETERS - Get scheduling parameters of a server
502----------------------------------------------------------
503.. index:: get scheduling parameters of a server
504.. index:: rtems_cbs_get_parameters
505
506CALLING SEQUENCE:
507    .. code-block:: c
508
509        rtems_cbs_get_parameters (
510            rtems_cbs_server_id   server_id,
511            rtems_cbs_parameters *params
512        );
513
514DIRECTIVE STATUS CODES:
515    .. list-table::
516     :class: rtems-table
517
518     * - ``RTEMS_CBS_OK``
519       - successful
520     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
521       - invalid input argument
522     * - ``RTEMS_CBS_ERROR_NOSERVER``
523       - server is not valid
524
525DESCRIPTION:
526    This directive returns a structure with current scheduling parameters of a
527    given server (period and execution time).
528
529NOTES:
530    It makes no difference if any task is assigned or not.
531
532.. raw:: latex
533
534   \clearpage
535
536.. _rtems_cbs_set_parameters:
537
538CBS_SET_PARAMETERS - Set scheduling parameters
539----------------------------------------------
540.. index:: set scheduling parameters
541.. index:: rtems_cbs_set_parameters
542
543CALLING SEQUENCE:
544    .. code-block:: c
545
546        int rtems_cbs_set_parameters (
547            rtems_cbs_server_id   server_id,
548            rtems_cbs_parameters *params
549        );
550
551DIRECTIVE STATUS CODES:
552    .. list-table::
553     :class: rtems-table
554
555     * - ``RTEMS_CBS_OK``
556       - successful
557     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
558       - invalid input argument
559     * - ``RTEMS_CBS_ERROR_NOSERVER``
560       - server is not valid
561
562DESCRIPTION:
563    This directive sets new scheduling parameters to the server. This operation
564    can be performed regardless of whether a task is assigned or not.  If a
565    task is assigned, the parameters become effective imediately, therefore it
566    is recommended to apply the change between two subsequent periods.
567
568NOTES:
569    There is an upper limit on both period and budget equal to (2^31)-1 ticks.
570
571.. raw:: latex
572
573   \clearpage
574
575.. _rtems_cbs_get_execution_time:
576
577CBS_GET_EXECUTION_TIME - Get elapsed execution time
578---------------------------------------------------
579.. index:: get elapsed execution time
580.. index:: rtems_cbs_get_execution_time
581
582CALLING SEQUENCE:
583    .. code-block:: c
584
585        int rtems_cbs_get_execution_time (
586            rtems_cbs_server_id    server_id,
587            time_t                *exec_time,
588            time_t                *abs_time
589        );
590
591DIRECTIVE STATUS CODES:
592    .. list-table::
593     :class: rtems-table
594
595     * - ``RTEMS_CBS_OK``
596       - successful
597     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
598       - invalid input argument
599     * - ``RTEMS_CBS_ERROR_NOSERVER``
600       - server is not valid
601
602DESCRIPTION:
603    This routine returns consumed execution time (``exec_time``) of a server
604    during the current period.
605
606NOTES:
607    Absolute time (``abs_time``) not supported now.
608
609.. raw:: latex
610
611   \clearpage
612
613.. _rtems_cbs_get_remaining_budget:
614
615CBS_GET_REMAINING_BUDGET - Get remaining execution time
616-------------------------------------------------------
617.. index:: get remaining execution time
618.. index:: rtems_cbs_get_remaining_budget
619
620CALLING SEQUENCE:
621    .. code-block:: c
622
623        int rtems_cbs_get_remaining_budget (
624            rtems_cbs_server_id  server_id,
625            time_t              *remaining_budget
626        );
627
628DIRECTIVE STATUS CODES:
629    .. list-table::
630     :class: rtems-table
631
632     * - ``RTEMS_CBS_OK``
633       - successful
634     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
635       - invalid input argument
636     * - ``RTEMS_CBS_ERROR_NOSERVER``
637       - server is not valid
638
639DESCRIPTION:
640    This directive returns remaining execution time of a given server for
641    current period.
642
643NOTES:
644    If the execution time approaches zero, the assigned task should finish
645    computations of the current period.
646
647.. raw:: latex
648
649   \clearpage
650
651.. _rtems_cbs_get_approved_budget:
652
653CBS_GET_APPROVED_BUDGET - Get scheduler approved execution time
654---------------------------------------------------------------
655.. index:: get scheduler approved execution time
656.. index:: rtems_cbs_get_approved_budget
657
658CALLING SEQUENCE:
659    .. code-block:: c
660
661        int rtems_cbs_get_approved_budget (
662            rtems_cbs_server_id  server_id,
663            time_t              *appr_budget
664        );
665
666DIRECTIVE STATUS CODES:
667    .. list-table::
668     :class: rtems-table
669
670     * - ``RTEMS_CBS_OK``
671       - successful
672     * - ``RTEMS_CBS_ERROR_INVALID_PARAMETER``
673       - invalid input argument
674     * - ``RTEMS_CBS_ERROR_NOSERVER``
675       - server is not valid
676
677DESCRIPTION:
678    This directive returns server's approved budget for subsequent periods.
Note: See TracBrowser for help on using the repository browser.