source: rtems-docs/c-user/config/general.rst @ 657f744

Last change on this file since 657f744 was 657f744, checked in by Sebastian Huber <sebastian.huber@…>, on 08/11/22 at 06:26:30

c-user: Update OAR copyright and reformat

These files are generated by a script.

  • Property mode set to 100644
File size: 29.1 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
4.. Copyright (C) 1988, 2022 On-Line Applications Research Corporation (OAR)
5
6.. This file is part of the RTEMS quality process and was automatically
7.. generated.  If you find something that needs to be fixed or
8.. worded better please post a report or patch to an RTEMS mailing list
9.. or raise a bug report:
10..
11.. https://www.rtems.org/bugs.html
12..
13.. For information on updating and regenerating please refer to the How-To
14.. section in the Software Requirements Engineering chapter of the
15.. RTEMS Software Engineering manual.  The manual is provided as a part of
16.. a release.  For development sources please refer to the online
17.. documentation at:
18..
19.. https://docs.rtems.org
20
21.. Generated from spec:/acfg/if/group-general
22
23General System Configuration
24============================
25
26This section describes general system configuration options.
27
28.. Generated from spec:/acfg/if/dirty-memory
29
30.. raw:: latex
31
32    \clearpage
33
34.. index:: CONFIGURE_DIRTY_MEMORY
35
36.. _CONFIGURE_DIRTY_MEMORY:
37
38CONFIGURE_DIRTY_MEMORY
39----------------------
40
41.. rubric:: CONSTANT:
42
43``CONFIGURE_DIRTY_MEMORY``
44
45.. rubric:: OPTION TYPE:
46
47This configuration option is a boolean feature define.
48
49.. rubric:: DEFAULT CONFIGURATION:
50
51If this configuration option is undefined, then the described feature is not
52enabled.
53
54.. rubric:: DESCRIPTION:
55
56In case this configuration option is defined, then the memory areas used for
57the RTEMS Workspace and the C Program Heap are dirtied with a ``0xCF`` byte
58pattern during system initialization.
59
60.. rubric:: NOTES:
61
62Dirtying memory can add significantly to system initialization time.  It may
63assist in finding code that incorrectly assumes the contents of free memory
64areas is cleared to zero during system initialization.  In case
65:ref:`CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY` is also defined, then the
66memory is first dirtied and then zeroed.
67
68See also :ref:`CONFIGURE_MALLOC_DIRTY`.
69
70.. Generated from spec:/acfg/if/disable-newlib-reentrancy
71
72.. raw:: latex
73
74    \clearpage
75
76.. index:: CONFIGURE_DISABLE_NEWLIB_REENTRANCY
77
78.. _CONFIGURE_DISABLE_NEWLIB_REENTRANCY:
79
80CONFIGURE_DISABLE_NEWLIB_REENTRANCY
81-----------------------------------
82
83.. rubric:: CONSTANT:
84
85``CONFIGURE_DISABLE_NEWLIB_REENTRANCY``
86
87.. rubric:: OPTION TYPE:
88
89This configuration option is a boolean feature define.
90
91.. rubric:: DEFAULT CONFIGURATION:
92
93If this configuration option is undefined, then the described feature is not
94enabled.
95
96.. rubric:: DESCRIPTION:
97
98In case this configuration option is defined, then the Newlib reentrancy
99support per thread is disabled and a global reentrancy structure is used.
100
101.. rubric:: NOTES:
102
103You can enable this option to reduce the size of the :term:`TCB`.  Use this
104option with care, since it can lead to race conditions and undefined system
105behaviour.  For example, :c:macro:`errno` is no longer a thread-local
106variable if this option is enabled.
107
108.. Generated from spec:/acfg/if/executive-ram-size
109
110.. raw:: latex
111
112    \clearpage
113
114.. index:: CONFIGURE_EXECUTIVE_RAM_SIZE
115
116.. _CONFIGURE_EXECUTIVE_RAM_SIZE:
117
118CONFIGURE_EXECUTIVE_RAM_SIZE
119----------------------------
120
121.. rubric:: CONSTANT:
122
123``CONFIGURE_EXECUTIVE_RAM_SIZE``
124
125.. rubric:: OPTION TYPE:
126
127This configuration option is an integer define.
128
129.. rubric:: DEFAULT VALUE:
130
131If this configuration option is undefined, then the RTEMS Workspace and task
132stack space size is calculated by ``<rtems/confdefs.h>`` based on the values
133configuration options.
134
135.. rubric:: DESCRIPTION:
136
137The value of this configuration option defines the RTEMS Workspace size in
138bytes.
139
140.. rubric:: NOTES:
141
142This is an advanced configuration option.  Use it only if you know exactly
143what you are doing.
144
145.. rubric:: CONSTRAINTS:
146
147The following constraints apply to this configuration option:
148
149* The value of the configuration option shall be greater than or equal to zero.
150
151* The value of the configuration option shall be less than or equal to
152  `UINTPTR_MAX <https://en.cppreference.com/w/c/types/integer>`_.
153
154* The value of the configuration option shall be less than or equal to a
155  BSP-specific and application-specific value which depends on the size of the
156  memory available to the application.
157
158.. Generated from spec:/acfg/if/extra-task-stacks
159
160.. raw:: latex
161
162    \clearpage
163
164.. index:: CONFIGURE_EXTRA_TASK_STACKS
165.. index:: memory for task tasks
166
167.. _CONFIGURE_EXTRA_TASK_STACKS:
168
169CONFIGURE_EXTRA_TASK_STACKS
170---------------------------
171
172.. rubric:: CONSTANT:
173
174``CONFIGURE_EXTRA_TASK_STACKS``
175
176.. rubric:: OPTION TYPE:
177
178This configuration option is an integer define.
179
180.. rubric:: DEFAULT VALUE:
181
182The default value is 0.
183
184.. rubric:: DESCRIPTION:
185
186The value of this configuration option defines the number of bytes the
187applications wishes to add to the task stack requirements calculated by
188``<rtems/confdefs.h>``.
189
190.. rubric:: NOTES:
191
192This parameter is very important.  If the application creates tasks with
193stacks larger then the minimum, then that memory is **not** accounted for by
194``<rtems/confdefs.h>``.
195
196.. rubric:: CONSTRAINTS:
197
198The following constraints apply to this configuration option:
199
200* The value of the configuration option shall be greater than or equal to zero.
201
202* The value of the configuration option shall be small enough so that the task
203  stack space calculation carried out by ``<rtems/confdefs.h>`` does not
204  overflow an integer of type `uintptr_t
205  <https://en.cppreference.com/w/c/types/integer>`_.
206
207.. Generated from spec:/acfg/if/initial-extensions
208
209.. raw:: latex
210
211    \clearpage
212
213.. index:: CONFIGURE_INITIAL_EXTENSIONS
214
215.. _CONFIGURE_INITIAL_EXTENSIONS:
216
217CONFIGURE_INITIAL_EXTENSIONS
218----------------------------
219
220.. rubric:: CONSTANT:
221
222``CONFIGURE_INITIAL_EXTENSIONS``
223
224.. rubric:: OPTION TYPE:
225
226This configuration option is an initializer define.
227
228.. rubric:: DEFAULT VALUE:
229
230The default value is the empty list.
231
232.. rubric:: DESCRIPTION:
233
234The value of this configuration option is used to initialize the table of
235initial user extensions.
236
237.. rubric:: NOTES:
238
239The value of this configuration option is placed before the entries of
240:ref:`BSP_INITIAL_EXTENSION` and after the entries of all other initial
241user extensions.
242
243.. rubric:: CONSTRAINTS:
244
245The value of the configuration option shall be a list of initializers for
246structures of type :c:type:`rtems_extensions_table`.
247
248.. Generated from spec:/acfg/if/interrupt-stack-size
249
250.. raw:: latex
251
252    \clearpage
253
254.. index:: CONFIGURE_INTERRUPT_STACK_SIZE
255.. index:: interrupt stack size
256
257.. _CONFIGURE_INTERRUPT_STACK_SIZE:
258
259CONFIGURE_INTERRUPT_STACK_SIZE
260------------------------------
261
262.. rubric:: CONSTANT:
263
264``CONFIGURE_INTERRUPT_STACK_SIZE``
265
266.. rubric:: OPTION TYPE:
267
268This configuration option is an integer define.
269
270.. rubric:: DEFAULT VALUE:
271
272The default value is :ref:`BSP_INTERRUPT_STACK_SIZE` in case it is defined,
273otherwise the default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`.
274
275.. rubric:: DESCRIPTION:
276
277The value of this configuration option defines the size of an interrupt stack
278in bytes.
279
280.. rubric:: NOTES:
281
282There is one interrupt stack available for each configured processor
283(:ref:`CONFIGURE_MAXIMUM_PROCESSORS`).  The interrupt stack areas are
284statically allocated in a special linker section (``.rtemsstack.interrupt``).
285The placement of this linker section is BSP-specific.
286
287Some BSPs use the interrupt stack as the initialization stack which is used
288to perform the sequential system initialization before the multithreading
289is started.
290
291The interrupt stacks are covered by the stack checker, see
292:ref:`CONFIGURE_STACK_CHECKER_ENABLED`.  However, using a too small interrupt stack
293size may still result in undefined behaviour.
294
295In releases before RTEMS 5.1 the default value was
296:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of
297:c:macro:`CPU_STACK_MINIMUM_SIZE`.
298
299.. rubric:: CONSTRAINTS:
300
301The following constraints apply to this configuration option:
302
303* The value of the configuration option shall be greater than or equal to a
304  BSP-specific and application-specific minimum value.
305
306* The value of the configuration option shall be small enough so that the
307  interrupt stack area calculation carried out by ``<rtems/confdefs.h>`` does
308  not overflow an integer of type `size_t
309  <https://en.cppreference.com/w/c/types/size_t>`_.
310
311* The value of the configuration option shall be aligned according to
312  :c:macro:`CPU_INTERRUPT_STACK_ALIGNMENT`.
313
314.. Generated from spec:/acfg/if/malloc-dirty
315
316.. raw:: latex
317
318    \clearpage
319
320.. index:: CONFIGURE_MALLOC_DIRTY
321
322.. _CONFIGURE_MALLOC_DIRTY:
323
324CONFIGURE_MALLOC_DIRTY
325----------------------
326
327.. rubric:: CONSTANT:
328
329``CONFIGURE_MALLOC_DIRTY``
330
331.. rubric:: OPTION TYPE:
332
333This configuration option is a boolean feature define.
334
335.. rubric:: DEFAULT CONFIGURATION:
336
337If this configuration option is undefined, then the described feature is not
338enabled.
339
340.. rubric:: DESCRIPTION:
341
342In case this configuration option is defined, then each memory area returned
343by C Program Heap allocator functions such as :c:func:`malloc` is dirtied
344with a ``0xCF`` byte pattern before it is handed over to the application.
345
346.. rubric:: NOTES:
347
348The dirtying performed by this option is carried out for each successful
349memory allocation from the C Program Heap in contrast to
350:ref:`CONFIGURE_DIRTY_MEMORY` which dirties the memory only once during the
351system initialization.
352
353.. Generated from spec:/acfg/if/max-file-descriptors
354
355.. raw:: latex
356
357    \clearpage
358
359.. index:: CONFIGURE_MAXIMUM_FILE_DESCRIPTORS
360.. index:: maximum file descriptors
361
362.. _CONFIGURE_MAXIMUM_FILE_DESCRIPTORS:
363
364CONFIGURE_MAXIMUM_FILE_DESCRIPTORS
365----------------------------------
366
367.. rubric:: CONSTANT:
368
369``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS``
370
371.. rubric:: OPTION TYPE:
372
373This configuration option is an integer define.
374
375.. rubric:: DEFAULT VALUE:
376
377The default value is 3.
378
379.. rubric:: DESCRIPTION:
380
381The value of this configuration option defines the maximum number of file
382like objects that can be concurrently open.
383
384.. rubric:: NOTES:
385
386The default value of three file descriptors allows RTEMS to support standard
387input, output, and error I/O streams on :file:`/dev/console`.
388
389.. rubric:: CONSTRAINTS:
390
391The following constraints apply to this configuration option:
392
393* The value of the configuration option shall be greater than or equal to zero.
394
395* The value of the configuration option shall be less than or equal to
396  `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_.
397
398* The value of the configuration option shall be less than or equal to a
399  BSP-specific and application-specific value which depends on the size of the
400  memory available to the application.
401
402.. Generated from spec:/acfg/if/max-processors
403
404.. raw:: latex
405
406    \clearpage
407
408.. index:: CONFIGURE_MAXIMUM_PROCESSORS
409
410.. _CONFIGURE_MAXIMUM_PROCESSORS:
411
412CONFIGURE_MAXIMUM_PROCESSORS
413----------------------------
414
415.. rubric:: CONSTANT:
416
417``CONFIGURE_MAXIMUM_PROCESSORS``
418
419.. rubric:: OPTION TYPE:
420
421This configuration option is an integer define.
422
423.. rubric:: DEFAULT VALUE:
424
425The default value is 1.
426
427.. rubric:: DESCRIPTION:
428
429The value of this configuration option defines the maximum number of
430processors an application intends to use.  The number of actually available
431processors depends on the hardware and may be less.  It is recommended to use
432the smallest value suitable for the application in order to save memory.
433Each processor needs an IDLE task stack and interrupt stack for example.
434
435.. rubric:: NOTES:
436
437If there are more processors available than configured, the rest will be
438ignored.
439
440This configuration option is only evaluated in SMP configurations of RTEMS
441(e.g. RTEMS was built with the SMP build configuration option enabled).
442In all other configurations it has no effect.
443
444.. rubric:: CONSTRAINTS:
445
446The following constraints apply to this configuration option:
447
448* The value of the configuration option shall be greater than or equal to one.
449
450* The value of the configuration option shall be less than or equal to
451  :c:macro:`CPU_MAXIMUM_PROCESSORS`.
452
453.. Generated from spec:/acfg/if/max-thread-name-size
454
455.. raw:: latex
456
457    \clearpage
458
459.. index:: CONFIGURE_MAXIMUM_THREAD_NAME_SIZE
460.. index:: maximum thread name size
461
462.. _CONFIGURE_MAXIMUM_THREAD_NAME_SIZE:
463
464CONFIGURE_MAXIMUM_THREAD_NAME_SIZE
465----------------------------------
466
467.. rubric:: CONSTANT:
468
469``CONFIGURE_MAXIMUM_THREAD_NAME_SIZE``
470
471.. rubric:: OPTION TYPE:
472
473This configuration option is an integer define.
474
475.. rubric:: DEFAULT VALUE:
476
477The default value is 16.
478
479.. rubric:: DESCRIPTION:
480
481The value of this configuration option defines the maximum thread name size
482including the terminating ``NUL`` character.
483
484.. rubric:: NOTES:
485
486The default value was chosen for Linux compatibility, see
487`pthread_setname_np() <http://man7.org/linux/man-pages/man3/pthread_setname_np.3.html>`_.
488
489The size of the thread control block is increased by the maximum thread name
490size.
491
492This configuration option is available since RTEMS 5.1.
493
494.. rubric:: CONSTRAINTS:
495
496The following constraints apply to this configuration option:
497
498* The value of the configuration option shall be greater than or equal to zero.
499
500* The value of the configuration option shall be less than or equal to
501  `SIZE_MAX <https://en.cppreference.com/w/c/types/limits>`_.
502
503* The value of the configuration option shall be less than or equal to a
504  BSP-specific and application-specific value which depends on the size of the
505  memory available to the application.
506
507.. Generated from spec:/acfg/if/memory-overhead
508
509.. raw:: latex
510
511    \clearpage
512
513.. index:: CONFIGURE_MEMORY_OVERHEAD
514
515.. _CONFIGURE_MEMORY_OVERHEAD:
516
517CONFIGURE_MEMORY_OVERHEAD
518-------------------------
519
520.. rubric:: CONSTANT:
521
522``CONFIGURE_MEMORY_OVERHEAD``
523
524.. rubric:: OPTION TYPE:
525
526This configuration option is an integer define.
527
528.. rubric:: DEFAULT VALUE:
529
530The default value is 0.
531
532.. rubric:: DESCRIPTION:
533
534The value of this configuration option defines the number of kilobytes the
535application wishes to add to the RTEMS Workspace size calculated by
536``<rtems/confdefs.h>``.
537
538.. rubric:: NOTES:
539
540This configuration option should only be used when it is suspected that a bug
541in ``<rtems/confdefs.h>`` has resulted in an underestimation.  Typically the
542memory allocation will be too low when an application does not account for
543all message queue buffers or task stacks, see
544:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`.
545
546.. rubric:: CONSTRAINTS:
547
548The following constraints apply to this configuration option:
549
550* The value of the configuration option shall be greater than or equal to zero.
551
552* The value of the configuration option shall be less than or equal to a
553  BSP-specific and application-specific value which depends on the size of the
554  memory available to the application.
555
556* The value of the configuration option shall be small enough so that the RTEMS
557  Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not
558  overflow an integer of type `uintptr_t
559  <https://en.cppreference.com/w/c/types/integer>`_.
560
561.. Generated from spec:/acfg/if/message-buffer-memory
562
563.. raw:: latex
564
565    \clearpage
566
567.. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY
568.. index:: configure message queue buffer memory
569.. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE
570.. index:: memory for a single message queue's buffers
571
572.. _CONFIGURE_MESSAGE_BUFFER_MEMORY:
573
574CONFIGURE_MESSAGE_BUFFER_MEMORY
575-------------------------------
576
577.. rubric:: CONSTANT:
578
579``CONFIGURE_MESSAGE_BUFFER_MEMORY``
580
581.. rubric:: OPTION TYPE:
582
583This configuration option is an integer define.
584
585.. rubric:: DEFAULT VALUE:
586
587The default value is 0.
588
589.. rubric:: DESCRIPTION:
590
591The value of this configuration option defines the number of bytes reserved
592for message queue buffers in the RTEMS Workspace.
593
594.. rubric:: NOTES:
595
596The configuration options :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and
597:ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES` define only how many message
598queues can be created by the application.  The memory for the message
599buffers is configured by this option.  For each message queue you have to
600reserve some memory for the message buffers.  The size depends on the
601maximum number of pending messages and the maximum size of the messages of
602a message queue.  Use the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` macro
603to specify the message buffer memory for each message queue and sum them up
604to define the value for ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``.
605
606The interface for the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help
607macro is as follows:
608
609.. code-block:: c
610
611    CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( max_messages, max_msg_size )
612
613Where ``max_messages`` is the maximum number of pending messages and
614``max_msg_size`` is the maximum size in bytes of the messages of the
615corresponding message queue.  Both parameters shall be compile time
616constants.  Not using this help macro (e.g. just using
617``max_messages * max_msg_size``) may result in an underestimate of the
618RTEMS Workspace size.
619
620The following example illustrates how the
621``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help macro can be used to assist in
622calculating the message buffer memory required.  In this example, there are
623two message queues used in this application.  The first message queue has a
624maximum of 24 pending messages with the message structure defined by the
625type ``one_message_type``.  The other message queue has a maximum of 500
626pending messages with the message structure defined by the type
627``other_message_type``.
628
629.. code-block:: c
630
631    #define CONFIGURE_MESSAGE_BUFFER_MEMORY ( \
632        CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \
633          24, \
634          sizeof( one_message_type ) \
635        ) \
636        + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \
637          500, \
638          sizeof( other_message_type ) \
639        ) \
640      )
641
642.. rubric:: CONSTRAINTS:
643
644The following constraints apply to this configuration option:
645
646* The value of the configuration option shall be greater than or equal to zero.
647
648* The value of the configuration option shall be less than or equal to a
649  BSP-specific and application-specific value which depends on the size of the
650  memory available to the application.
651
652* The value of the configuration option shall be small enough so that the RTEMS
653  Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not
654  overflow an integer of type `uintptr_t
655  <https://en.cppreference.com/w/c/types/integer>`_.
656
657.. Generated from spec:/acfg/if/microseconds-per-tick
658
659.. raw:: latex
660
661    \clearpage
662
663.. index:: CONFIGURE_MICROSECONDS_PER_TICK
664.. index:: clock tick quantum
665.. index:: tick quantum
666
667.. _CONFIGURE_MICROSECONDS_PER_TICK:
668
669CONFIGURE_MICROSECONDS_PER_TICK
670-------------------------------
671
672.. rubric:: CONSTANT:
673
674``CONFIGURE_MICROSECONDS_PER_TICK``
675
676.. rubric:: OPTION TYPE:
677
678This configuration option is an integer define.
679
680.. rubric:: DEFAULT VALUE:
681
682The default value is 10000.
683
684.. rubric:: DESCRIPTION:
685
686The value of this configuration option defines the length of time in
687microseconds between clock ticks (clock tick quantum).
688
689When the clock tick quantum value is too low, the system will spend so much
690time processing clock ticks that it does not have processing time available
691to perform application work. In this case, the system will become
692unresponsive.
693
694The lowest practical time quantum varies widely based upon the speed of the
695target hardware and the architectural overhead associated with
696interrupts. In general terms, you do not want to configure it lower than is
697needed for the application.
698
699The clock tick quantum should be selected such that it all blocking and
700delay times in the application are evenly divisible by it. Otherwise,
701rounding errors will be introduced which may negatively impact the
702application.
703
704.. rubric:: NOTES:
705
706This configuration option has no impact if the Clock Driver is not
707configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`.
708
709There may be Clock Driver specific limits on the resolution or maximum value
710of a clock tick quantum.
711
712.. rubric:: CONSTRAINTS:
713
714The following constraints apply to this configuration option:
715
716* The value of the configuration option shall be greater than or equal to a
717  value defined by the :term:`Clock Driver`.
718
719* The value of the configuration option shall be less than or equal to a value
720  defined by the :term:`Clock Driver`.
721
722* The resulting clock ticks per second should be an integer.
723
724.. Generated from spec:/acfg/if/min-task-stack-size
725
726.. raw:: latex
727
728    \clearpage
729
730.. index:: CONFIGURE_MINIMUM_TASK_STACK_SIZE
731.. index:: minimum task stack size
732
733.. _CONFIGURE_MINIMUM_TASK_STACK_SIZE:
734
735CONFIGURE_MINIMUM_TASK_STACK_SIZE
736---------------------------------
737
738.. rubric:: CONSTANT:
739
740``CONFIGURE_MINIMUM_TASK_STACK_SIZE``
741
742.. rubric:: OPTION TYPE:
743
744This configuration option is an integer define.
745
746.. rubric:: DEFAULT VALUE:
747
748The default value is :c:macro:`CPU_STACK_MINIMUM_SIZE`.
749
750.. rubric:: DESCRIPTION:
751
752The value of this configuration option defines the minimum stack size in
753bytes for every user task or thread in the system.
754
755.. rubric:: NOTES:
756
757Adjusting this parameter should be done with caution.  Examining the actual
758stack usage using the stack checker usage reporting facility is recommended
759(see also :ref:`CONFIGURE_STACK_CHECKER_ENABLED`).
760
761This parameter can be used to lower the minimum from that recommended. This
762can be used in low memory systems to reduce memory consumption for
763stacks. However, this shall be done with caution as it could increase the
764possibility of a blown task stack.
765
766This parameter can be used to increase the minimum from that
767recommended. This can be used in higher memory systems to reduce the risk
768of stack overflow without performing analysis on actual consumption.
769
770By default, this configuration parameter defines also the minimum stack
771size of POSIX threads.  This can be changed with the
772:ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`
773configuration option.
774
775In releases before RTEMS 5.1 the ``CONFIGURE_MINIMUM_TASK_STACK_SIZE`` was
776used to define the default value of :ref:`CONFIGURE_INTERRUPT_STACK_SIZE`.
777
778.. rubric:: CONSTRAINTS:
779
780The following constraints apply to this configuration option:
781
782* The value of the configuration option shall be small enough so that the task
783  stack space calculation carried out by ``<rtems/confdefs.h>`` does not
784  overflow an integer of type `uintptr_t
785  <https://en.cppreference.com/w/c/types/integer>`_.
786
787* The value of the configuration option shall be greater than or equal to a
788  BSP-specific and application-specific minimum value.
789
790.. Generated from spec:/acfg/if/stack-checker-enabled
791
792.. raw:: latex
793
794    \clearpage
795
796.. index:: CONFIGURE_STACK_CHECKER_ENABLED
797
798.. _CONFIGURE_STACK_CHECKER_ENABLED:
799
800CONFIGURE_STACK_CHECKER_ENABLED
801-------------------------------
802
803.. rubric:: CONSTANT:
804
805``CONFIGURE_STACK_CHECKER_ENABLED``
806
807.. rubric:: OPTION TYPE:
808
809This configuration option is a boolean feature define.
810
811.. rubric:: DEFAULT CONFIGURATION:
812
813If this configuration option is undefined, then the described feature is not
814enabled.
815
816.. rubric:: DESCRIPTION:
817
818In case this configuration option is defined, then the stack checker is
819enabled.
820
821.. rubric:: NOTES:
822
823The stack checker performs run-time stack bounds checking.  This increases
824the time required to create tasks as well as adding overhead to each context
825switch.
826
827In 4.9 and older, this configuration option was named ``STACK_CHECKER_ON``.
828
829.. Generated from spec:/acfg/if/ticks-per-time-slice
830
831.. raw:: latex
832
833    \clearpage
834
835.. index:: CONFIGURE_TICKS_PER_TIMESLICE
836.. index:: ticks per timeslice
837
838.. _CONFIGURE_TICKS_PER_TIMESLICE:
839
840CONFIGURE_TICKS_PER_TIMESLICE
841-----------------------------
842
843.. rubric:: CONSTANT:
844
845``CONFIGURE_TICKS_PER_TIMESLICE``
846
847.. rubric:: OPTION TYPE:
848
849This configuration option is an integer define.
850
851.. rubric:: DEFAULT VALUE:
852
853The default value is 50.
854
855.. rubric:: DESCRIPTION:
856
857The value of this configuration option defines the length of the timeslice
858quantum in ticks for each task.
859
860.. rubric:: NOTES:
861
862This configuration option has no impact if the Clock Driver is not
863configured, see :ref:`CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER`.
864
865.. rubric:: CONSTRAINTS:
866
867The following constraints apply to this configuration option:
868
869* The value of the configuration option shall be greater than or equal to zero.
870
871* The value of the configuration option shall be less than or equal to
872  `UINT32_MAX <https://en.cppreference.com/w/c/types/integer>`_.
873
874.. Generated from spec:/acfg/if/unified-work-areas
875
876.. raw:: latex
877
878    \clearpage
879
880.. index:: CONFIGURE_UNIFIED_WORK_AREAS
881.. index:: unified work areas
882.. index:: separate work areas
883.. index:: RTEMS Workspace
884.. index:: C Program Heap
885
886.. _CONFIGURE_UNIFIED_WORK_AREAS:
887
888CONFIGURE_UNIFIED_WORK_AREAS
889----------------------------
890
891.. rubric:: CONSTANT:
892
893``CONFIGURE_UNIFIED_WORK_AREAS``
894
895.. rubric:: OPTION TYPE:
896
897This configuration option is a boolean feature define.
898
899.. rubric:: DEFAULT CONFIGURATION:
900
901If this configuration option is undefined, then there will be separate memory
902pools for the RTEMS Workspace and C Program Heap.
903
904.. rubric:: DESCRIPTION:
905
906In case this configuration option is defined, then the RTEMS Workspace and
907the C Program Heap will be one pool of memory.
908
909.. rubric:: NOTES:
910
911Having separate pools does have some advantages in the event a task blows a
912stack or writes outside its memory area. However, in low memory systems the
913overhead of the two pools plus the potential for unused memory in either
914pool is very undesirable.
915
916In high memory environments, this is desirable when you want to use the
917:ref:`ConfigUnlimitedObjects` option.  You will be able to create objects
918until you run out of all available memory rather then just until you run out
919of RTEMS Workspace.
920
921.. Generated from spec:/acfg/if/unlimited-allocation-size
922
923.. raw:: latex
924
925    \clearpage
926
927.. index:: CONFIGURE_UNLIMITED_ALLOCATION_SIZE
928
929.. _CONFIGURE_UNLIMITED_ALLOCATION_SIZE:
930
931CONFIGURE_UNLIMITED_ALLOCATION_SIZE
932-----------------------------------
933
934.. rubric:: CONSTANT:
935
936``CONFIGURE_UNLIMITED_ALLOCATION_SIZE``
937
938.. rubric:: OPTION TYPE:
939
940This configuration option is an integer define.
941
942.. rubric:: DEFAULT VALUE:
943
944The default value is 8.
945
946.. rubric:: DESCRIPTION:
947
948If :ref:`CONFIGURE_UNLIMITED_OBJECTS` is defined, then the value of this
949configuration option defines the default objects maximum of all object
950classes supporting :ref:`ConfigUnlimitedObjects` to
951``rtems_resource_unlimited( CONFIGURE_UNLIMITED_ALLOCATION_SIZE )``.
952
953.. rubric:: NOTES:
954
955By allowing users to declare all resources as being unlimited the user can
956avoid identifying and limiting the resources used.
957
958The object maximum of each class can be configured also individually using
959the :c:func:`rtems_resource_unlimited` macro.
960
961.. rubric:: CONSTRAINTS:
962
963The value of the configuration option shall meet the constraints of all object
964classes to which it is applied.
965
966.. Generated from spec:/acfg/if/unlimited-objects
967
968.. raw:: latex
969
970    \clearpage
971
972.. index:: CONFIGURE_UNLIMITED_OBJECTS
973
974.. _CONFIGURE_UNLIMITED_OBJECTS:
975
976CONFIGURE_UNLIMITED_OBJECTS
977---------------------------
978
979.. rubric:: CONSTANT:
980
981``CONFIGURE_UNLIMITED_OBJECTS``
982
983.. rubric:: OPTION TYPE:
984
985This configuration option is a boolean feature define.
986
987.. rubric:: DEFAULT CONFIGURATION:
988
989If this configuration option is undefined, then the described feature is not
990enabled.
991
992.. rubric:: DESCRIPTION:
993
994In case this configuration option is defined, then unlimited objects are used
995by default.
996
997.. rubric:: NOTES:
998
999When using unlimited objects, it is common practice to also specify
1000:ref:`CONFIGURE_UNIFIED_WORK_AREAS` so the system operates with a single pool
1001of memory for both RTEMS Workspace and C Program Heap.
1002
1003This option does not override an explicit configuration for a particular
1004object class by the user.
1005
1006See also :ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`.
1007
1008.. Generated from spec:/acfg/if/verbose-system-init
1009
1010.. raw:: latex
1011
1012    \clearpage
1013
1014.. index:: CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION
1015
1016.. _CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION:
1017
1018CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION
1019---------------------------------------
1020
1021.. rubric:: CONSTANT:
1022
1023``CONFIGURE_VERBOSE_SYSTEM_INITIALIZATION``
1024
1025.. rubric:: OPTION TYPE:
1026
1027This configuration option is a boolean feature define.
1028
1029.. rubric:: DEFAULT CONFIGURATION:
1030
1031If this configuration option is undefined, then the described feature is not
1032enabled.
1033
1034.. rubric:: DESCRIPTION:
1035
1036In case this configuration option is defined, then the system initialization
1037is verbose.
1038
1039.. rubric:: NOTES:
1040
1041You may use this feature to debug system initialization issues.  The
1042:c:func:`printk` function is used to print the information.
1043
1044.. Generated from spec:/acfg/if/zero-workspace-automatically
1045
1046.. raw:: latex
1047
1048    \clearpage
1049
1050.. index:: CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY
1051.. index:: clear C Program Heap
1052.. index:: clear RTEMS Workspace
1053.. index:: zero C Program Heap
1054.. index:: zero RTEMS Workspace
1055
1056.. _CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY:
1057
1058CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY
1059--------------------------------------
1060
1061.. rubric:: CONSTANT:
1062
1063``CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY``
1064
1065.. rubric:: OPTION TYPE:
1066
1067This configuration option is a boolean feature define.
1068
1069.. rubric:: DEFAULT CONFIGURATION:
1070
1071If this configuration option is undefined, then the described feature is not
1072enabled.
1073
1074.. rubric:: DESCRIPTION:
1075
1076In case this configuration option is defined, then the memory areas used for
1077the RTEMS Workspace and the C Program Heap are zeroed with a ``0x00`` byte
1078pattern during system initialization.
1079
1080.. rubric:: NOTES:
1081
1082Zeroing memory can add significantly to the system initialization time. It is
1083not necessary for RTEMS but is often assumed by support libraries.  In case
1084:ref:`CONFIGURE_DIRTY_MEMORY` is also defined, then the memory is first
1085dirtied and then zeroed.
Note: See TracBrowser for help on using the repository browser.