source: rtems/doc/user/conf.t @ e0938c2

4.115
Last change on this file since e0938c2 was e0938c2, checked in by Joel Sherrill <joel.sherrill@…>, on 06/15/15 at 18:22:31

user/conf.t: Fix names for CONFIGURE_UNLIMITED_OBJECTS and CONFIGURE_UNLIMITED_ALLOCATION_SIZE

closes #2368.

  • Property mode set to 100644
File size: 135.6 KB
Line 
1@c  COPYRIGHT (c) 1988-2015.
2@c  On-Line Applications Research Corporation (OAR).
3@c  All rights reserved.
4
5@c TODO:
6@c   + Ensure all macros are documented.
7@c   + Verify which structures may actually be defined by a user
8@c   + Add Go configuration.
9
10@c Questions:
11@c   + Should there be examples of defining your own
12@c     Device Driver Table, Init task table, etc.?
13@c
14
15@chapter Configuring a System
16
17@c
18@c === Introduction ===
19@c
20@section Introduction
21
22RTEMS must be configured for an application.  This configuration
23encompasses a variety of information including the length of each clock
24tick, the maximum number of each information RTEMS object that can
25be created, the application initialization tasks, the task scheduling
26algorithm to be used, and the device drivers in the application.
27
28Although this information is contained in data structures that are used
29by RTEMS at system initialization time, the data structures themselves
30should only rarely to be generated by hand. RTEMS provides a set of
31macros system which provides a simple standard mechanism to automate
32the generation of these structures.
33
34@ifset is-Ada
35System configuration is ALWAYS done from C.  When developing
36an Ada application, the user is responsible for creating at
37least one C file which contains the Ada run-time initialization
38and the RTEMS System Configuration.  There is no Ada binding
39for RTEMS System Configuration information.  Thus all examples
40and data structures shown in this chapter are in C.
41@end ifset
42
43@cindex confdefs.h
44@findex confdefs.h
45@cindex <rtems/confdefs.h>
46@findex <rtems/confdefs.h>
47
48The RTEMS header file @code{<rtems/confdefs.h>} is at the core of the
49automatic generation of system configuration. It is based on the idea
50of setting macros which define configuration parameters of interest to
51the application and defaulting or calculating all others. This variety
52of macros can automatically produce all of the configuration data
53required for an RTEMS application.
54
55Trivia: @code{confdefs} is shorthand for a @b{Configuration Defaults}.
56
57As a general rule, application developers only specify values
58for the configuration parameters of interest to them. They define what
59resources or features they require. In most cases, when a parameter is
60not specified, it defaults to zero (0) instances, a standards compliant
61value, or disabled as appropriate. For example, by default there will be
62256 task priority levels but this can be lowered by the application. This
63number of priority levels is required to be compliant with the RTEID/ORKID
64standards upon which the Classic API is based. There are similar cases
65where the default is selected to be compliant with with the POSIX standard.
66
67For each configuration parameter in the configuration tables, the macro
68corresponding to that field is discussed. The RTEMS Maintainers
69expect that all systems can be easily configured using the
70@code{<rtems/confdefs.h>} mechanism and that using this mechanism will
71avoid internal RTEMS configuration changes impacting applications.
72
73@c
74@c === Philosophy ===
75@c
76@section Default Value Selection Philosophy
77
78The user should be aware that the defaults are intentionally set as
79low as possible.  By default, no application resources are configured.
80The @code{<rtems/confdefs.h>} file ensures that at least one application
81task or thread is configured and that at least one of the initialization
82task/thread tables is configured.
83
84@c
85@c === Sizing the RTEMS Workspace ===
86@c
87@section Sizing the RTEMS Workspace
88
89The RTEMS Workspace is a user-specified block of memory reserved for
90use by RTEMS.  The application should NOT modify this memory.  This area
91consists primarily of the RTEMS data structures whose exact size depends
92upon the values specified in the Configuration Table.  In addition,
93task stacks and floating point context areas are dynamically allocated
94from the RTEMS Workspace.
95
96The @code{<rtems/confdefs.h>} mechanism calculates the size of the RTEMS
97Workspace automatically.  It assumes that all tasks are floating point and
98that all will be allocated the minimum stack space.  This calculation
99includes the amount of memory that will be allocated for internal use
100by RTEMS. The automatic calculation may underestimate the workspace
101size truly needed by the application, in which case one can use the
102@code{CONFIGURE_MEMORY_OVERHEAD} macro to add a value to the estimate. See
103@ref{Configuring a System Specify Memory Overhead} for more details.
104
105The memory area for the RTEMS Workspace is determined by the BSP.  In case the
106RTEMS Workspace is too large for the available memory, then a fatal run-time
107error occurs and the system terminates.
108
109The file @code{<rtems/confdefs.h>} will calculate the value of the
110@code{work_space_size} parameter of the Configuration Table. There
111are many parameters the application developer can specify to
112help @code{<rtems/confdefs.h>} in its calculations.  Correctly
113specifying the application requirements via parameters such as
114@code{CONFIGURE_EXTRA_TASK_STACKS} and @code{CONFIGURE_MAXIMUM_TASKS}
115is critical for production software.
116
117For each class of objects, the allocation can operate in one of two ways.
118The default way has an ceiling on the maximum number of object instances
119which can concurrently exist in the system. Memory for all instances of
120that object class is reserved at system initialization.  The second
121way allocates memory for an initial number of objects and increases the
122current allocation by a fixed increment when required. Both ways allocate
123space from inside the RTEMS Workspace.
124
125See @ref{Configuring a System Unlimited Objects} for more details about
126the second way, which allows for dynamic allocation of objects and
127therefore does not provide determinism.  This mode is useful mostly for
128when the number of objects cannot be determined ahead of time or when
129porting software for which you do not know the object requirements.
130
131The space needed for stacks and for RTEMS objects will vary from
132one version of RTEMS and from one target processor to another.
133Therefore it is safest to use @code{<rtems/confdefs.h>} and specify
134your application's requirements in terms of the numbers of objects and
135multiples of @code{RTEMS_MINIMUM_STACK_SIZE}, as far as is possible. The
136automatic estimates of space required will in general change when:
137
138@itemize @bullet
139@item a configuration parameter is changed,
140@item task or interrupt stack sizes change,
141@item the floating point attribute of a task changes,
142@item task floating point attribute is altered,
143@item RTEMS is upgraded, or
144@item the target processor is changed.
145@end itemize
146
147Failure to provide enough space in the RTEMS Workspace may result in fatal
148run-time errors terminating the system.
149
150@c
151@c === Potential Issues ===
152@c
153@section Potential Issues with RTEMS Workspace Size Estimation
154
155The @code{<rtems/confdefs.h>} file estimates the amount of memory
156required for the RTEMS Workspace.  This estimate is only as accurate
157as the information given to @code{<rtems/confdefs.h>} and may be either
158too high or too low for a variety of reasons.  Some of the reasons that
159@code{<rtems/confdefs.h>} may reserve too much memory for RTEMS are:
160
161@itemize @bullet
162@item All tasks/threads are assumed to be floating point.
163@end itemize
164
165Conversely, there are many more reasons that the resource estimate could be
166too low:
167
168@itemize @bullet
169@item Task/thread stacks greater than minimum size must be
170accounted for explicitly by developer.
171
172@item Memory for messages is not included.
173
174@item Device driver requirements are not included.
175
176@item Network stack requirements are not included.
177
178@item Requirements for add-on libraries are not included.
179@end itemize
180
181In general, @code{<rtems/confdefs.h>} is very accurate when given enough
182information.  However, it is quite easy to use a library and forget to
183account for its resources.
184
185@c
186@c === Format to be followed for making changes in this file ===
187@c
188@section Format to be followed for making changes in this file
189
190@itemize @bullet
191@item MACRO NAME
192Should be alphanumeric. Can have '_' (underscore).
193
194@item DATA TYPE
195Please refer to all existing formats.
196
197@item RANGE:
198The range depends on the Data Type of the macro.
199@itemize @minus
200@item If the data type is of type task priority, then its value should
201be an integer in the range of 1 to 255.
202
203@item If the data type is an integer, then it can have numbers, characters
204(in case the value is defined using another macro) and arithmetic operations
205(+, -, *, /).
206
207@item If the data type is a function pointer the first character
208should be an alphabet or an underscore. The rest of the string
209can be alphanumeric.
210
211@item If the data type is RTEMS Attributes or RTEMS Mode then
212the string should be alphanumeric.
213
214@item If the data type is RTEMS NAME then the value should be
215an integer>=0 or RTEMS_BUILD_NAME( 'U', 'I', '1', ' ' )
216@end itemize
217
218@item DEFAULT VALUE
219The default value should be in the following formats-
220Please note that the '.' (full stop) is necessary.
221
222@itemize @minus
223@item In case the value is not defined then:
224      This is not defined by default.
225
226@item If we know the default value then:
227      The default value is XXX.
228
229@item If the default value is BSP Specific then:
230      This option is BSP specific.
231@end itemize
232
233@item DESCRIPTION
234The description of the macro. (No specific format)
235
236@item NOTES
237Any further notes. (No specific format)
238
239@end itemize
240
241@c
242@c === Configuration Example ===
243@c
244@section Configuration Example
245
246In the following example, the configuration information for a system
247with a single message queue, four (4) tasks, and a timeslice of
248fifty (50) milliseconds is as follows:
249
250@example
251@group
252#include <bsp.h>
253
254#define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
255#define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
256
257#define CONFIGURE_MICROSECONDS_PER_TICK   1000 /* 1 millisecond */
258#define CONFIGURE_TICKS_PER_TIMESLICE       50 /* 50 milliseconds */
259
260#define CONFIGURE_RTEMS_INIT_TASKS_TABLE
261
262#define CONFIGURE_MAXIMUM_TASKS 4
263#define CONFIGURE_MAXIMUM_MESSAGE_QUEUES 1
264
265#define CONFIGURE_MESSAGE_BUFFER_MEMORY \
266  CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(20, sizeof(struct USER_MESSAGE))
267
268#define CONFIGURE_INIT
269#include <rtems/confdefs.h>
270@end group
271@end example
272
273In this example, only a few configuration parameters are specified. The
274impact of these are as follows:
275
276@itemize @bullet
277
278@item The example specified @code{CONFIGURE_RTEMS_INIT_TASK_TABLE}
279but did not specify any additional parameters. This results in a
280configuration of an application which will begin execution of a single
281initialization task named @code{Init} which is non-preemptible and at
282priority one (1).
283
284@item By specifying @code{CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER},
285this application is configured to have a clock tick device
286driver. Without a clock tick device driver, RTEMS has no way to know
287that time is passing and will be unable to support delays and wall
288time. Further configuration details about time are
289provided. Per @code{CONFIGURE_MICROSECONDS_PER_TICK} and
290@code{CONFIGURE_TICKS_PER_TIMESLICE}, the user specified they wanted a
291clock tick to occur each millisecond, and that the length of a timeslice
292would be fifty (50) milliseconds.
293
294@item By specifying @code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER},
295the application will include a console device driver. Although the
296console device driver may support a combination of multiple serial
297ports and display and keyboard combinations, it is only required to
298provide a single device named @code{/dev/console}. This device will
299be used for Standard Input, Output and Error I/O Streams. Thus when
300@code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER} is specified, implicitly
301three (3) file descriptors are reserved for the Standard I/O Streams and
302those file descriptors are associated with @code{/dev/console} during
303initialization. All console devices are expected to support the POSIX
304@i{termios} interface.
305
306@item The example above specifies via @code{CONFIGURE_MAXIMUM_TASKS}
307that the application requires a maximum of four (4)
308simultaneously existing Classic API tasks. Similarly, by specifying
309@code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES}, there may be a maximum of only
310one (1) concurrently existent Classic API message queues.
311
312@item The most surprising configuration parameter in this example is the
313use of @code{CONFIGURE_MESSAGE_BUFFER_MEMORY}. Message buffer memory is
314allocated from the RTEMS Workspace and must be accounted for. In this
315example, the single message queue will have up to twenty (20) messages
316of type @code{struct USER_MESSAGE}.
317
318@item The @code{CONFIGURE_INIT} constant must be defined in order to
319make @code{<rtems/confdefs.h>} instantiate the configuration data
320structures.  This can only be defined in one source file per
321application that includes @code{<rtems/confdefs.h>} or the symbol
322table will be instantiated multiple times and linking errors
323produced.
324
325@end itemize
326
327This example illustrates that parameters have default values. Among
328other things, the application implicitly used the following defaults:
329
330@itemize @bullet
331@item All unspecified types of communications and synchronization objects
332in the Classic and POSIX Threads API have maximums of zero (0).
333
334@item The filesystem will be the default filesystem which is the In-Memory File
335System (IMFS).
336
337@item The application will have the default number of priority levels.
338
339@item The minimum task stack size will be that recommended by RTEMS for
340the target architecture.
341@end itemize
342
343@c
344@c === Unlimited Objects ===
345@c
346@subsection Unlimited Objects
347
348In real-time embedded systems the RAM is normally a limited, critical
349resource and dynamic allocation is avoided as much as possible to
350ensure predictable, deterministic execution times. For such cases, see
351@ref{Configuring a System Sizing the RTEMS Workspace} for an overview
352of how to tune the size of the workspace.  Frequently when users are
353porting software to RTEMS the precise resource requirements of the
354software is unknown. In these situations users do not need to control
355the size of the workspace very tightly because they just want to get
356the new software to run; later they can tune the workspace size as needed.
357
358The following API-independent object classes can be configured in
359unlimited mode:
360
361@itemize @bullet
362@item POSIX Keys
363@item POSIX Key Value Pairs
364@end itemize
365
366The following object classes in the Classic API can be configured in
367unlimited mode:
368
369@itemize @bullet
370@item Tasks
371@item Timers
372@item Semaphores
373@item Message Queues
374@item Periods
375@item Barriers
376@item Partitions
377@item Regions
378@item Ports
379@end itemize
380
381Additionally, the following object classes from the POSIX API can be
382configured in unlimited mode:
383
384@itemize @bullet
385@item Threads
386@item Mutexes
387@item Condition Variables
388@item Timers
389@item Message Queues
390@item Message Queue Descriptors
391@item Semaphores
392@item Barriers
393@item Read/Write Locks
394@item Spinlocks
395@end itemize
396
397The following object classes can @strong{not} be configured in unlimited mode:
398@itemize @bullet
399@item Drivers
400@item File Descriptors
401@item User Extensions
402@item POSIX Queued Signals
403@end itemize
404
405Due to the memory requirements of unlimited objects it is strongly recommended
406to use them only in combination with the unified work areas. See
407@ref{Configuring a System Separate or Unified Work Areas} for more information
408on unified work areas.
409
410The following example demonstrates how the two simple configuration defines for
411unlimited objects and unified works areas can replace many seperate
412configuration defines for supported object classes:
413@example
414#define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
415#define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
416
417#define CONFIGURE_UNIFIED_WORK_AREAS
418#define CONFIGURE_UNLIMITED_OBJECTS
419
420#define CONFIGURE_RTEMS_INIT_TASKS_TABLE
421
422#define CONFIGURE_INIT
423
424#include <rtems/confdefs.h>
425@end example
426
427Users are cautioned that using unlimited objects is not recommended for
428production software unless the dynamic growth is absolutely required. It
429is generally considered a safer embedded systems programming practice to
430know the system limits rather than experience an out of memory error
431at an arbitrary and largely unpredictable time in the field.
432
433@c
434@c === Per Object Class Unlimited Object Instances ===
435@c
436@subsection Per Object Class Unlimited Object Instances
437
438@findex rtems_resource_unlimited
439When the number of objects is not known ahead of time, RTEMS provides an
440auto-extending mode that can be enabled individually for each object
441type by using the macro @code{rtems_resource_unlimited}. This takes a value
442as a parameter, and is used to set the object maximum number field in
443an API Configuration table. The value is an allocation unit size. When
444RTEMS is required to grow the object table it is grown by this
445size. The kernel will return the object memory back to the RTEMS Workspace
446when an object is destroyed. The kernel will only return an allocated
447block of objects to the RTEMS Workspace if at least half the allocation
448size of free objects remain allocated. RTEMS always keeps one
449allocation block of objects allocated. Here is an example of using
450@code{rtems_resource_unlimited}:
451
452@example
453#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
454@end example
455
456@findex rtems_resource_is_unlimited
457@findex rtems_resource_maximum_per_allocation
458Object maximum specifications can be evaluated with the
459@code{rtems_resource_is_unlimited} and
460@code{rtems_resource_maximum_per_allocation} macros.
461
462@c
463@c === Unlimited Object Instances ===
464@c
465@subsection Unlimited Object Instances
466
467To ease the burden of developers who are porting new software RTEMS
468also provides the capability to make all object classes listed above
469operate in unlimited mode in a simple manner. The application developer
470is only responsible for enabling unlimited objects and specifying the
471allocation size.
472
473@c
474@c === CONFIGURE_UNLIMITED_OBJECTS ===
475@c
476@subsection Enable Unlimited Object Instances
477
478@findex CONFIGURE_UNLIMITED_OBJECTS
479
480@table @b
481@item CONSTANT:
482@code{CONFIGURE_UNLIMITED_OBJECTS}
483
484@item DATA TYPE:
485Boolean feature macro.
486
487@item RANGE:
488Defined or undefined.
489
490@item DEFAULT VALUE:
491This is not defined by default.
492
493@end table
494
495@subheading DESCRIPTION:
496@code{CONFIGURE_UNLIMITED_OBJECTS} enables @code{rtems_resource_unlimited}
497mode for Classic API and POSIX API objects that do not already have a
498specific maximum limit defined.
499
500@subheading NOTES:
501When using unlimited objects, it is common practice to also specify
502@code{CONFIGURE_UNIFIED_WORK_AREAS} so the system operates with a single
503pool of memory for both RTEMS and application memory allocations.
504
505@c
506@c === CONFIGURE_UNLIMITED_ALLOCATION_SIZE ===
507@c
508@subsection Specify Unlimited Objects Allocation Size
509
510@table @b
511@item CONSTANT:
512@code{CONFIGURE_UNLIMITED_ALLOCATION_SIZE}
513
514@item DATA TYPE:
515Unsigned integer (@code{uint32_t}).
516
517@item RANGE:
518Positive.
519
520@item DEFAULT VALUE:
521If not defined and @code{CONFIGURE_UNLIMITED_OBJECTS} is defined, the
522default value is eight (8).
523
524@end table
525
526@subheading DESCRIPTION:
527@code{CONFIGURE_UNLIMITED_ALLOCATION_SIZE} provides an
528allocation size to use for @code{rtems_resource_unlimited} when using
529@code{CONFIGURE_UNLIMITED_OBJECTS}.
530
531@subheading NOTES:
532By allowing users to declare all resources as being unlimited
533the user can avoid identifying and limiting the resources used.
534@code{CONFIGURE_UNLIMITED_OBJECTS} does not support varying the allocation
535sizes for different objects; users who want that much control can define
536the @code{rtems_resource_unlimited} macros themselves.
537
538@example
539#define CONFIGURE_UNLIMITED_OBJECTS
540#define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5
541@end example
542
543@c
544@c === Classic API Configuration ===
545@c
546@section Classic API Configuration
547
548This section defines the Classic API related system configuration
549parameters supported by @code{<rtems/confdefs.h>}.
550
551@c
552@c === CONFIGURE_MAXIMUM_TASKS ===
553@c
554@subsection Specify Maximum Classic API Tasks
555
556@findex CONFIGURE_MAXIMUM_TASKS
557
558@table @b
559@item CONSTANT:
560@code{CONFIGURE_MAXIMUM_TASKS}
561
562@item DATA TYPE:
563Unsigned integer (@code{uint32_t}).
564
565@item RANGE:
566Zero or positive.
567
568@item DEFAULT VALUE:
569The default value is 0.
570
571@end table
572
573@subheading DESCRIPTION:
574@code{CONFIGURE_MAXIMUM_TASKS} is the maximum number of Classic API
575Tasks that can be concurrently active.
576
577@subheading NOTES:
578This object class can be configured in unlimited allocation mode.
579
580The calculations for the required memory in the RTEMS Workspace
581for tasks assume that each task has a minimum stack size and
582has floating point support enabled.  The configuration parameter
583@code{CONFIGURE_EXTRA_TASK_STACKS} is used to specify task stack
584requirements @b{ABOVE} the minimum size required.  See
585@ref{Configuring a System Reserve Task/Thread Stack Memory Above Minimum}
586for more information about @code{CONFIGURE_EXTRA_TASK_STACKS}.
587
588The maximum number of POSIX threads is specified by
589@code{CONFIGURE_MAXIMUM_POSIX_THREADS}.
590@c XXX - Add xref to CONFIGURE_MAXIMUM_POSIX_THREADS.
591
592A future enhancement to @code{<rtems/confdefs.h>} could be to eliminate
593the assumption that all tasks have floating point enabled. This would
594require the addition of a new configuration parameter to specify the
595number of tasks which enable floating point support.
596
597@c
598@c === CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS ===
599@c
600@subsection Enable Classic API Notepads
601
602@findex CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS
603
604@table @b
605@item CONSTANT:
606@code{CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS}
607
608@item DATA TYPE:
609Boolean feature macro.
610
611@item RANGE:
612Defined or undefined.
613
614@item DEFAULT VALUE:
615This is not defined by default, and Classic API Notepads are not supported.
616
617@end table
618
619@subheading DESCRIPTION:
620@code{CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS} should be defined if the
621user wants to have support for Classic API Notepads in their application.
622
623@subheading NOTES:
624Disabling Classic API Notepads saves the allocation of sixteen (16)
625thirty-two bit integers. This saves sixty-four bytes per task/thread
626plus the allocation overhead. Notepads are rarely used in applications
627and this can save significant memory in a low RAM system. Classic API
628Notepads are deprecated, and this option is expected to be obsolete in
629the near future.
630
631@c
632@c === CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS ===
633@c
634@subsection Disable Classic API Notepads
635
636@findex CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS
637
638@table @b
639@item CONSTANT:
640@code{CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS}
641
642@item DATA TYPE:
643Boolean feature macro.
644
645@item RANGE:
646Defined or undefined.
647
648@item DEFAULT VALUE:
649This is not defined by default, and Classic API Notepads are not supported.
650
651@end table
652
653@subheading DESCRIPTION:
654@code{CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS} is deprecated. If users
655want to have support for Classic API Notepads, they should use
656@code{CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS}.
657
658@subheading NOTES:
659Disabling Classic API Notepads saves the allocation of sixteen (16)
660thirty-two bit integers. This saves sixty-four bytes per task/thread
661plus the allocation overhead. Notepads are rarely used in applications
662and this can save significant memory in a low RAM system. Classic API
663Notepads are deprecated, and this option is expected to be obsolete in
664the near future.
665
666@c
667@c === CONFIGURE_MAXIMUM_TIMERS ===
668@c
669@subsection Specify Maximum Classic API Timers
670
671@findex CONFIGURE_MAXIMUM_TIMERS
672
673@table @b
674@item CONSTANT:
675@code{CONFIGURE_MAXIMUM_TIMERS}
676
677@item DATA TYPE:
678Unsigned integer (@code{uint32_t}).
679
680@item RANGE:
681Zero or positive.
682
683@item DEFAULT VALUE:
684The default value is 0.
685
686@end table
687
688@subheading DESCRIPTION:
689@code{CONFIGURE_MAXIMUM_TIMERS} is the maximum number of Classic API
690Timers that can be concurrently active.
691
692@subheading NOTES:
693This object class can be configured in unlimited allocation mode.
694
695@c
696@c === CONFIGURE_MAXIMUM_SEMAPHORES ===
697@c
698@subsection Specify Maximum Classic API Semaphores
699
700@findex CONFIGURE_MAXIMUM_SEMAPHORES
701
702@table @b
703@item CONSTANT:
704@code{CONFIGURE_MAXIMUM_SEMAPHORES}
705
706@item DATA TYPE:
707Unsigned integer (@code{uint32_t}).
708
709@item RANGE:
710Zero or positive.
711
712@item DEFAULT VALUE:
713The default value is 0.
714
715@end table
716
717@subheading DESCRIPTION:
718@code{CONFIGURE_MAXIMUM_SEMAPHORES} is the maximum number of Classic
719API Semaphores that can be concurrently active.
720
721@subheading NOTES:
722This object class can be configured in unlimited allocation mode.
723
724@c
725@c === CONFIGURE_MAXIMUM_MRSP_SEMAPHORES ===
726@c
727@subsection Specify Maximum Classic API Semaphores usable with MrsP
728
729@findex CONFIGURE_MAXIMUM_MRSP_SEMAPHORES
730
731@table @b
732@item CONSTANT:
733@code{CONFIGURE_MAXIMUM_MRSP_SEMAPHORES}
734
735@item DATA TYPE:
736Unsigned integer (@code{uint32_t}).
737
738@item RANGE:
739Zero or positive.
740
741@item DEFAULT VALUE:
742The default value is 0.
743
744@end table
745
746@subheading DESCRIPTION:
747@code{CONFIGURE_MAXIMUM_MRSP_SEMAPHORES} is the
748maximum number of Classic API Semaphores using the Multiprocessor Resource
749Sharing Protocol (MrsP) that can be concurrently active.
750
751@subheading NOTES:
752This configuration option is only used on SMP configurations.  On uni-processor
753configurations the Priority Ceiling Protocol is used for MrsP semaphores and
754thus no extra memory is necessary.
755
756@c
757@c === CONFIGURE_MAXIMUM_MESSAGE_QUEUES ===
758@c
759@subsection Specify Maximum Classic API Message Queues
760
761@findex CONFIGURE_MAXIMUM_MESSAGE_QUEUES
762
763@table @b
764@item CONSTANT:
765@code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES}
766
767@item DATA TYPE:
768Unsigned integer (@code{uint32_t}).
769
770@item RANGE:
771Zero or positive.
772
773@item DEFAULT VALUE:
774The default value is 0.
775
776@end table
777
778@subheading DESCRIPTION:
779@code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES} is the maximum number of Classic
780API Message Queues that can be concurrently active.
781
782@subheading NOTES:
783This object class can be configured in unlimited allocation mode.
784
785@c
786@c === CONFIGURE_MAXIMUM_BARRIERS ===
787@c
788@subsection Specify Maximum Classic API Barriers
789
790@findex CONFIGURE_MAXIMUM_BARRIERS
791
792@table @b
793@item CONSTANT:
794@code{CONFIGURE_MAXIMUM_BARRIERS}
795
796@item DATA TYPE:
797Unsigned integer (@code{uint32_t}).
798
799@item RANGE:
800Zero or positive.
801
802@item DEFAULT VALUE:
803The default value is 0.
804
805@end table
806
807@subheading DESCRIPTION:
808@code{CONFIGURE_MAXIMUM_BARRIERS} is the maximum number of Classic
809API Barriers that can be concurrently active.
810
811@subheading NOTES:
812This object class can be configured in unlimited allocation mode.
813
814@c
815@c === CONFIGURE_MAXIMUM_PERIODS ===
816@c
817@subsection Specify Maximum Classic API Periods
818
819@findex CONFIGURE_MAXIMUM_PERIODS
820
821@table @b
822@item CONSTANT:
823@code{CONFIGURE_MAXIMUM_PERIODS}
824
825@item DATA TYPE:
826Unsigned integer (@code{uint32_t}).
827
828@item RANGE:
829Zero or positive.
830
831@item DEFAULT VALUE:
832The default value is 0.
833
834@end table
835
836@subheading DESCRIPTION:
837@code{CONFIGURE_MAXIMUM_PERIODS} is the maximum number of Classic
838API Periods that can be concurrently active.
839
840@subheading NOTES:
841This object class can be configured in unlimited allocation mode.
842
843@c
844@c === CONFIGURE_MAXIMUM_PARTITIONS ===
845@c
846@subsection Specify Maximum Classic API Partitions
847
848@findex CONFIGURE_MAXIMUM_PARTITIONS
849
850@table @b
851@item CONSTANT:
852@code{CONFIGURE_MAXIMUM_PARTITIONS}
853
854@item DATA TYPE:
855Unsigned integer (@code{uint32_t}).
856
857@item RANGE:
858Zero or positive.
859
860@item DEFAULT VALUE:
861The default value is 0.
862
863@end table
864
865@subheading DESCRIPTION:
866@code{CONFIGURE_MAXIMUM_PARTITIONS} is the maximum number of Classic
867API Partitions that can be concurrently active.
868
869@subheading NOTES:
870This object class can be configured in unlimited allocation mode.
871
872@c
873@c === CONFIGURE_MAXIMUM_REGIONS ===
874@c
875@subsection Specify Maximum Classic API Regions
876
877@findex CONFIGURE_MAXIMUM_REGIONS
878
879@table @b
880@item CONSTANT:
881@code{CONFIGURE_MAXIMUM_REGIONS}
882
883@item DATA TYPE:
884Unsigned integer (@code{uint32_t}).
885
886@item RANGE:
887Zero or positive.
888
889@item DEFAULT VALUE:
890The default value is 0.
891
892@end table
893
894@subheading DESCRIPTION:
895@code{CONFIGURE_MAXIMUM_REGIONS} is the maximum number of Classic
896API Regions that can be concurrently active.
897
898@subheading NOTES:
899None.
900
901@c
902@c === CONFIGURE_MAXIMUM_PORTS ===
903@c
904@subsection Specify Maximum Classic API Ports
905
906@findex CONFIGURE_MAXIMUM_PORTS
907
908@table @b
909@item CONSTANT:
910@code{CONFIGURE_MAXIMUM_PORTS}
911
912@item DATA TYPE:
913Unsigned integer (@code{uint32_t}).
914
915@item RANGE:
916Zero or positive.
917
918@item DEFAULT VALUE:
919The default value is 0.
920
921@end table
922
923@subheading DESCRIPTION:
924@code{CONFIGURE_MAXIMUM_PORTS} is the maximum number of Classic
925API Ports that can be concurrently active.
926
927@subheading NOTES:
928This object class can be configured in unlimited allocation mode.
929
930@c
931@c === CONFIGURE_MAXIMUM_USER_EXTENSIONS ===
932@c
933@subsection Specify Maximum Classic API User Extensions
934
935@findex CONFIGURE_MAXIMUM_USER_EXTENSIONS
936
937@table @b
938@item CONSTANT:
939@code{CONFIGURE_MAXIMUM_USER_EXTENSIONS}
940
941@item DATA TYPE:
942Unsigned integer (@code{uint32_t}).
943
944@item RANGE:
945Zero or positive.
946
947@item DEFAULT VALUE:
948The default value is 0.
949
950@end table
951
952@subheading DESCRIPTION:
953@code{CONFIGURE_MAXIMUM_USER_EXTENSIONS} is the maximum number of Classic
954API User Extensions that can be concurrently active.
955
956@subheading NOTES:
957This object class can be configured in unlimited allocation mode.
958
959@c
960@c === Classic API Initialization Task Configuration ===
961@c
962@section Classic API Initialization Tasks Table Configuration
963
964The @code{<rtems/confdefs.h>} configuration system can automatically
965generate an Initialization Tasks Table named
966@code{Initialization_tasks} with a single entry.  The following
967parameters control the generation of that table.
968
969@c
970@c === CONFIGURE_RTEMS_INIT_TASKS_TABLE ===
971@c
972@subsection Instantiate Classic API Initialization Task Table
973
974@findex CONFIGURE_RTEMS_INIT_TASKS_TABLE
975
976@table @b
977@item CONSTANT:
978@code{CONFIGURE_RTEMS_INIT_TASKS_TABLE}
979
980@item DATA TYPE:
981Boolean feature macro.
982
983@item RANGE:
984Defined or undefined.
985
986@item DEFAULT VALUE:
987This is not defined by default.
988
989@end table
990
991@subheading DESCRIPTION:
992@code{CONFIGURE_RTEMS_INIT_TASKS_TABLE} is defined if the user wishes
993to use a Classic RTEMS API Initialization Task Table. The table built by
994@code{<rtems/confdefs.h>} specifies the parameters for a single task. This
995is sufficient for applications which initialization the system from a
996single task.
997
998By default, this field is not defined as the user MUST select their own
999API for initialization tasks.
1000
1001@subheading NOTES:
1002The application may choose to use the initialization tasks or threads
1003table from another API.
1004
1005A compile time error will be generated if the user does not configure
1006any initialization tasks or threads.
1007
1008@c
1009@c === CONFIGURE_INIT_TASK_ENTRY_POINT ===
1010@c
1011@subsection Specifying Classic API Initialization Task Entry Point
1012
1013@findex CONFIGURE_INIT_TASK_ENTRY_POINT
1014
1015@table @b
1016@item CONSTANT:
1017@code{CONFIGURE_INIT_TASK_ENTRY_POINT}
1018
1019@item DATA TYPE:
1020Task entry function pointer (@code{rtems_task_entry}).
1021
1022@item RANGE:
1023Valid task entry function pointer.
1024
1025@item DEFAULT VALUE:
1026The default value is @code{Init}.
1027
1028@end table
1029
1030@subheading DESCRIPTION:
1031@code{CONFIGURE_INIT_TASK_ENTRY_POINT} is the entry point (a.k.a. function
1032name) of the single initialization task defined by the Classic API
1033Initialization Tasks Table.
1034
1035@subheading NOTES:
1036The user must implement the function @code{Init} or the function name provided
1037in this configuration parameter.
1038
1039@c
1040@c === CONFIGURE_INIT_TASK_NAME ===
1041@c
1042@subsection Specifying Classic API Initialization Task Name
1043
1044@findex CONFIGURE_INIT_TASK_NAME
1045
1046@table @b
1047@item CONSTANT:
1048@code{CONFIGURE_INIT_TASK_NAME}
1049
1050@item DATA TYPE:
1051RTEMS Name (@code{rtems_name}).
1052
1053@item RANGE:
1054Any value.
1055
1056@item DEFAULT VALUE:
1057The default value is @code{rtems_build_name( 'U', 'I', '1', ' ' )}.
1058
1059@end table
1060
1061@subheading DESCRIPTION:
1062@code{CONFIGURE_INIT_TASK_NAME} is the name of the single initialization
1063task defined by the Classic API Initialization Tasks Table.
1064
1065@subheading NOTES:
1066None.
1067
1068@c
1069@c === CONFIGURE_INIT_TASK_STACK_SIZE ===
1070@c
1071@subsection Specifying Classic API Initialization Task Stack Size
1072
1073@findex CONFIGURE_INIT_TASK_STACK_SIZE
1074
1075@table @b
1076@item CONSTANT:
1077@code{CONFIGURE_INIT_TASK_STACK_SIZE}
1078
1079@item DATA TYPE:
1080Unsigned integer (@code{size_t}).
1081
1082@item RANGE:
1083Zero or positive.
1084
1085@item DEFAULT VALUE:
1086The default value is RTEMS_MINIMUM_STACK_SIZE.
1087
1088@end table
1089
1090@subheading DESCRIPTION:
1091@code{CONFIGURE_INIT_TASK_STACK_SIZE} is the stack size of the single
1092initialization task defined by the Classic API Initialization Tasks Table.
1093
1094@subheading NOTES:
1095If the stack size specified is greater than the configured minimum,
1096it must be accounted for in @code{CONFIGURE_EXTRA_TASK_STACKS}.
1097See @ref{Configuring a System Reserve Task/Thread Stack Memory Above Minimum}
1098for more information about @code{CONFIGURE_EXTRA_TASK_STACKS}.
1099
1100@c
1101@c === CONFIGURE_INIT_TASK_PRIORITY ===
1102@c
1103@subsection Specifying Classic API Initialization Task Priority
1104
1105@findex CONFIGURE_INIT_TASK_PRIORITY
1106
1107@table @b
1108@item CONSTANT:
1109@code{CONFIGURE_INIT_TASK_PRIORITY}
1110
1111@item DATA TYPE:
1112RTEMS Task Priority (@code{rtems_task_priority}).
1113
1114@item RANGE:
1115One (1) to CONFIGURE_MAXIMUM_PRIORITY.
1116
1117@item DEFAULT VALUE:
1118The default value is 1, which is the highest priority in the
1119Classic API.
1120
1121@end table
1122
1123@subheading DESCRIPTION:
1124@code{CONFIGURE_INIT_TASK_PRIORITY} is the initial priority of the single
1125initialization task defined by the Classic API Initialization Tasks Table.
1126
1127@subheading NOTES:
1128None.
1129
1130@c
1131@c === CONFIGURE_INIT_TASK_ATTRIBUTES ===
1132@c
1133@subsection Specifying Classic API Initialization Task Attributes
1134
1135@findex CONFIGURE_INIT_TASK_ATTRIBUTES
1136
1137@table @b
1138@item CONSTANT:
1139@code{CONFIGURE_INIT_TASK_ATTRIBUTES}
1140
1141
1142@item DATA TYPE:
1143RTEMS Attributes (@code{rtems_attribute}).
1144
1145@item RANGE:
1146Valid task attribute sets.
1147
1148@item DEFAULT VALUE:
1149The default value is @code{RTEMS_DEFAULT_ATTRIBUTES}.
1150
1151@end table
1152
1153@subheading DESCRIPTION:
1154@code{CONFIGURE_INIT_TASK_ATTRIBUTES} is the task attributes of the single
1155initialization task defined by the Classic API Initialization Tasks Table.
1156
1157@subheading NOTES:
1158None.
1159
1160@c
1161@c === CONFIGURE_INIT_TASK_INITIAL_MODES ===
1162@c
1163@subsection Specifying Classic API Initialization Task Modes
1164
1165@findex CONFIGURE_INIT_TASK_INITIAL_MODES
1166
1167@table @b
1168@item CONSTANT:
1169@code{CONFIGURE_INIT_TASK_INITIAL_MODES}
1170
1171@item DATA TYPE:
1172RTEMS Mode (@code{rtems_mode}).
1173
1174@item RANGE:
1175Valid task mode sets.
1176
1177@item DEFAULT VALUE:
1178The default value is @code{RTEMS_NO_PREEMPT}.
1179
1180@end table
1181
1182@subheading DESCRIPTION:
1183@code{CONFIGURE_INIT_TASK_INITIAL_MODES} is the initial execution mode of
1184the single initialization task defined by the Classic API Initialization
1185Tasks Table.
1186
1187@subheading NOTES:
1188None.
1189
1190@c
1191@c === CONFIGURE_INIT_TASK_ARGUMENTS ===
1192@c
1193@subsection Specifying Classic API Initialization Task Arguments
1194
1195@findex CONFIGURE_INIT_TASK_ARGUMENTS
1196
1197@table @b
1198@item CONSTANT:
1199@code{CONFIGURE_INIT_TASK_ARGUMENTS}
1200
1201@item DATA TYPE:
1202RTEMS Task Argument (@code{rtems_task_argument}).
1203
1204@item RANGE:
1205Complete range of the type.
1206
1207@item DEFAULT VALUE:
1208The default value is 0.
1209
1210@end table
1211
1212@subheading DESCRIPTION:
1213@code{CONFIGURE_INIT_TASK_ARGUMENTS} is the task argument of the single
1214initialization task defined by the Classic API Initialization Tasks Table.
1215
1216@subheading NOTES:
1217None.
1218
1219@c
1220@c === CONFIGURE_HAS_OWN_INIT_TASK_TABLE ===
1221@c
1222@subsection Not Using Generated Initialization Tasks Table
1223
1224@findex CONFIGURE_HAS_OWN_INIT_TASK_TABLE
1225
1226@table @b
1227@item CONSTANT:
1228@code{CONFIGURE_HAS_OWN_INIT_TASK_TABLE}
1229
1230@item DATA TYPE:
1231Boolean feature macro.
1232
1233@item RANGE:
1234Defined or undefined.
1235
1236@item DEFAULT VALUE:
1237This is not defined by default.
1238
1239@end table
1240
1241@subheading DESCRIPTION:
1242@code{CONFIGURE_HAS_OWN_INIT_TASK_TABLE} is defined if the user wishes
1243to define their own Classic API Initialization Tasks Table.  This table
1244should be named @code{Initialization_tasks}.
1245
1246@subheading NOTES:
1247This is a seldom used configuration parameter. The most likely use case
1248is when an application desires to have more than one initialization task.
1249
1250@c
1251@c === POSIX API Configuration ===
1252@c
1253@section POSIX API Configuration
1254
1255The parameters in this section are used to configure resources
1256for the RTEMS POSIX API.  They are only relevant if the POSIX API
1257is enabled at configure time using the @code{--enable-posix} option.
1258
1259@c
1260@c === CONFIGURE_MAXIMUM_POSIX_THREADS ===
1261@c
1262@subsection Specify Maximum POSIX API Threads
1263
1264@findex CONFIGURE_MAXIMUM_POSIX_THREADS
1265
1266@table @b
1267@item CONSTANT:
1268@code{CONFIGURE_MAXIMUM_POSIX_THREADS}
1269
1270@item DATA TYPE:
1271Unsigned integer (@code{uint32_t}).
1272
1273@item RANGE:
1274Zero or positive.
1275
1276@item DEFAULT VALUE:
1277The default value is 0.
1278
1279@end table
1280
1281@subheading DESCRIPTION:
1282@code{CONFIGURE_MAXIMUM_POSIX_THREADS} is the maximum number of POSIX API
1283Threads that can be concurrently active.
1284
1285@subheading NOTES:
1286This object class can be configured in unlimited allocation mode.
1287
1288This calculations for the required memory in the RTEMS Workspace
1289for threads assume that each thread has a minimum stack size and
1290has floating point support enabled.  The configuration parameter
1291@code{CONFIGURE_EXTRA_TASK_STACKS} is used to specify thread stack
1292requirements @b{ABOVE} the minimum size required.
1293See @ref{Configuring a System Reserve Task/Thread Stack Memory Above Minimum}
1294for more information about @code{CONFIGURE_EXTRA_TASK_STACKS}.
1295
1296The maximum number of Classic API Tasks is specified by
1297@code{CONFIGURE_MAXIMUM_TASKS}.
1298
1299All POSIX threads have floating point enabled.
1300
1301@c XXX - Add xref to CONFIGURE_MAXIMUM_TASKS.
1302
1303@c
1304@c === CONFIGURE_MAXIMUM_POSIX_MUTEXES ===
1305@c
1306@subsection Specify Maximum POSIX API Mutexes
1307
1308@findex CONFIGURE_MAXIMUM_POSIX_MUTEXES
1309
1310@table @b
1311@item CONSTANT:
1312@code{CONFIGURE_MAXIMUM_POSIX_MUTEXES}
1313
1314@item DATA TYPE:
1315Unsigned integer (@code{uint32_t}).
1316
1317@item RANGE:
1318Zero or positive.
1319
1320@item DEFAULT VALUE:
1321The default value is 0.
1322
1323@end table
1324
1325@subheading DESCRIPTION:
1326@code{CONFIGURE_MAXIMUM_POSIX_MUTEXES} is the maximum number of POSIX
1327API Mutexes that can be concurrently active.
1328
1329@subheading NOTES:
1330This object class can be configured in unlimited allocation mode.
1331
1332@c
1333@c === CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES ===
1334@c
1335@subsection Specify Maximum POSIX API Condition Variables
1336
1337@findex CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES
1338
1339@table @b
1340@item CONSTANT:
1341@code{CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES}
1342
1343@item DATA TYPE:
1344Unsigned integer (@code{uint32_t}).
1345
1346@item RANGE:
1347Zero or positive.
1348
1349@item DEFAULT VALUE:
1350The default value is 0.
1351
1352@end table
1353
1354@subheading DESCRIPTION:
1355@code{CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES} is the maximum number
1356of POSIX API Condition Variables that can be concurrently active.
1357
1358@subheading NOTES:
1359This object class can be configured in unlimited allocation mode.
1360
1361@c
1362@c === CONFIGURE_MAXIMUM_POSIX_KEYS ===
1363@c
1364@subsection Specify Maximum POSIX API Keys
1365
1366@findex CONFIGURE_MAXIMUM_POSIX_KEYS
1367
1368@table @b
1369@item CONSTANT:
1370@code{CONFIGURE_MAXIMUM_POSIX_KEYS}
1371
1372@item DATA TYPE:
1373Unsigned integer (@code{uint32_t}).
1374
1375@item RANGE:
1376Zero or positive.
1377
1378@item DEFAULT VALUE:
1379The default value is 0.
1380
1381@end table
1382
1383@subheading DESCRIPTION:
1384@code{CONFIGURE_MAXIMUM_POSIX_KEYS} is the maximum number of POSIX
1385API Keys that can be concurrently active.
1386
1387@subheading NOTES:
1388This object class can be configured in unlimited allocation mode.
1389
1390@c XXX - Key pairs
1391
1392@c
1393@c === CONFIGURE_MAXIMUM_POSIX_TIMERS ===
1394@c
1395@subsection Specify Maximum POSIX API Timers
1396
1397@findex CONFIGURE_MAXIMUM_POSIX_TIMERS
1398
1399@table @b
1400@item CONSTANT:
1401@code{CONFIGURE_MAXIMUM_POSIX_TIMERS}
1402
1403@item DATA TYPE:
1404Unsigned integer (@code{uint32_t}).
1405
1406@item RANGE:
1407Zero or positive.
1408
1409@item DEFAULT VALUE:
1410The default value is 0.
1411
1412@end table
1413
1414@subheading DESCRIPTION:
1415@code{CONFIGURE_MAXIMUM_POSIX_TIMERS} is the maximum number of POSIX
1416API Timers that can be concurrently active.
1417
1418@subheading NOTES:
1419This object class can be configured in unlimited allocation mode.
1420
1421@c
1422@c === CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS ===
1423@c
1424@subsection Specify Maximum POSIX API Queued Signals
1425
1426@findex CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS
1427
1428@table @b
1429@item CONSTANT:
1430@code{CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS}
1431
1432@item DATA TYPE:
1433Unsigned integer (@code{uint32_t}).
1434
1435@item RANGE:
1436Zero or positive.
1437
1438@item DEFAULT VALUE:
1439The default value is 0.
1440
1441@end table
1442
1443@subheading DESCRIPTION:
1444@code{CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS} is the maximum number of POSIX
1445API Queued Signals that can be concurrently active.
1446
1447@subheading NOTES:
1448None.
1449
1450@c
1451@c === CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES ===
1452@c
1453@subsection Specify Maximum POSIX API Message Queues
1454
1455@findex CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES
1456
1457@table @b
1458@item CONSTANT:
1459@code{CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES}
1460
1461@item DATA TYPE:
1462Unsigned integer (@code{uint32_t}).
1463
1464@item RANGE:
1465Zero or positive.
1466
1467@item DEFAULT VALUE:
1468The default value is 0.
1469
1470@end table
1471
1472@subheading DESCRIPTION:
1473@code{CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES} is the maximum number of POSIX
1474API Message Queues that can be concurrently active.
1475
1476@subheading NOTES:
1477This object class can be configured in unlimited allocation mode.
1478
1479@c XXX - memory for buffers note
1480
1481@c
1482@c === CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS ===
1483@c
1484@subsection Specify Maximum POSIX API Message Queue Descriptors
1485
1486@findex CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS
1487
1488@table @b
1489@item CONSTANT:
1490@code{CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS}
1491
1492@item DATA TYPE:
1493Unsigned integer (@code{uint32_t}).
1494
1495@item RANGE:
1496greater than or equal to @code{CONFIGURE_MAXIMUM_POSIX_MESSAGES_QUEUES}
1497
1498@item DEFAULT VALUE:
1499The default value is 0.
1500
1501@end table
1502
1503@subheading DESCRIPTION:
1504@code{CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS} is the maximum
1505number of POSIX API Message Queue Descriptors that can be concurrently
1506active.
1507
1508@subheading NOTES:
1509This object class can be configured in unlimited allocation mode.
1510
1511@code{CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUE_DESCRIPTORS} should be
1512greater than or equal to @code{CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES}.
1513
1514@c
1515@c === CONFIGURE_MAXIMUM_POSIX_SEMAPHORES ===
1516@c
1517@subsection Specify Maximum POSIX API Semaphores
1518
1519@findex CONFIGURE_MAXIMUM_POSIX_SEMAPHORES
1520
1521@table @b
1522@item CONSTANT:
1523@code{CONFIGURE_MAXIMUM_POSIX_SEMAPHORES}
1524
1525@item DATA TYPE:
1526Unsigned integer (@code{uint32_t}).
1527
1528@item RANGE:
1529Zero or positive.
1530
1531@item DEFAULT VALUE:
1532The default value is 0.
1533
1534@end table
1535
1536@subheading DESCRIPTION:
1537@code{CONFIGURE_MAXIMUM_POSIX_SEMAPHORES} is the maximum number of POSIX
1538API Semaphores that can be concurrently active.
1539
1540@subheading NOTES:
1541None.
1542
1543@c
1544@c === CONFIGURE_MAXIMUM_POSIX_BARRIERS ===
1545@c
1546@subsection Specify Maximum POSIX API Barriers
1547
1548@findex CONFIGURE_MAXIMUM_POSIX_BARRIERS
1549
1550@table @b
1551@item CONSTANT:
1552@code{CONFIGURE_MAXIMUM_POSIX_BARRIERS}
1553
1554@item DATA TYPE:
1555Unsigned integer (@code{uint32_t}).
1556
1557@item RANGE:
1558Zero or positive.
1559
1560@item DEFAULT VALUE:
1561The default value is 0.
1562
1563@end table
1564
1565@subheading DESCRIPTION:
1566@code{CONFIGURE_MAXIMUM_POSIX_BARRIERS} is the maximum number of POSIX
1567API Barriers that can be concurrently active.
1568
1569@subheading NOTES:
1570This object class can be configured in unlimited allocation mode.
1571
1572@c
1573@c === CONFIGURE_MAXIMUM_POSIX_SPINLOCKS ===
1574@c
1575@subsection Specify Maximum POSIX API Spinlocks
1576
1577@findex CONFIGURE_MAXIMUM_POSIX_SPINLOCKS
1578
1579@table @b
1580@item CONSTANT:
1581@code{CONFIGURE_MAXIMUM_POSIX_SPINLOCKS}
1582
1583@item DATA TYPE:
1584Unsigned integer (@code{uint32_t}).
1585
1586@item RANGE:
1587Zero or positive.
1588
1589@item DEFAULT VALUE:
1590The default value is 0.
1591
1592@end table
1593
1594@subheading DESCRIPTION:
1595@code{CONFIGURE_MAXIMUM_POSIX_SPINLOCKS} is the maximum number of POSIX
1596API Spinlocks that can be concurrently active.
1597
1598@subheading NOTES:
1599This object class can be configured in unlimited allocation mode.
1600
1601@c
1602@c === CONFIGURE_MAXIMUM_POSIX_RWLOCKS ===
1603@c
1604@subsection Specify Maximum POSIX API Read/Write Locks
1605
1606@findex CONFIGURE_MAXIMUM_POSIX_RWLOCKS
1607
1608@table @b
1609@item CONSTANT:
1610@code{CONFIGURE_MAXIMUM_POSIX_RWLOCKS}
1611
1612@item DATA TYPE:
1613Unsigned integer (@code{uint32_t}).
1614
1615@item RANGE:
1616Zero or positive.
1617
1618@item DEFAULT VALUE:
1619The default value is 0.
1620
1621@end table
1622
1623@subheading DESCRIPTION:
1624@code{CONFIGURE_MAXIMUM_POSIX_RWLOCKS} is the maximum number of POSIX
1625API Read/Write Locks that can be concurrently active.
1626
1627@subheading NOTES:
1628This object class can be configured in unlimited allocation mode.
1629
1630@c
1631@c === POSIX Initialization Threads Table Configuration ===
1632@c
1633@section POSIX Initialization Threads Table Configuration
1634
1635The @code{<rtems/confdefs.h>} configuration system can automatically
1636generate a POSIX Initialization Threads Table named
1637@code{POSIX_Initialization_threads} with a single entry.  The following
1638parameters control the generation of that table.
1639
1640@c
1641@c === CONFIGURE_POSIX_INIT_THREAD_TABLE ===
1642@c
1643@subsection Instantiate POSIX API Initialization Thread Table
1644
1645@findex CONFIGURE_POSIX_INIT_THREAD_TABLE
1646
1647@table @b
1648@item CONSTANT:
1649@findex CONFIGURE_POSIX_INIT_THREAD_TABLE
1650
1651@item DATA TYPE:
1652Boolean feature macro.
1653
1654@item RANGE:
1655Defined or undefined.
1656
1657@item DEFAULT VALUE:
1658This field is not defined by default, as the user MUST select their own
1659API for initialization tasks.
1660
1661@end table
1662
1663@subheading DESCRIPTION:
1664@code{CONFIGURE_POSIX_INIT_THREAD_TABLE} is defined if the user wishes
1665to use a POSIX API Initialization Threads Table.  The table built
1666by @code{<rtems/confdefs.h>} specifies the parameters for a single
1667thread. This is sufficient for applications which initialization the
1668system from a
1669single task.
1670
1671By default, this field is not defined as the user MUST select their own
1672API for initialization tasks.
1673
1674@subheading NOTES:
1675The application may choose to use the initialization tasks or threads
1676table from another API.
1677
1678A compile time error will be generated if the user does not configure
1679any initialization tasks or threads.
1680
1681@c
1682@c === CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT ===
1683@c
1684@subsection Specifying POSIX API Initialization Thread Entry Point
1685
1686@findex CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT
1687
1688@table @b
1689@item CONSTANT:
1690@code{CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT}
1691
1692@item DATA TYPE:
1693POSIX thread function pointer (@code{void *(*entry_point)(void *)}).
1694
1695@item RANGE:
1696Undefined or a valid POSIX thread function pointer.
1697
1698@item DEFAULT VALUE:
1699The default value is @code{POSIX_Init}.
1700
1701@end table
1702
1703@subheading DESCRIPTION:
1704@code{CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT} is the entry point
1705(a.k.a. function name) of the single initialization thread defined by
1706the POSIX API Initialization Threads Table.
1707
1708@subheading NOTES:
1709The user must implement the function @code{POSIX_Init} or the function name
1710provided in this configuration parameter.
1711
1712@c
1713@c === CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE ===
1714@c
1715@subsection Specifying POSIX API Initialization Thread Stack Size
1716
1717@findex CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE
1718
1719@table @b
1720@item CONSTANT:
1721@code{CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE}
1722
1723@item DATA TYPE:
1724Unsigned integer (@code{size_t}).
1725
1726@item RANGE:
1727Zero or positive.
1728
1729@item DEFAULT VALUE:
1730The default value is 2 * RTEMS_MINIMUM_STACK_SIZE.
1731
1732@end table
1733
1734@subheading DESCRIPTION:
1735@code{CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE} is the stack size of the
1736single initialization thread defined by the POSIX API Initialization
1737Threads Table.
1738
1739@subheading NOTES:
1740If the stack size specified is greater than the configured minimum,
1741it must be accounted for in @code{CONFIGURE_EXTRA_TASK_STACKS}.
1742See @ref{Configuring a System Reserve Task/Thread Stack Memory Above Minimum}
1743for more information about @code{CONFIGURE_EXTRA_TASK_STACKS}.
1744
1745@c
1746@c === CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE ===
1747@c
1748@subsection Not Using Generated POSIX Initialization Threads Table
1749
1750@findex CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE
1751
1752@table @b
1753@item CONSTANT:
1754@code{CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE}
1755
1756@item DATA TYPE:
1757Boolean feature macro.
1758
1759@item RANGE:
1760Defined or undefined.
1761
1762@item DEFAULT VALUE:
1763This is not defined by default.
1764
1765@end table
1766
1767@subheading DESCRIPTION:
1768@code{CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE} is defined if the
1769user wishes to define their own POSIX API Initialization Threads Table.
1770This table should be named @code{POSIX_Initialization_threads}.
1771
1772@subheading NOTES:
1773This is a seldom used configuration parameter. The most likely use case
1774is when an application desires to have more than one initialization task.
1775
1776@c
1777@c === Basic System Information ===
1778@c
1779@section Basic System Information
1780
1781This section defines the general system configuration parameters supported by
1782@code{<rtems/confdefs.h>}.
1783
1784@c
1785@c === CONFIGURE_UNIFIED_WORK_AREAS ===
1786@c
1787@subsection Separate or Unified Work Areas
1788
1789@findex CONFIGURE_UNIFIED_WORK_AREAS
1790@cindex unified work areas
1791@cindex separate work areas
1792@cindex RTEMS Workspace
1793@cindex C Program Heap
1794
1795@table @b
1796@item CONSTANT:
1797@code{CONFIGURE_UNIFIED_WORK_AREAS}
1798
1799@item DATA TYPE:
1800Boolean feature macro.
1801
1802@item RANGE:
1803Defined or undefined.
1804
1805@item DEFAULT VALUE:
1806This is not defined by default, which specifies that the C Program Heap
1807and the RTEMS Workspace will be separate.
1808
1809@end table
1810
1811@subheading DESCRIPTION:
1812When defined, the C Program Heap and the RTEMS Workspace will be one pool
1813of memory.
1814
1815When not defined, there will be separate memory pools for the RTEMS
1816Workspace and C Program Heap.
1817
1818@subheading NOTES:
1819Having separate pools does have some advantages in the event a task blows
1820a stack or writes outside its memory area. However, in low memory systems
1821the overhead of the two pools plus the potential for unused memory in
1822either pool is very undesirable.
1823
1824In high memory environments, this is desirable when you want to use the
1825RTEMS "unlimited" objects option.  You will be able to create objects
1826until you run out of all available memory rather then just until you
1827run out of RTEMS Workspace.
1828
1829@c
1830@c === CONFIGURE_MICROSECONDS_PER_TICK ===
1831@c
1832@subsection Length of Each Clock Tick
1833
1834@findex CONFIGURE_MICROSECONDS_PER_TICK
1835@cindex tick quantum
1836
1837@table @b
1838@item CONSTANT:
1839@code{CONFIGURE_MICROSECONDS_PER_TICK}
1840
1841@item DATA TYPE:
1842Unsigned integer (@code{uint32_t}).
1843
1844@item RANGE:
1845Positive.
1846
1847@item DEFAULT VALUE:
1848This is not defined by default. When not defined,
1849the clock tick quantum is configured to be 10,000
1850microseconds which is ten (10) milliseconds.
1851
1852@end table
1853
1854@subheading DESCRIPTION:
1855This constant is  used to specify the length of time between clock ticks.
1856
1857When the clock tick quantum value is too low, the system will spend so
1858much time processing clock ticks that it does not have processing time
1859available to perform application work. In this case, the system will
1860become unresponsive.
1861
1862The lowest practical time quantum varies widely based upon the speed
1863of the target hardware and the architectural overhead associated with
1864interrupts. In general terms, you do not want to configure it lower than
1865is needed for the application.
1866
1867The clock tick quantum should be selected such that it all blocking and
1868delay times in the application are evenly divisible by it. Otherwise,
1869rounding errors will be introduced which may negatively impact the
1870application.
1871
1872@subheading NOTES:
1873This configuration parameter has no impact if the Clock Tick Device
1874driver is not configured.
1875
1876There may be BSP specific limits on the resolution or maximum value of
1877a clock tick quantum.
1878
1879@c
1880@c === CONFIGURE_TICKS_PER_TIMESLICE ===
1881@c
1882@subsection Specifying Timeslicing Quantum
1883
1884@findex CONFIGURE_TICKS_PER_TIMESLICE
1885@cindex ticks per timeslice
1886
1887@table @b
1888@item CONSTANT:
1889@code{CONFIGURE_TICKS_PER_TIMESLICE}
1890
1891
1892@item DATA TYPE:
1893Unsigned integer (@code{uint32_t}).
1894
1895@item RANGE:
1896Positive.
1897
1898@item DEFAULT VALUE:
1899The default value is 50.
1900
1901@end table
1902
1903@subheading DESCRIPTION:
1904This configuration parameter specifies the length of the timeslice
1905quantum in ticks for each task.
1906
1907@subheading NOTES:
1908This configuration parameter has no impact if the Clock Tick Device
1909driver is not configured.
1910
1911@c
1912@c === CONFIGURE_MAXIMUM_PRIORITY ===
1913@c
1914@subsection Specifying the Number of Thread Priority Levels
1915
1916@findex CONFIGURE_MAXIMUM_PRIORITY
1917@cindex maximum priority
1918@cindex number of priority levels
1919
1920@table @b
1921@item CONSTANT:
1922@code{CONFIGURE_MAXIMUM_PRIORITY}
1923
1924@item DATA TYPE:
1925Unsigned integer (@code{uint8_t}).
1926
1927@item RANGE:
1928Valid values for this configuration parameter must be one (1) less than
1929than a power of two (2) between 4 and 256 inclusively.  In other words,
1930valid values are 3, 7, 31, 63, 127, and 255.
1931
1932@item DEFAULT VALUE:
1933The default value is 255, because RTEMS must support 256 priority levels to be
1934compliant with various standards. These priorities range from zero (0) to 255.
1935
1936@end table
1937
1938@subheading DESCRIPTION:
1939This configuration parameter specified the maximum numeric priority
1940of any task in the system and one less that the number of priority levels
1941in the system.
1942
1943Reducing the number of priorities in the system reduces the amount of
1944memory allocated from the RTEMS Workspace.
1945
1946@subheading NOTES:
1947The numerically greatest priority is the logically lowest priority in
1948the system and will thus be used by the IDLE task.
1949
1950Priority zero (0) is reserved for internal use by RTEMS and is not
1951available to applications.
1952
1953With some schedulers, reducing the number of priorities can reduce the
1954amount of memory used by the scheduler. For example, the Deterministic
1955Priority Scheduler (DPS) used by default uses three pointers of storage
1956per priority level. Reducing the number of priorities from 256 levels
1957to sixteen (16) can reduce memory usage by about three (3) kilobytes.
1958
1959@c
1960@c === CONFIGURE_MINIMUM_TASK_STACK_SIZE ===
1961@c
1962@subsection Specifying the Minimum Task Size
1963
1964@findex CONFIGURE_MINIMUM_TASK_STACK_SIZE
1965@cindex minimum task stack size
1966
1967@table @b
1968@item CONSTANT:
1969@code{CONFIGURE_MINIMUM_TASK_STACK_SIZE}
1970
1971@item DATA TYPE:
1972Unsigned integer (@code{uint32_t}).
1973
1974@item RANGE:
1975Positive.
1976
1977@item DEFAULT VALUE:
1978This is not defined by default, which sets the executive to the recommended
1979minimum stack size for this processor.
1980
1981@end table
1982
1983@subheading DESCRIPTION:
1984The configuration parameter is set to the number of bytes the application
1985wants the minimum stack size to be for every task or thread in the system.
1986
1987Adjusting this parameter should be done with caution. Examining the actual
1988usage using the Stack Checker Usage Reporting facility is recommended.
1989
1990@subheading NOTES:
1991This parameter can be used to lower the minimum from that
1992recommended. This can be used in low memory systems to reduce memory
1993consumption for stacks. However, this must be done with caution as it
1994could increase the possibility of a blown task stack.
1995
1996This parameter can be used to increase the minimum from that
1997recommended. This can be used in higher memory systems to reduce the
1998risk of stack overflow without performing analysis on actual consumption.
1999
2000@c
2001@c === CONFIGURE_INTERRUPT_STACK_SIZE ===
2002@c
2003@subsection Configuring the Size of the Interrupt Stack
2004
2005@findex CONFIGURE_INTERRUPT_STACK_SIZE
2006@cindex interrupt stack size
2007
2008@table @b
2009@item CONSTANT:
2010@code{CONFIGURE_INTERRUPT_STACK_SIZE}
2011
2012@item DATA TYPE:
2013Unsigned integer (@code{uint32_t}).
2014
2015@item RANGE:
2016Positive.
2017
2018@item DEFAULT VALUE:
2019The default value is CONFIGURE_MINIMUM_TASK_STACK_SIZE, which is the minimum
2020interrupt stack size.
2021
2022@end table
2023
2024@subheading DESCRIPTION:
2025@code{CONFIGURE_INTERRUPT_STACK_SIZE} is set to the size of the
2026interrupt stack.  The interrupt stack size is often set by the BSP but
2027since this memory may be allocated from the RTEMS Workspace, it must be
2028accounted for.
2029
2030@subheading NOTES:
2031In some BSPs, changing this constant does NOT change the
2032size of the interrupt stack, only the amount of memory
2033reserved for it.
2034
2035Patches which result in this constant only being used in memory
2036calculations when the interrupt stack is intended to be allocated
2037from the RTEMS Workspace would be welcomed by the RTEMS Project.
2038
2039@c
2040@c === CONFIGURE_EXTRA_TASK_STACKS ===
2041@c
2042@subsection Reserve Task/Thread Stack Memory Above Minimum
2043
2044@findex CONFIGURE_EXTRA_TASK_STACKS
2045@cindex memory for task tasks
2046
2047@table @b
2048@item CONSTANT:
2049@code{CONFIGURE_EXTRA_TASK_STACKS}
2050
2051@item DATA TYPE:
2052Unsigned integer (@code{size_t}).
2053
2054@item RANGE:
2055Undefined or positive.
2056
2057@item DEFAULT VALUE:
2058The default value is 0.
2059
2060@end table
2061
2062@subheading DESCRIPTION:
2063This configuration parameter is set to the number of bytes the
2064applications wishes to add to the task stack requirements calculated
2065by @code{<rtems/confdefs.h>}.
2066
2067@subheading NOTES:
2068This parameter is very important.  If the application creates tasks with
2069stacks larger then the minimum, then that memory is NOT accounted for
2070by @code{<rtems/confdefs.h>}.
2071
2072@c
2073@c === CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY ===
2074@c
2075@subsection Automatically Zeroing the RTEMS Workspace and C Program Heap
2076
2077@findex CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY
2078@cindex clear C Program Heap
2079@cindex clear RTEMS Workspace
2080@cindex zero C Program Heap
2081@cindex zero RTEMS Workspace
2082
2083@table @b
2084@item CONSTANT:
2085@code{CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY}
2086
2087@item DATA TYPE:
2088Boolean feature macro.
2089
2090@item RANGE:
2091Defined or undefined.
2092
2093@item DEFAULT VALUE:
2094This is not defined by default, unless overridden by the BSP.
2095The default is @b{NOT} to zero out the RTEMS Workspace or C Program Heap.
2096
2097@end table
2098
2099@subheading DESCRIPTION:
2100This macro indicates whether RTEMS should zero the RTEMS Workspace and
2101C Program Heap as part of its initialization.  If defined, the memory
2102regions are zeroed.  Otherwise, they are not.
2103
2104@subheading NOTES:
2105Zeroing memory can add significantly to system boot time. It is not
2106necessary for RTEMS but is often assumed by support libraries.
2107
2108@c
2109@c === CONFIGURE_STACK_CHECKER_ENABLED ===
2110@c
2111@subsection Enable The Task Stack Usage Checker
2112
2113@findex CONFIGURE_STACK_CHECKER_ENABLED
2114
2115@table @b
2116@item CONSTANT:
2117@code{CONFIGURE_STACK_CHECKER_ENABLED}
2118
2119@item DATA TYPE:
2120Boolean feature macro.
2121
2122@item RANGE:
2123Defined or undefined.
2124
2125@item DEFAULT VALUE:
2126This is not defined by default, and thus stack checking is disabled.
2127
2128@end table
2129
2130@subheading DESCRIPTION:
2131This configuration parameter is defined when the application wishes to
2132enable run-time stack bounds checking.
2133
2134
2135@subheading NOTES:
2136In 4.9 and older, this configuration parameter was named
2137@code{STACK_CHECKER_ON}.
2138
2139This increases the time required to create tasks as well as adding
2140overhead to each context switch.
2141
2142@c
2143@c === CONFIGURE_INITIAL_EXTENSIONS ===
2144@c
2145@subsection Specify Application Specific User Extensions
2146
2147@findex CONFIGURE_INITIAL_EXTENSIONS
2148
2149@table @b
2150@item CONSTANT:
2151@code{CONFIGURE_INITIAL_EXTENSIONS}
2152
2153@item DATA TYPE:
2154List of user extension initializers (@code{rtems_extensions_table}).
2155
2156@item RANGE:
2157Undefined or a list of one or more user extensions.
2158
2159@item DEFAULT VALUE:
2160This is not defined by default.
2161
2162@end table
2163
2164@subheading DESCRIPTION:
2165If @code{CONFIGURE_INITIAL_EXTENSIONS} is defined by the application,
2166then this application specific set of initial extensions will be placed
2167in the initial extension table.
2168
2169@subheading NOTES:
2170None.
2171
2172@c
2173@c === Custom Stack Allocator ===
2174@c
2175@section Configuring Custom Task Stack Allocation
2176
2177RTEMS allows the application or BSP to define its own allocation and
2178deallocation methods for task stacks. This can be used to place task
2179stacks in special areas of memory or to utilize a Memory Management Unit
2180so that stack overflows are detected in hardware.
2181
2182@c
2183@c === CONFIGURE_TASK_STACK_ALLOCATOR_INIT ===
2184@c
2185@subsection Custom Task Stack Allocator Initialization
2186
2187@findex CONFIGURE_TASK_STACK_ALLOCATOR_INIT
2188
2189@table @b
2190@item CONSTANT:
2191@code{CONFIGURE_TASK_STACK_ALLOCATOR_INIT}
2192
2193@item DATA TYPE:
2194Function pointer.
2195
2196@item RANGE:
2197Undefined, NULL or valid function pointer.
2198
2199@item DEFAULT VALUE:
2200The default value is NULL, which indicates that
2201task stacks will be allocated from the RTEMS Workspace.
2202
2203@end table
2204
2205@subheading DESCRIPTION:
2206@code{CONFIGURE_TASK_STACK_ALLOCATOR_INIT} configures the initialization
2207method for an application or BSP specific task stack allocation
2208implementation.
2209
2210@subheading NOTES:
2211A correctly configured system must configure the following to be consistent:
2212
2213@itemize @bullet
2214@item @code{CONFIGURE_TASK_STACK_ALLOCATOR_INIT}
2215@item @code{CONFIGURE_TASK_STACK_ALLOCATOR}
2216@item @code{CONFIGURE_TASK_STACK_DEALLOCATOR}
2217@end itemize
2218
2219@c
2220@c === CONFIGURE_TASK_STACK_ALLOCATOR ===
2221@c
2222@subsection Custom Task Stack Allocator
2223
2224@findex CONFIGURE_TASK_STACK_ALLOCATOR
2225
2226@cindex task stack allocator
2227
2228@table @b
2229@item CONSTANT:
2230@code{CONFIGURE_TASK_STACK_ALLOCATOR}
2231
2232@item DATA TYPE:
2233Function pointer.
2234
2235@item RANGE:
2236Undefined or valid function pointer.
2237
2238@item DEFAULT VALUE:
2239The default value is @code{_Workspace_Allocate}, which indicates
2240that task stacks will be allocated from the RTEMS Workspace.
2241
2242@end table
2243
2244@subheading DESCRIPTION:
2245@code{CONFIGURE_TASK_STACK_ALLOCATOR} may point to a user provided
2246routine to allocate task stacks.
2247
2248@subheading NOTES:
2249A correctly configured system must configure the following to be consistent:
2250
2251@itemize @bullet
2252@item @code{CONFIGURE_TASK_STACK_ALLOCATOR_INIT}
2253@item @code{CONFIGURE_TASK_STACK_ALLOCATOR}
2254@item @code{CONFIGURE_TASK_STACK_DEALLOCATOR}
2255@end itemize
2256
2257@c
2258@c === CONFIGURE_TASK_STACK_DEALLOCATOR ===
2259@c
2260@subsection Custom Task Stack Deallocator
2261
2262@findex CONFIGURE_TASK_STACK_DEALLOCATOR
2263@cindex task stack deallocator
2264
2265@table @b
2266@item CONSTANT:
2267@code{CONFIGURE_TASK_STACK_DEALLOCATOR}
2268
2269@item DATA TYPE:
2270Function pointer.
2271
2272@item RANGE:
2273Undefined or valid function pointer.
2274
2275@item DEFAULT VALUE:
2276The default value is @code{_Workspace_Free}, which indicates that
2277task stacks will be allocated from the RTEMS Workspace.
2278
2279@end table
2280
2281@subheading DESCRIPTION:
2282@code{CONFIGURE_TASK_STACK_DEALLOCATOR} may point to a user provided
2283routine to free task stacks.
2284
2285@subheading NOTES:
2286A correctly configured system must configure the following to be consistent:
2287
2288@itemize @bullet
2289@item @code{CONFIGURE_TASK_STACK_ALLOCATOR_INIT}
2290@item @code{CONFIGURE_TASK_STACK_ALLOCATOR}
2291@item @code{CONFIGURE_TASK_STACK_DEALLOCATOR}
2292@end itemize
2293
2294@c
2295@c === Classic API Message Buffers ===
2296@c
2297@section Configuring Memory for Classic API Message Buffers
2298
2299This section describes the configuration parameters related to specifying
2300the amount of memory reserved for Classic API Message Buffers.
2301
2302@c
2303@c === CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE ===
2304@c
2305@subsection Calculate Memory for a Single Classic Message API Message Queue
2306
2307@findex CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE
2308@cindex memory for a single message queue's buffers
2309
2310@table @b
2311@item CONSTANT:
2312@code{CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)}
2313
2314@item DATA TYPE:
2315Unsigned integer (@code{size_t}).
2316
2317@item RANGE:
2318Positive.
2319
2320@item DEFAULT VALUE:
2321The default value is None.
2322
2323@end table
2324
2325@subheading DESCRIPTION:
2326This is a helper macro which is used to assist in computing the total
2327amount of memory required for message buffers.  Each message queue will
2328have its own configuration with maximum message size and maximum number
2329of pending messages.
2330
2331The interface for this macro is as follows:
2332
2333@example
2334CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)
2335@end example
2336
2337Where @code{max_messages} is the maximum number of pending messages
2338and @code{size_per} is the size in bytes of the user message.
2339
2340@subheading NOTES:
2341This macro is only used in support of @code{CONFIGURE_MESSAGE_BUFFER_MEMORY}.
2342
2343@c
2344@c === CONFIGURE_MESSAGE_BUFFER_MEMORY ===
2345@c
2346@subsection Reserve Memory for All Classic Message API Message Queues
2347
2348@findex CONFIGURE_MESSAGE_BUFFER_MEMORY
2349@cindex configure message queue buffer memory
2350
2351@table @b
2352@item CONSTANT:
2353@code{CONFIGURE_MESSAGE_BUFFER_MEMORY}
2354
2355@item DATA TYPE:
2356integer summation macro
2357
2358@item RANGE:
2359undefined (zero) or calculation resulting in a positive integer
2360
2361@item DEFAULT VALUE:
2362This is not defined by default, and zero (0) memory is reserved.
2363
2364@end table
2365
2366@subheading DESCRIPTION:
2367This macro is set to the number of bytes the application requires to be
2368reserved for pending Classic API Message Queue buffers.
2369
2370@subheading NOTES:
2371The following illustrates how the help macro
2372@code{CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE} can be used to assist in
2373calculating the message buffer memory required.  In this example, there
2374are two message queues used in this application.  The first message
2375queue has maximum of 24 pending messages with the message structure
2376defined by the type @code{one_message_type}.  The other message queue
2377has maximum of 500 pending messages with the message structure defined
2378by the type @code{other_message_type}.
2379
2380@example
2381@group
2382#define CONFIGURE_MESSAGE_BUFFER_MEMORY \
2383 (CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \
2384    24, sizeof(one_message_type) + \
2385  CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \
2386    500, sizeof(other_message_type) \
2387 )
2388@end group
2389@end example
2390
2391@c
2392@c === Seldom Used Configuration Parameters ===
2393@c
2394@section Seldom Used Configuration Parameters
2395
2396This section describes configuration parameters supported by
2397@code{<rtems/confdefs.h>} which are seldom used by applications. These
2398parameters tend to be oriented to debugging system configurations
2399and providing work-arounds when the memory estimated by
2400@code{<rtems/confdefs.h>} is incorrect.
2401
2402@c
2403@c === CONFIGURE_MEMORY_OVERHEAD ===
2404@c
2405@subsection Specify Memory Overhead
2406
2407@findex CONFIGURE_MEMORY_OVERHEAD
2408
2409@table @b
2410@item CONSTANT:
2411@code{CONFIGURE_MEMORY_OVERHEAD}
2412
2413@item DATA TYPE:
2414Unsigned integer (@code{size_t}).
2415
2416@item RANGE:
2417Zero or positive.
2418
2419@item DEFAULT VALUE:
2420The default value is 0.
2421
2422@end table
2423
2424@subheading DESCRIPTION:
2425Thie parameter is set to the number of kilobytes the application wishes
2426to add to the requirements calculated by @code{<rtems/confdefs.h>}.
2427
2428@subheading NOTES:
2429This configuration parameter should only be used when it is suspected that
2430a bug in @code{<rtems/confdefs.h>} has resulted in an underestimation.
2431Typically the memory allocation will be too low when an application does
2432not account for all message queue buffers or task stacks.
2433
2434@c
2435@c === CONFIGURE_HAS_OWN_CONFIGURATION_TABLE ===
2436@c
2437@subsection Do Not Generate Configuration Information
2438
2439@findex CONFIGURE_HAS_OWN_CONFIGURATION_TABLE
2440
2441@table @b
2442@item CONSTANT:
2443@code{CONFIGURE_HAS_OWN_CONFIGURATION_TABLE}
2444
2445@item DATA TYPE:
2446Boolean feature macro.
2447
2448@item RANGE:
2449Defined or undefined.
2450
2451@item DEFAULT VALUE:
2452This is not defined by default.
2453
2454@end table
2455
2456@subheading DESCRIPTION:
2457This configuration parameter should only be defined if the application
2458is providing their own complete set of configuration tables.
2459
2460@subheading NOTES:
2461None.
2462
2463@c
2464@c === C Library Support Configuration ===
2465@c
2466@section C Library Support Configuration
2467
2468This section defines the file system and IO library
2469related configuration parameters supported by
2470@code{<rtems/confdefs.h>}.
2471
2472@c
2473@c === CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS ===
2474@c
2475@subsection Specify Maximum Number of File Descriptors
2476
2477@findex CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS
2478@cindex maximum file descriptors
2479
2480@table @b
2481@item CONSTANT:
2482@code{CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS}
2483
2484@item DATA TYPE:
2485Unsigned integer (@code{uint32_t}).
2486
2487@item RANGE:
2488Zero or positive.
2489
2490@item DEFAULT VALUE:
2491
2492If @code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER} is defined, then the
2493default value is 3, otherwise the default value is 0.
2494
2495Three file descriptors allows RTEMS to support standard input, output, and
2496error I/O streams on @code{/dev/console}.
2497
2498@end table
2499
2500@subheading DESCRIPTION:
2501This configuration parameter is set to the maximum number of file like objects
2502that can be concurrently open.
2503
2504@subheading NOTES:
2505None.
2506
2507@c
2508@c === CONFIGURE_TERMIOS_DISABLED ===
2509@c
2510@subsection Disable POSIX Termios Support
2511
2512@findex CONFIGURE_TERMIOS_DISABLED
2513
2514@table @b
2515@item CONSTANT:
2516@code{CONFIGURE_TERMIOS_DISABLED}
2517
2518@item DATA TYPE:
2519Boolean feature macro.
2520
2521@item RANGE:
2522Defined or undefined.
2523
2524@item DEFAULT VALUE:
2525This is not defined by default, and resources are reserved for the
2526termios functionality.
2527
2528@end table
2529
2530@subheading DESCRIPTION:
2531This configuration parameter is defined if the software implementing
2532POSIX termios functionality is not going to be used by this application.
2533
2534@subheading NOTES:
2535The termios support library should not be included in an application
2536executable unless it is directly referenced by the application or a
2537device driver.
2538
2539@c
2540@c === CONFIGURE_NUMBER_OF_TERMIOS_PORTS ===
2541@c
2542@subsection Specify Maximum Termios Ports
2543
2544@findex CONFIGURE_NUMBER_OF_TERMIOS_PORTS
2545
2546@table @b
2547@item CONSTANT:
2548@code{CONFIGURE_NUMBER_OF_TERMIOS_PORTS}
2549
2550@item DATA TYPE:
2551Unsigned integer.
2552
2553@item RANGE:
2554Zero or positive.
2555
2556@item DEFAULT VALUE:
2557The default value is 1, so a console port can be used.
2558
2559@end table
2560
2561@subheading DESCRIPTION:
2562This configuration parameter is set to the number of ports using the
2563termios functionality.  Each concurrently active termios port requires
2564resources.
2565
2566@subheading NOTES:
2567If the application will be using serial ports
2568including, but not limited to, the Console Device
2569(e.g. @code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER}), then it is
2570highly likely that this configuration parameter should NOT be is defined.
2571
2572@c
2573@c === File System Configuration Parameters ===
2574@c
2575@section File System Configuration Parameters
2576
2577This section defines File System related configuration parameters.
2578
2579@c
2580@c === CONFIGURE_HAS_OWN_MOUNT_TABLE ===
2581@c
2582@subsection Providing Application Specific Mount Table
2583
2584@findex CONFIGURE_HAS_OWN_MOUNT_TABLE
2585
2586@table @b
2587@item CONSTANT:
2588@code{CONFIGURE_HAS_OWN_MOUNT_TABLE}
2589
2590@item DATA TYPE:
2591Undefined or an array of type @code{rtems_filesystem_mount_table_t}.
2592
2593@item RANGE:
2594Undefined or an array of type @code{rtems_filesystem_mount_table_t}.
2595
2596@item DEFAULT VALUE:
2597This is not defined by default.
2598
2599@end table
2600
2601@subheading DESCRIPTION:
2602This configuration parameter is defined when the application
2603provides their own filesystem mount table.  The mount table is an
2604array of @code{rtems_filesystem_mount_table_t} entries pointed
2605to by the global variable @code{rtems_filesystem_mount_table}.
2606The number of entries in this table is in an integer variable named
2607@code{rtems_filesystem_mount_table_t}.
2608
2609@c XXX - is the variable name for the count right?
2610
2611@subheading NOTES:
2612None.
2613@c XXX - Please provide an example
2614
2615@c
2616@c === CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM ===
2617@c
2618@subsection Configure devFS as Root File System
2619
2620@findex CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM
2621
2622@table @b
2623@item CONSTANT:
2624@code{CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM}
2625
2626@item DATA TYPE:
2627Boolean feature macro.
2628
2629@item RANGE:
2630Defined or undefined.
2631
2632@item DEFAULT VALUE:
2633This is not defined by default. If no other root file system
2634configuration parameters are specified, the IMFS will be used as the
2635root file system.
2636
2637@end table
2638
2639@subheading DESCRIPTION:
2640This configuration parameter is defined if the application wishes to
2641use the device-only filesytem as the root file system.
2642
2643@subheading NOTES:
2644The device-only filesystem supports only device nodes and is smaller in
2645executable code size than the full IMFS and miniIMFS.
2646
2647The devFS is comparable in functionality to the pseudo-filesystem name
2648space provided before RTEMS release 4.5.0.
2649
2650@c
2651@c === CONFIGURE_MAXIMUM_DEVICES ===
2652@c
2653@subsection Specifying Maximum Devices for devFS
2654
2655@findex CONFIGURE_MAXIMUM_DEVICES
2656
2657@table @b
2658@item CONSTANT:
2659@code{CONFIGURE_MAXIMUM_DEVICES}
2660
2661@item DATA TYPE:
2662Unsigned integer (@code{uint32_t}).
2663
2664@item RANGE:
2665Positive.
2666
2667@item DEFAULT VALUE:
2668If @code{BSP_MAXIMUM_DEVICES} is defined, then the
2669default value is @code{BSP_MAXIMUM_DEVICES}, otherwise the default value is 4.
2670
2671@end table
2672
2673@subheading DESCRIPTION:
2674@code{CONFIGURE_MAXIMUM_DEVICES} is defined to the number of
2675individual devices that may be registered in the device file system (devFS).
2676
2677@subheading NOTES:
2678This option is specific to the device file system (devFS) and should not be
2679confused with the @code{CONFIGURE_MAXIMUM_DRIVERS} option.  This parameter only
2680impacts the devFS and thus is only used by @code{<rtems/confdefs.h>} when
2681@code{CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM} is specified.
2682
2683@c
2684@c === CONFIGURE_APPLICATION_DISABLE_FILESYSTEM ===
2685@c
2686@subsection Disable File System Support
2687
2688@findex CONFIGURE_APPLICATION_DISABLE_FILESYSTEM
2689
2690@table @b
2691@item CONSTANT:
2692@code{CONFIGURE_APPLICATION_DISABLE_FILESYSTEM}
2693
2694@item DATA TYPE:
2695Boolean feature macro.
2696
2697@item RANGE:
2698Defined or undefined.
2699
2700@item DEFAULT VALUE:
2701This is not defined by default. If no other root file system
2702configuration parameters are specified, the IMFS will be used as the
2703root file system.
2704
2705@end table
2706
2707@subheading DESCRIPTION:
2708This configuration parameter is defined if the application dose not
2709intend to use any kind of filesystem support. This include the device
2710infrastructure necessary to support @code{printf()}.
2711
2712@subheading NOTES:
2713None.
2714
2715@c
2716@c === CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM ===
2717@c
2718@subsection Use a Root IMFS with a Minimalistic Feature Set
2719
2720@findex CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM
2721
2722@table @b
2723@item CONSTANT:
2724@code{CONFIGURE_USE_MINIIMFS_AS_BASE_FILESYSTEM}
2725
2726@item DATA TYPE:
2727Boolean feature macro.
2728
2729@item RANGE:
2730Defined or undefined.
2731
2732@item DEFAULT VALUE:
2733This is not defined by default.
2734
2735@end table
2736
2737@subheading DESCRIPTION:
2738In case this configuration option is defined, then the following configuration
2739options will be defined as well
2740@itemize @bullet
2741@item @code{CONFIGURE_IMFS_DISABLE_CHMOD},
2742@item @code{CONFIGURE_IMFS_DISABLE_CHOWN},
2743@item @code{CONFIGURE_IMFS_DISABLE_UTIME},
2744@item @code{CONFIGURE_IMFS_DISABLE_LINK},
2745@item @code{CONFIGURE_IMFS_DISABLE_SYMLINK},
2746@item @code{CONFIGURE_IMFS_DISABLE_READLINK},
2747@item @code{CONFIGURE_IMFS_DISABLE_RENAME}, and
2748@item @code{CONFIGURE_IMFS_DISABLE_UNMOUNT}.
2749@end itemize
2750
2751@c
2752@c === CONFIGURE_IMFS_DISABLE_CHOWN ===
2753@c
2754@subsection Disable Change Owner Support of Root IMFS
2755
2756@findex CONFIGURE_IMFS_DISABLE_CHOWN
2757
2758@table @b
2759@item CONSTANT:
2760@code{CONFIGURE_IMFS_DISABLE_CHOWN}
2761
2762@item DATA TYPE:
2763Boolean feature macro.
2764
2765@item RANGE:
2766Defined or undefined.
2767
2768@item DEFAULT VALUE:
2769This is not defined by default.
2770
2771@end table
2772
2773@subheading DESCRIPTION:
2774In case this configuration option is defined, then the support to change the
2775owner is disabled in the root IMFS.
2776
2777@c
2778@c === CONFIGURE_IMFS_DISABLE_CHMOD ===
2779@c
2780@subsection Disable Change Mode Support of Root IMFS
2781
2782@findex CONFIGURE_IMFS_DISABLE_CHMOD
2783
2784@table @b
2785@item CONSTANT:
2786@code{CONFIGURE_IMFS_DISABLE_CHMOD}
2787
2788@item DATA TYPE:
2789Boolean feature macro.
2790
2791@item RANGE:
2792Defined or undefined.
2793
2794@item DEFAULT VALUE:
2795This is not defined by default.
2796
2797@end table
2798
2799@subheading DESCRIPTION:
2800In case this configuration option is defined, then the support to change the
2801mode is disabled in the root IMFS.
2802
2803@c
2804@c === CONFIGURE_IMFS_DISABLE_UTIME ===
2805@c
2806@subsection Disable Change Times Support of Root IMFS
2807
2808@findex CONFIGURE_IMFS_DISABLE_UTIME
2809
2810@table @b
2811@item CONSTANT:
2812@code{CONFIGURE_IMFS_DISABLE_UTIME}
2813
2814@item DATA TYPE:
2815Boolean feature macro.
2816
2817@item RANGE:
2818Defined or undefined.
2819
2820@item DEFAULT VALUE:
2821This is not defined by default.
2822
2823@end table
2824
2825@subheading DESCRIPTION:
2826In case this configuration option is defined, then the support to change times
2827is disabled in the root IMFS.
2828
2829@c
2830@c === CONFIGURE_IMFS_DISABLE_LINK ===
2831@c
2832@subsection Disable Create Hard Link Support of Root IMFS
2833
2834@findex CONFIGURE_IMFS_DISABLE_LINK
2835
2836@table @b
2837@item CONSTANT:
2838@code{CONFIGURE_IMFS_DISABLE_LINK}
2839
2840@item DATA TYPE:
2841Boolean feature macro.
2842
2843@item RANGE:
2844Defined or undefined.
2845
2846@item DEFAULT VALUE:
2847This is not defined by default.
2848
2849@end table
2850
2851@subheading DESCRIPTION:
2852In case this configuration option is defined, then the support to create hard
2853links is disabled in the root IMFS.
2854
2855@c
2856@c === CONFIGURE_IMFS_DISABLE_SYMLINK ===
2857@c
2858@subsection Disable Create Symbolic Link Support of Root IMFS
2859
2860@findex CONFIGURE_IMFS_DISABLE_SYMLINK
2861
2862@table @b
2863@item CONSTANT:
2864@code{CONFIGURE_IMFS_DISABLE_SYMLINK}
2865
2866@item DATA TYPE:
2867Boolean feature macro.
2868
2869@item RANGE:
2870Defined or undefined.
2871
2872@item DEFAULT VALUE:
2873This is not defined by default.
2874
2875@end table
2876
2877@subheading DESCRIPTION:
2878In case this configuration option is defined, then the support to create
2879symbolic links is disabled in the root IMFS.
2880
2881@c
2882@c === CONFIGURE_IMFS_DISABLE_READLINK ===
2883@c
2884@subsection Disable Read Symbolic Link Support of Root IMFS
2885
2886@findex CONFIGURE_IMFS_DISABLE_READLINK
2887
2888@table @b
2889@item CONSTANT:
2890@code{CONFIGURE_IMFS_DISABLE_READLINK}
2891
2892@item DATA TYPE:
2893Boolean feature macro.
2894
2895@item RANGE:
2896Defined or undefined.
2897
2898@item DEFAULT VALUE:
2899This is not defined by default.
2900
2901@end table
2902
2903@subheading DESCRIPTION:
2904In case this configuration option is defined, then the support to read symbolic
2905links is disabled in the root IMFS.
2906
2907@c
2908@c === CONFIGURE_IMFS_DISABLE_RENAME ===
2909@c
2910@subsection Disable Rename Support of Root IMFS
2911
2912@findex CONFIGURE_IMFS_DISABLE_RENAME
2913
2914@table @b
2915@item CONSTANT:
2916@code{CONFIGURE_IMFS_DISABLE_RENAME}
2917
2918@item DATA TYPE:
2919Boolean feature macro.
2920
2921@item RANGE:
2922Defined or undefined.
2923
2924@item DEFAULT VALUE:
2925This is not defined by default.
2926
2927@end table
2928
2929@subheading DESCRIPTION:
2930In case this configuration option is defined, then the support to rename nodes
2931is disabled in the root IMFS.
2932
2933@c
2934@c === CONFIGURE_IMFS_DISABLE_READDIR ===
2935@c
2936@subsection Disable Directory Read Support of Root IMFS
2937
2938@findex CONFIGURE_IMFS_DISABLE_READDIR
2939
2940@table @b
2941@item CONSTANT:
2942@code{CONFIGURE_IMFS_DISABLE_READDIR}
2943
2944@item DATA TYPE:
2945Boolean feature macro.
2946
2947@item RANGE:
2948Defined or undefined.
2949
2950@item DEFAULT VALUE:
2951This is not defined by default.
2952
2953@end table
2954
2955@subheading DESCRIPTION:
2956In case this configuration option is defined, then the support to read a
2957directory is disabled in the root IMFS.  It is still possible to open nodes in
2958a directory.
2959
2960@c
2961@c === CONFIGURE_IMFS_DISABLE_MOUNT ===
2962@c
2963@subsection Disable Mount Support of Root IMFS
2964
2965@findex CONFIGURE_IMFS_DISABLE_MOUNT
2966
2967@table @b
2968@item CONSTANT:
2969@code{CONFIGURE_IMFS_DISABLE_MOUNT}
2970
2971@item DATA TYPE:
2972Boolean feature macro.
2973
2974@item RANGE:
2975Defined or undefined.
2976
2977@item DEFAULT VALUE:
2978This is not defined by default.
2979
2980@end table
2981
2982@subheading DESCRIPTION:
2983In case this configuration option is defined, then the support to mount other
2984file systems is disabled in the root IMFS.
2985
2986@c
2987@c === CONFIGURE_IMFS_DISABLE_UNMOUNT ===
2988@c
2989@subsection Disable Unmount Support of Root IMFS
2990
2991@findex CONFIGURE_IMFS_DISABLE_UNMOUNT
2992
2993@table @b
2994@item CONSTANT:
2995@code{CONFIGURE_IMFS_DISABLE_UNMOUNT}
2996
2997@item DATA TYPE:
2998Boolean feature macro.
2999
3000@item RANGE:
3001Defined or undefined.
3002
3003@item DEFAULT VALUE:
3004This is not defined by default.
3005
3006@end table
3007
3008@subheading DESCRIPTION:
3009In case this configuration option is defined, then the support to unmount file
3010systems is disabled in the root IMFS.
3011
3012@c
3013@c === CONFIGURE_IMFS_DISABLE_MKNOD ===
3014@c
3015@subsection Disable Make Nodes Support of Root IMFS
3016
3017@findex CONFIGURE_IMFS_DISABLE_MKNOD
3018
3019@table @b
3020@item CONSTANT:
3021@code{CONFIGURE_IMFS_DISABLE_MKNOD}
3022
3023@item DATA TYPE:
3024Boolean feature macro.
3025
3026@item RANGE:
3027Defined or undefined.
3028
3029@item DEFAULT VALUE:
3030This is not defined by default.
3031
3032@end table
3033
3034@subheading DESCRIPTION:
3035In case this configuration option is defined, then the support to make
3036directories, devices, regular files and FIFOs is disabled in the root IMFS.
3037
3038@c
3039@c === CONFIGURE_IMFS_DISABLE_MKNOD_FILE ===
3040@c
3041@subsection Disable Make Files Support of Root IMFS
3042
3043@findex CONFIGURE_IMFS_DISABLE_MKNOD_FILE
3044
3045@table @b
3046@item CONSTANT:
3047@code{CONFIGURE_IMFS_DISABLE_MKNOD_FILE}
3048
3049@item DATA TYPE:
3050Boolean feature macro.
3051
3052@item RANGE:
3053Defined or undefined.
3054
3055@item DEFAULT VALUE:
3056This is not defined by default.
3057
3058@end table
3059
3060@subheading DESCRIPTION:
3061In case this configuration option is defined, then the support to make regular
3062files is disabled in the root IMFS.
3063
3064@c
3065@c === CONFIGURE_IMFS_DISABLE_RMNOD ===
3066@c
3067@subsection Disable Remove Nodes Support of Root IMFS
3068
3069@findex CONFIGURE_IMFS_DISABLE_RMNOD
3070
3071@table @b
3072@item CONSTANT:
3073@code{CONFIGURE_IMFS_DISABLE_RMNOD}
3074
3075@item DATA TYPE:
3076Boolean feature macro.
3077
3078@item RANGE:
3079Defined or undefined.
3080
3081@item DEFAULT VALUE:
3082This is not defined by default.
3083
3084@end table
3085
3086@subheading DESCRIPTION:
3087In case this configuration option is defined, then the support to remove nodes
3088is disabled in the root IMFS.
3089
3090@c
3091@c === Block Device Cache Configuration ===
3092@c
3093@section Block Device Cache Configuration
3094
3095This section defines Block Device Cache (bdbuf) related configuration
3096parameters.
3097
3098@c
3099@c === CONFIGURE_APPLICATION_NEEDS_LIBBLOCK ===
3100@c
3101@subsection Enable Block Device Cache
3102
3103@findex CONFIGURE_APPLICATION_NEEDS_LIBBLOCK
3104
3105@table @b
3106@item CONSTANT:
3107@code{CONFIGURE_APPLICATION_NEEDS_LIBBLOCK}
3108
3109@item DATA TYPE:
3110Boolean feature macro.
3111
3112@item RANGE:
3113Defined or undefined.
3114
3115@item DEFAULT VALUE:
3116This is not defined by default.
3117
3118@end table
3119
3120@subheading DESCRIPTION:
3121Provides a Block Device Cache configuration.
3122
3123@subheading NOTES:
3124Each option of the Block Device Cache configuration can be explicitly set by
3125the user with the configuration options below.  The Block Device Cache is used
3126for example by the RFS and DOSFS file systems.
3127
3128@c
3129@c === CONFIGURE_BDBUF_CACHE_MEMORY_SIZE ===
3130@c
3131@subsection Size of the Cache Memory
3132
3133@findex CONFIGURE_BDBUF_CACHE_MEMORY_SIZE
3134
3135@table @b
3136@item CONSTANT:
3137@code{CONFIGURE_BDBUF_CACHE_MEMORY_SIZE}
3138
3139@item DATA TYPE:
3140Unsigned integer (@code{size_t}).
3141
3142@item RANGE:
3143Positive.
3144
3145@item DEFAULT VALUE:
3146The default value is 32768 bytes.
3147
3148@end table
3149
3150@subheading DESCRIPTION:
3151Size of the cache memory in bytes.
3152
3153@subheading NOTES:
3154None.
3155
3156@c
3157@c === CONFIGURE_BDBUF_BUFFER_MIN_SIZE ===
3158@c
3159@subsection Minimum Size of a Buffer
3160
3161@findex CONFIGURE_BDBUF_BUFFER_MIN_SIZE
3162
3163@table @b
3164@item CONSTANT:
3165@code{CONFIGURE_BDBUF_BUFFER_MIN_SIZE}
3166
3167@item DATA TYPE:
3168Unsigned integer (@code{uint32_t}).
3169
3170@item RANGE:
3171Positive.
3172
3173@item DEFAULT VALUE:
3174The default value is 512 bytes.
3175
3176@end table
3177
3178@subheading DESCRIPTION:
3179Defines the minimum size of a buffer in bytes.
3180
3181@subheading NOTES:
3182None.
3183
3184@c
3185@c === CONFIGURE_BDBUF_BUFFER_MAX_SIZE ===
3186@c
3187@subsection Maximum Size of a Buffer
3188
3189@findex CONFIGURE_BDBUF_BUFFER_MAX_SIZE
3190
3191@table @b
3192@item CONSTANT:
3193@code{CONFIGURE_BDBUF_BUFFER_MAX_SIZE}
3194
3195@item DATA TYPE:
3196Unsigned integer (@code{uint32_t}).
3197
3198@item RANGE:
3199It must be positive and an integral multiple of the buffer minimum size.
3200
3201@item DEFAULT VALUE:
3202The default value is 4096 bytes.
3203
3204@end table
3205
3206@subheading DESCRIPTION:
3207Defines the maximum size of a buffer in bytes.
3208
3209@subheading NOTES:
3210None.
3211
3212@c
3213@c === CONFIGURE_SWAPOUT_SWAP_PERIOD ===
3214@c
3215@subsection Swapout Task Swap Period
3216
3217@findex CONFIGURE_SWAPOUT_SWAP_PERIOD
3218
3219@table @b
3220@item CONSTANT:
3221@code{CONFIGURE_SWAPOUT_SWAP_PERIOD}
3222
3223@item DATA TYPE:
3224Unsigned integer (@code{uint32_t}).
3225
3226@item RANGE:
3227Positive.
3228
3229@item DEFAULT VALUE:
3230The default value is 250 milliseconds.
3231
3232@end table
3233
3234@subheading DESCRIPTION:
3235Defines the swapout task swap period in milliseconds.
3236
3237@subheading NOTES:
3238None.
3239
3240@c
3241@c === CONFIGURE_SWAPOUT_BLOCK_HOLD ===
3242@c
3243@subsection Swapout Task Maximum Block Hold Time
3244
3245@findex CONFIGURE_SWAPOUT_BLOCK_HOLD
3246
3247@table @b
3248@item CONSTANT:
3249@code{CONFIGURE_SWAPOUT_BLOCK_HOLD}
3250
3251@item DATA TYPE:
3252Unsigned integer (@code{uint32_t}).
3253
3254@item RANGE:
3255Positive.
3256
3257@item DEFAULT VALUE:
3258The default value is 1000 milliseconds.
3259
3260@end table
3261
3262@subheading DESCRIPTION:
3263Defines the swapout task maximum block hold time in milliseconds.
3264
3265@subheading NOTES:
3266None.
3267
3268@c
3269@c === CONFIGURE_SWAPOUT_TASK_PRIORITY ===
3270@c
3271@subsection Swapout Task Priority
3272
3273@findex CONFIGURE_SWAPOUT_TASK_PRIORITY
3274
3275@table @b
3276@item CONSTANT:
3277@code{CONFIGURE_SWAPOUT_TASK_PRIORITY}
3278
3279@item DATA TYPE:
3280Task priority (@code{rtems_task_priority}).
3281
3282@item RANGE:
3283Valid task priority.
3284
3285@item DEFAULT VALUE:
3286The default value is 15.
3287
3288@end table
3289
3290@subheading DESCRIPTION:
3291Defines the swapout task priority.
3292
3293@subheading NOTES:
3294None.
3295
3296@c
3297@c === CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS ===
3298@c
3299@subsection Maximum Blocks per Read-Ahead Request
3300
3301@findex CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS
3302
3303@table @b
3304@item CONSTANT:
3305@code{CONFIGURE_BDBUF_MAX_READ_AHEAD_BLOCKS}
3306
3307@item DATA TYPE:
3308Unsigned integer (@code{uint32_t}).
3309
3310@item RANGE:
3311Positive.
3312
3313@item DEFAULT VALUE:
3314The default value is 0.
3315
3316@end table
3317
3318@subheading DESCRIPTION:
3319Defines the maximum blocks per read-ahead request.
3320
3321@subheading NOTES:
3322A value of 0 disables the read-ahead task (default).  The read-ahead task will
3323issue speculative read transfers if a sequential access pattern is detected.
3324This can improve the performance on some systems.
3325
3326@c
3327@c === CONFIGURE_BDBUF_MAX_WRITE_BLOCKS ===
3328@c
3329@subsection Maximum Blocks per Write Request
3330
3331@findex CONFIGURE_BDBUF_MAX_WRITE_BLOCKS
3332
3333@table @b
3334@item CONSTANT:
3335@code{CONFIGURE_BDBUF_MAX_WRITE_BLOCKS}
3336
3337@item DATA TYPE:
3338Unsigned integer (@code{uint32_t}).
3339
3340@item RANGE:
3341Positive.
3342
3343@item DEFAULT VALUE:
3344The default value is 16.
3345
3346@end table
3347
3348@subheading DESCRIPTION:
3349Defines the maximum blocks per write request.
3350
3351@subheading NOTES:
3352None.
3353
3354@c
3355@c === CONFIGURE_BDBUF_TASK_STACK_SIZE ===
3356@c
3357@subsection Task Stack Size of the Block Device Cache Tasks
3358
3359@findex CONFIGURE_BDBUF_TASK_STACK_SIZE
3360
3361@table @b
3362@item CONSTANT:
3363@code{CONFIGURE_BDBUF_TASK_STACK_SIZE}
3364
3365@item DATA TYPE:
3366Unsigned integer (@code{size_t}).
3367
3368@item RANGE:
3369Zero or positive.
3370
3371@item DEFAULT VALUE:
3372The default value is RTEMS_MINIMUM_STACK_SIZE.
3373
3374@end table
3375
3376@subheading DESCRIPTION:
3377Defines the task stack size of the Block Device Cache tasks in bytes.
3378
3379@subheading NOTES:
3380None.
3381
3382@c
3383@c === CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY ===
3384@c
3385@subsection Read-Ahead Task Priority
3386
3387@findex CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY
3388
3389@table @b
3390@item CONSTANT:
3391@code{CONFIGURE_BDBUF_READ_AHEAD_TASK_PRIORITY}
3392
3393@item DATA TYPE:
3394Task priority (@code{rtems_task_priority}).
3395
3396@item RANGE:
3397Valid task priority.
3398
3399@item DEFAULT VALUE:
3400The default value is 15.
3401
3402@end table
3403
3404@subheading DESCRIPTION:
3405Defines the read-ahead task priority.
3406
3407@subheading NOTES:
3408None.
3409
3410@c
3411@c === CONFIGURE_SWAPOUT_WORKER_TASKS ===
3412@c
3413@subsection Swapout Worker Task Count
3414
3415@findex CONFIGURE_SWAPOUT_WORKER_TASKS
3416
3417@table @b
3418@item CONSTANT:
3419@code{CONFIGURE_SWAPOUT_WORKER_TASKS}
3420
3421@item DATA TYPE:
3422Unsigned integer (@code{size_t}).
3423
3424@item RANGE:
3425Zero or positive.
3426
3427@item DEFAULT VALUE:
3428The default value is 0.
3429
3430@end table
3431
3432@subheading DESCRIPTION:
3433Defines the swapout worker task count.
3434
3435@subheading NOTES:
3436None.
3437
3438@c
3439@c === CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY ===
3440@c
3441@subsection Swapout Worker Task Priority
3442
3443@findex CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY
3444
3445@table @b
3446@item CONSTANT:
3447@code{CONFIGURE_SWAPOUT_WORKER_TASK_PRIORITY}
3448
3449@item DATA TYPE:
3450Task priority (@code{rtems_task_priority}).
3451
3452@item RANGE:
3453Valid task priority.
3454
3455@item DEFAULT VALUE:
3456The default value is 15.
3457
3458@end table
3459
3460@subheading DESCRIPTION:
3461Defines the swapout worker task priority.
3462
3463@subheading NOTES:
3464None.
3465
3466@c
3467@c === BSP Specific Settings ===
3468@c
3469@section BSP Specific Settings
3470
3471This section describes BSP specific configuration settings used by
3472@code{<rtems/confdefs.h>}.  The BSP specific configuration settings are
3473defined in @code{<bsp.h>}.
3474
3475@c
3476@c === Disable BSP Settings ===
3477@c
3478@subsection Disable BSP Configuration Settings
3479
3480@findex CONFIGURE_DISABLE_BSP_SETTINGS
3481
3482@table @b
3483@item CONSTANT:
3484@code{CONFIGURE_DISABLE_BSP_SETTINGS}
3485
3486@item DATA TYPE:
3487Boolean feature macro.
3488
3489@item RANGE:
3490Defined or undefined.
3491
3492@item DEFAULT VALUE:
3493This is not defined by default.
3494
3495@end table
3496
3497@subheading DESCRIPTION:
3498All BSP specific configuration settings can be disabled by the application
3499with the @code{CONFIGURE_DISABLE_BSP_SETTINGS} option.
3500
3501@subheading NOTES:
3502None.
3503
3504@c
3505@c === CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK ===
3506@c
3507@subsection Specify BSP Supports sbrk()
3508
3509@findex CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
3510
3511@table @b
3512@item CONSTANT:
3513@code{CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK}
3514
3515@item DATA TYPE:
3516Boolean feature macro.
3517
3518@item RANGE:
3519Defined or undefined.
3520
3521@item DEFAULT VALUE:
3522This option is BSP specific.
3523
3524@end table
3525
3526@subheading DESCRIPTION:
3527This configuration parameter is defined by a BSP to indicate that it
3528does not allocate all available memory to the C Program Heap used by
3529the Malloc Family of routines.
3530
3531If defined, when @code{malloc()} is unable to allocate memory, it will
3532call the BSP supplied @code{sbrk()} to obtain more memory.
3533
3534@subheading NOTES:
3535This parameter should not be defined by the application. Only the BSP
3536knows how it allocates memory to the C Program Heap.
3537
3538@c
3539@c === BSP_IDLE_TASK_BODY ===
3540@c
3541@subsection Specify BSP Specific Idle Task
3542
3543@findex BSP_IDLE_TASK_BODY
3544
3545@table @b
3546@item CONSTANT:
3547@code{BSP_IDLE_TASK_BODY}
3548
3549@item DATA TYPE:
3550Function pointer.
3551
3552@item RANGE:
3553Undefined or valid function pointer.
3554
3555@item DEFAULT VALUE:
3556This option is BSP specific.
3557
3558@end table
3559
3560@subheading DESCRIPTION:
3561If @code{BSP_IDLE_TASK_BODY} is defined by the BSP and
3562@code{CONFIGURE_IDLE_TASK_BODY} is not defined by the application,
3563then this BSP specific idle task body will be used.
3564
3565@subheading NOTES:
3566As it has knowledge of the specific CPU model, system controller logic,
3567and peripheral buses, a BSP specific IDLE task may be capable of turning
3568components off to save power during extended periods of no task activity
3569
3570@c
3571@c === BSP_IDLE_TASK_STACK_SIZE ===
3572@c
3573@subsection Specify BSP Suggested Value for IDLE Task Stack Size
3574
3575@findex BSP_IDLE_TASK_STACK_SIZE
3576
3577@table @b
3578@item CONSTANT:
3579@code{BSP_IDLE_TASK_STACK_SIZE}
3580
3581@item DATA TYPE:
3582Unsigned integer (@code{size_t}).
3583
3584@item RANGE:
3585Undefined or positive.
3586
3587@item DEFAULT VALUE:
3588This option is BSP specific.
3589
3590@end table
3591
3592@subheading DESCRIPTION:
3593If @code{BSP_IDLE_TASK_STACK_SIZE} is defined by the BSP and
3594@code{CONFIGURE_IDLE_TASK_STACK_SIZE} is not defined by the application,
3595then this BSP suggested idle task stack size will be used.
3596
3597
3598@subheading NOTES:
3599The order of precedence for configuring the IDLE task stack size is:
3600
3601@itemize @bullet
3602@item RTEMS default minimum stack size.
3603@item If defined, then @code{CONFIGURE_MINIMUM_TASK_STACK_SIZE}.
3604@item If defined, then the BSP specific @code{BSP_IDLE_TASK_SIZE}.
3605@item If defined, then the application specified
3606@code{CONFIGURE_IDLE_TASK_SIZE}.
3607@end itemize
3608
3609@c XXX - add cross references to other related values.
3610
3611@c
3612@c === BSP_INITIAL_EXTENSION ===
3613@c
3614@subsection Specify BSP Specific User Extensions
3615
3616@findex BSP_INITIAL_EXTENSION
3617
3618@table @b
3619@item CONSTANT:
3620@code{BSP_INITIAL_EXTENSION}
3621
3622@item DATA TYPE:
3623List of user extension initializers (@code{rtems_extensions_table}).
3624
3625@item RANGE:
3626Undefined or a list of user extension initializers.
3627
3628@item DEFAULT VALUE:
3629This option is BSP specific.
3630
3631@end table
3632
3633@subheading DESCRIPTION:
3634If @code{BSP_INITIAL_EXTENSION} is defined by the BSP, then this BSP
3635specific initial extension will be placed as the last entry in the initial
3636extension table.
3637
3638@subheading NOTES:
3639None.
3640
3641@c
3642@c === BSP_INTERRUPT_STACK_SIZE ===
3643@c
3644@subsection Specifying BSP Specific Interrupt Stack Size
3645
3646@findex BSP_INTERRUPT_STACK_SIZE
3647
3648@table @b
3649@item CONSTANT:
3650@code{BSP_INTERRUPT_STACK_SIZE}
3651
3652@item DATA TYPE:
3653Unsigned integer (@code{size_t}).
3654
3655@item RANGE:
3656Undefined or positive.
3657
3658@item DEFAULT VALUE:
3659This option is BSP specific.
3660
3661@end table
3662
3663@subheading DESCRIPTION:
3664If @code{BSP_INTERRUPT_STACK_SIZE} is defined by the BSP and
3665@code{CONFIGURE_INTERRUPT_STACK_SIZE} is not defined by the application,
3666then this BSP specific interrupt stack size will be used.
3667
3668@subheading NOTES:
3669None.
3670
3671@c
3672@c === BSP_MAXIMUM_DEVICES ===
3673@c
3674@subsection Specifying BSP Specific Maximum Devices
3675
3676@findex BSP_MAXIMUM_DEVICES
3677
3678@table @b
3679@item CONSTANT:
3680@code{BSP_MAXIMUM_DEVICES}
3681
3682@item DATA TYPE:
3683Unsigned integer (@code{size_t}).
3684
3685@item RANGE:
3686Undefined or positive.
3687
3688@item DEFAULT VALUE:
3689This option is BSP specific.
3690
3691@end table
3692
3693@subheading DESCRIPTION:
3694If @code{BSP_MAXIMUM_DEVICES} is defined by the BSP and
3695@code{CONFIGURE_MAXIMUM_DEVICES} is not defined by the application,
3696then this BSP specific maximum device count will be used.
3697
3698@subheading NOTES:
3699This option is specific to the device file system (devFS) and should not be
3700confused with the @code{CONFIGURE_MAXIMUM_DRIVERS} option.  This parameter only
3701impacts the devFS and thus is only used by @code{<rtems/confdefs.h>} when
3702@code{CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM} is specified.
3703
3704@c
3705@c === BSP_ZERO_WORKSPACE_AUTOMATICALLY ===
3706@c
3707@subsection BSP Recommends RTEMS Workspace be Cleared
3708
3709@findex BSP_ZERO_WORKSPACE_AUTOMATICALLY
3710
3711@table @b
3712@item CONSTANT:
3713@code{BSP_ZERO_WORKSPACE_AUTOMATICALLY}
3714
3715@item DATA TYPE:
3716Boolean feature macro.
3717
3718@item RANGE:
3719Defined or undefined.
3720
3721@item DEFAULT VALUE:
3722This option is BSP specific.
3723
3724@end table
3725
3726@subheading DESCRIPTION:
3727If @code{BSP_ZERO_WORKSPACE_AUTOMATICALLY} is defined by the BSP and
3728@code{CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY} is not defined by the
3729application, then the workspace will be zeroed automatically.
3730
3731@subheading NOTES:
3732Zeroing memory can add significantly to system boot time. It is not
3733necessary for RTEMS but is often assumed by support libraries.
3734
3735@c
3736@c === CONFIGURE_BSP_PREREQUISITE_DRIVERS ===
3737@c
3738@subsection Specify BSP Prerequisite Drivers
3739
3740@findex CONFIGURE_BSP_PREREQUISITE_DRIVERS
3741
3742@table @b
3743@item CONSTANT:
3744@code{CONFIGURE_BSP_PREREQUISITE_DRIVERS}
3745
3746@item DATA TYPE:
3747List of device driver initializers (@code{rtems_driver_address_table}).
3748
3749@item RANGE:
3750Undefined or array of device drivers.
3751
3752@item DEFAULT VALUE:
3753This option is BSP specific.
3754
3755@end table
3756
3757@subheading DESCRIPTION:
3758@code{CONFIGURE_BSP_PREREQUISITE_DRIVERS} is defined if the BSP has device
3759drivers it needs to include in the Device Driver Table.  This should be
3760defined to the set of device driver entries that will be placed in the
3761table at the @b{FRONT} of the Device Driver Table and initialized before
3762any other drivers @b{INCLUDING} any application prerequisite drivers.
3763
3764@subheading NOTES:
3765@code{CONFIGURE_BSP_PREREQUISITE_DRIVERS} is typically used by BSPs
3766to configure common infrastructure such as bus controllers or probe
3767for devices.
3768
3769
3770@c
3771@c === Idle Task Configuration ===
3772@c
3773@section Idle Task Configuration
3774
3775This section defines the IDLE task related configuration parameters
3776supported by @code{<rtems/confdefs.h>}.
3777
3778@c
3779@c === CONFIGURE_IDLE_TASK_BODY ===
3780@c
3781@subsection Specify Application Specific Idle Task Body
3782
3783@findex CONFIGURE_IDLE_TASK_BODY
3784
3785@table @b
3786@item CONSTANT:
3787@code{CONFIGURE_IDLE_TASK_BODY}
3788
3789@item DATA TYPE:
3790Function pointer.
3791
3792@item RANGE:
3793Undefined or valid function pointer.
3794
3795@item DEFAULT VALUE:
3796This is not defined by default.
3797
3798@end table
3799
3800@subheading DESCRIPTION:
3801@code{CONFIGURE_IDLE_TASK_BODY} is set to the function name corresponding
3802to the application specific IDLE thread body.  If not specified, the
3803BSP or RTEMS default IDLE thread body will be used.
3804
3805@subheading NOTES:
3806None.
3807
3808@c
3809@c === CONFIGURE_IDLE_TASK_STACK_SIZE ===
3810@c
3811@subsection Specify Idle Task Stack Size
3812
3813@findex CONFIGURE_IDLE_TASK_STACK_SIZE
3814
3815@table @b
3816@item CONSTANT:
3817@code{CONFIGURE_IDLE_TASK_STACK_SIZE}
3818
3819@item DATA TYPE:
3820Unsigned integer (@code{size_t}).
3821
3822@item RANGE:
3823Undefined or positive.
3824
3825@item DEFAULT VALUE:
3826The default value is RTEMS_MINIMUM_STACK_SIZE.
3827
3828@end table
3829
3830@subheading DESCRIPTION:
3831@code{CONFIGURE_IDLE_TASK_STACK_SIZE} is set to the
3832desired stack size for the IDLE task.
3833
3834@subheading NOTES:
3835None.
3836
3837@c
3838@c === CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION ===
3839@c
3840@subsection Specify Idle Task Performs Application Initialization
3841
3842@findex CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION
3843
3844@table @b
3845@item CONSTANT:
3846@code{CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION}
3847
3848@item DATA TYPE:
3849Boolean feature macro.
3850
3851@item RANGE:
3852Defined or undefined.
3853
3854@item DEFAULT VALUE:
3855This is not defined by default, the user is assumed
3856to provide one or more initialization tasks.
3857
3858@end table
3859
3860@subheading DESCRIPTION:
3861@code{CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION} is set to
3862indicate that the user has configured @b{NO} user initialization tasks
3863or threads and that the user provided IDLE task will perform application
3864initialization and then transform itself into an IDLE task.
3865
3866@subheading NOTES:
3867If you use this option be careful, the user IDLE task @b{CANNOT} block
3868at all during the initialization sequence.  Further, once application
3869initialization is complete, it must make itself preemptible and enter
3870an IDLE body loop.
3871
3872The IDLE task must run at the lowest priority of all tasks in the system.
3873
3874@c
3875@c === Scheduler Algorithm Configuration ===
3876@c
3877@section Scheduler Algorithm Configuration
3878
3879This section defines the configuration parameters related to selecting a
3880scheduling algorithm for an application.  For the schedulers built into
3881RTEMS, the configuration is straightforward.  All that is required is
3882to define the configuration macro which specifies which scheduler you
3883want for in your application.  The currently available schedulers are:
3884
3885The pluggable scheduler interface also enables the user to provide their
3886own scheduling algorithm.  If you choose to do this, you must define
3887multiple configuration macros.
3888
3889@c
3890@c === CONFIGURE_SCHEDULER_PRIORITY ===
3891@c
3892@subsection Use Deterministic Priority Scheduler
3893
3894@findex CONFIGURE_SCHEDULER_PRIORITY
3895
3896@table @b
3897@item CONSTANT:
3898@code{CONFIGURE_SCHEDULER_PRIORITY}
3899
3900@item DATA TYPE:
3901Boolean feature macro.
3902
3903@item RANGE:
3904Defined or undefined.
3905
3906@item DEFAULT VALUE:
3907This is defined by default.
3908This is the default scheduler and specifying this
3909configuration parameter is redundant.
3910
3911@end table
3912
3913@subheading DESCRIPTION:
3914The Deterministic Priority Scheduler is the default scheduler in RTEMS
3915for uni-processor applications and is designed for predictable performance
3916under the highest loads.  It can block or unblock a thread in a constant
3917amount of time.  This scheduler requires a variable amount of memory
3918based upon the number of priorities configured in the system.
3919
3920@subheading NOTES:
3921This scheduler may be explicitly selected by defining
3922@code{CONFIGURE_SCHEDULER_PRIORITY} although this is equivalent to the
3923default behavior.
3924
3925@c
3926@c === CONFIGURE_SCHEDULER_SIMPLE ===
3927@c
3928@subsection Use Simple Priority Scheduler
3929
3930@findex CONFIGURE_SCHEDULER_SIMPLE
3931
3932@table @b
3933@item CONSTANT:
3934@code{CONFIGURE_SCHEDULER_SIMPLE}
3935
3936@item DATA TYPE:
3937Boolean feature macro.
3938
3939@item RANGE:
3940Defined or undefined.
3941
3942@item DEFAULT VALUE:
3943This is not defined by default.
3944
3945@end table
3946
3947@subheading DESCRIPTION:
3948When defined, the Simple Priority Scheduler is used at the thread
3949scheduling algorithm. This is an alternative scheduler in RTEMS.
3950It is designed to provide the same task scheduling behaviour as the
3951Deterministic Priority Scheduler while being simpler in implementation
3952and uses less memory for data management.  It maintains a single sorted
3953list of all ready threads.  Thus blocking or unblocking a thread is not
3954a constant time operation with this scheduler.
3955
3956This scheduler may be explicitly selected by defining
3957@code{CONFIGURE_SCHEDULER_SIMPLE}.
3958
3959@subheading NOTES:
3960This scheduler is appropriate for use in small systems where RAM is limited.
3961
3962@c
3963@c === CONFIGURE_SCHEDULER_EDF ===
3964@c
3965@subsection Use Earliest Deadline First Scheduler
3966
3967@findex CONFIGURE_SCHEDULER_EDF
3968
3969@table @b
3970@item CONSTANT:
3971@code{CONFIGURE_SCHEDULER_EDF}
3972
3973@item DATA TYPE:
3974Boolean feature macro.
3975
3976@item RANGE:
3977Defined or undefined.
3978
3979@item DEFAULT VALUE:
3980This is not defined by default.
3981
3982@end table
3983
3984@subheading DESCRIPTION:
3985The Earliest Deadline First Scheduler (EDF) is an alternative scheduler in
3986RTEMS for uni-processor applications. The EDF schedules tasks with dynamic
3987priorities equal to deadlines. The deadlines are declared using only
3988Rate Monotonic manager which handles periodic behavior.  Period is always
3989equal to deadline. If a task does not have any deadline declared or the
3990deadline is cancelled, the task is considered a background task which is
3991scheduled in case no deadline-driven tasks are ready to run.  Moreover,
3992multiple background tasks are scheduled according their priority assigned
3993upon initialization. All ready tasks reside in a single ready queue.
3994
3995This scheduler may be explicitly selected by defining
3996@code{CONFIGURE_SCHEDULER_EDF}.
3997
3998@subheading NOTES:
3999None.
4000
4001
4002@c
4003@c === CONFIGURE_SCHEDULER_CBS ===
4004@c
4005@subsection Use Constant Bandwidth Server Scheduler
4006
4007@findex CONFIGURE_SCHEDULER_CBS
4008
4009@table @b
4010@item CONSTANT:
4011@code{CONFIGURE_SCHEDULER_CBS}
4012
4013@item DATA TYPE:
4014Boolean feature macro.
4015
4016@item RANGE:
4017Defined or undefined.
4018
4019@item DEFAULT VALUE:
4020This is not defined by default.
4021
4022@end table
4023
4024@subheading DESCRIPTION:
4025The Constant Bandwidth Server Scheduler (CBS) is an alternative scheduler
4026in RTEMS for uni-processor applications. The CBS is a budget aware extension
4027of EDF scheduler. The goal of this scheduler is to ensure temporal
4028isolation of tasks. The CBS is equipped with a set of additional rules
4029and provides with an extensive API.
4030
4031This scheduler may be explicitly selected by defining
4032@code{CONFIGURE_SCHEDULER_CBS}.
4033@c XXX - add cross reference to API chapter
4034
4035@subheading NOTES:
4036None.
4037
4038@c
4039@c === CONFIGURE_SCHEDULER_PRIORITY_SMP ===
4040@c
4041@subsection Use Deterministic Priority SMP Scheduler
4042
4043@findex CONFIGURE_SCHEDULER_PRIORITY_SMP
4044
4045@table @b
4046@item CONSTANT:
4047@code{CONFIGURE_SCHEDULER_PRIORITY_SMP}
4048
4049@item DATA TYPE:
4050Boolean feature macro.
4051
4052@item RANGE:
4053Defined or undefined.
4054
4055@item DEFAULT VALUE:
4056This is not defined by default.
4057
4058@end table
4059
4060@subheading DESCRIPTION:
4061The Deterministic Priority SMP Scheduler is derived from the Deterministic
4062Priority Scheduler but is capable of scheduling threads across multiple
4063processors.
4064
4065In a configuration with SMP enabled at configure time, it may be
4066explicitly selected by defining @code{CONFIGURE_SCHEDULER_PRIORITY_SMP}.
4067
4068@subheading NOTES:
4069This scheduler is only available when RTEMS is configured with SMP
4070support enabled.
4071
4072This scheduler is currently the default in SMP configurations and is
4073only selected when @code{CONFIGURE_SMP_APPLICATION} is defined.
4074
4075@c
4076@c === CONFIGURE_SCHEDULER_SIMPLE_SMP ===
4077@c
4078@subsection Use Simple SMP Priority Scheduler
4079
4080@findex CONFIGURE_SCHEDULER_SIMPLE_SMP
4081
4082@table @b
4083@item CONSTANT:
4084@code{CONFIGURE_SCHEDULER_SIMPLE_SMP}
4085
4086@item DATA TYPE:
4087Boolean feature macro.
4088
4089@item RANGE:
4090Defined or undefined.
4091
4092@item DEFAULT VALUE:
4093This is not defined by default.
4094
4095@end table
4096
4097@subheading DESCRIPTION:
4098The Simple SMP Priority Scheduler is derived from the Simple Priority
4099Scheduler but is capable of scheduling threads across multiple processors.
4100It is designed to provide the same task scheduling behaviour as the
4101Deterministic Priority Scheduler while distributing threads across
4102multiple processors.  Being based upon the Simple Priority Scheduler, it also
4103maintains a single sorted list of all ready threads.  Thus blocking or
4104unblocking a thread is not a constant time operation with this scheduler.
4105
4106In addition, when allocating threads to processors, the algorithm is not
4107constant time. This algorithm was not designed with efficiency as a
4108primary design goal.  Its primary design goal was to provide an SMP-aware
4109scheduling algorithm that is simple to understand.
4110
4111In a configuration with SMP enabled at configure time, it may be
4112explicitly selected by defining @code{CONFIGURE_SCHEDULER_SIMPLE_SMP}.
4113
4114@subheading NOTES:
4115This scheduler is only available when RTEMS is configured with SMP
4116support enabled.
4117
4118@c
4119@c === Configuring a Scheduler Name ===
4120@c
4121@subsection Configuring a Scheduler Name
4122
4123@findex CONFIGURE_SCHEDULER_NAME
4124
4125@table @b
4126@item CONSTANT:
4127@code{CONFIGURE_SCHEDULER_NAME}
4128
4129@item DATA TYPE:
4130RTEMS Name (@code{rtems_name}).
4131
4132@item RANGE:
4133Any value.
4134
4135@item DEFAULT VALUE:
4136The default name is
4137@itemize @bullet
4138@item @code{"UCBS"} for the Uni-Processor CBS scheduler,
4139@item @code{"UEDF"} for the Uni-Processor EDF scheduler,
4140@item @code{"UPD "} for the Uni-Processor Deterministic Priority scheduler,
4141@item @code{"UPS "} for the Uni-Processor Simple Priority scheduler,
4142@item @code{"MPA "} for the Multi-Processor Priority Affinity scheduler, and
4143@item @code{"MPD "} for the Multi-Processor Deterministic Priority scheduler, and
4144@item @code{"MPS "} for the Multi-Processor Simple Priority scheduler.
4145@end itemize
4146
4147@end table
4148
4149@subheading DESCRIPTION:
4150Schedulers can be identified via @code{rtems_scheduler_ident}.  The name of the scheduler is determined by the configuration.
4151
4152@subheading NOTES:
4153None.
4154
4155@c
4156@c === Configuring a User Scheduler ===
4157@c
4158@subsection Configuring a User Provided Scheduler
4159
4160@findex CONFIGURE_SCHEDULER_USER
4161
4162@table @b
4163@item CONSTANT:
4164@code{CONFIGURE_SCHEDULER_USER}
4165
4166@item DATA TYPE:
4167Boolean feature macro.
4168
4169@item RANGE:
4170Defined or undefined.
4171
4172@item DEFAULT VALUE:
4173This is not defined by default.
4174
4175@end table
4176
4177@subheading DESCRIPTION:
4178RTEMS allows the application to provide its own task/thread
4179scheduling algorithm. In order to do this, one must define
4180@code{CONFIGURE_SCHEDULER_USER} to indicate the application provides its
4181own scheduling algorithm. If @code{CONFIGURE_SCHEDULER_USER} is defined
4182then the following additional macros must be defined:
4183
4184@itemize @bullet
4185@item @code{CONFIGURE_SCHEDULER_CONTEXT} must be defined to a static definition
4186of the scheduler context of the user scheduler.
4187
4188@item @code{CONFIGURE_SCHEDULER_CONTROLS} must be defined to a scheduler
4189control initializer for the user scheduler.
4190
4191@item @code{CONFIGURE_SCHEDULER_USER_PER_THREAD} must be defined to the type of
4192the per-thread information of the user scheduler.
4193
4194@end itemize
4195
4196@subheading NOTES:
4197At this time, the mechanics and requirements for writing a
4198new scheduler are evolving and not fully documented.  It is
4199recommended that you look at the existing Deterministic Priority
4200Scheduler in @code{cpukit/score/src/schedulerpriority*.c} for
4201guidance.  For guidance on the configuration macros, please examine
4202@code{cpukit/sapi/include/confdefs.h} for how these are defined for the
4203Deterministic Priority Scheduler.
4204
4205@c
4206@c === Configuring Clustered/Partitioned Schedulers ===
4207@c
4208@subsection Configuring Clustered/Partitioned Schedulers
4209
4210Clustered/partitioned scheduling helps to control the worst-case latencies in
4211the system.  The goal is to reduce the amount of shared state in the system and
4212thus prevention of lock contention.  Modern multi-processor systems tend to
4213have several layers of data and instruction caches.  With clustered/partitioned
4214scheduling it is possible to honour the cache topology of a system and thus
4215avoid expensive cache synchronization traffic.
4216
4217We have clustered scheduling in case the set of processors of a system is
4218partitioned into non-empty pairwise-disjoint subsets.  These subsets are called
4219clusters.  Clusters with a cardinality of one are partitions.  Each cluster is
4220owned by exactly one scheduler instance.  In order to use clustered/partitioned
4221scheduling the application designer has to answer two questions.
4222
4223@enumerate
4224@item How is the set of processors partitioned into clusters/partitions?
4225@item Which scheduler is used for which cluster/partition?
4226@end enumerate
4227
4228@subheading CONFIGURATION:
4229
4230The schedulers in an SMP system are statically configured on RTEMS.  Firstly
4231the application must select which scheduling algorithms are available with the
4232following defines
4233
4234@itemize @bullet
4235@item @code{CONFIGURE_SCHEDULER_PRIORITY_SMP},
4236@item @code{CONFIGURE_SCHEDULER_SIMPLE_SMP}, and
4237@item @code{CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP}.
4238@end itemize
4239
4240This is necessary to calculate the per-thread overhead introduced by the
4241schedulers.  After these definitions the configuration file must @code{#include
4242<rtems/scheduler.h>} to have access to scheduler specific configuration macros.
4243Each scheduler needs a context to store state information at run-time.  To
4244provide a context for each scheduler is the next step.  Use the following
4245macros to create scheduler contexts
4246
4247@itemize @bullet
4248@item @code{RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(name, prio_count)},
4249@item @code{RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(name)}, and
4250@item @code{RTEMS_SCHEDULER_CONTEXT_PRIORITY_AFFINITY_SMP(name, prio_count)}.
4251@end itemize
4252
4253The @code{name} parameter is used as part of a designator for a global
4254variable, so the usual C/C++ designator rules apply.  Additional parameters are
4255scheduler specific.  The schedulers are registered in the system via the
4256scheduler table.  To create the scheduler table define
4257@code{CONFIGURE_SCHEDULER_CONTROLS} to a list of the following scheduler
4258control initializers
4259
4260@itemize @bullet
4261@item @code{RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP(name, obj_name)},
4262@item @code{RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(name, obj_name)}, and
4263@item @code{RTEMS_SCHEDULER_CONTROL_PRIORITY_AFFINITY_SMP(name, obj_name)}.
4264@end itemize
4265
4266The @code{name} parameter must correspond to the parameter defining the
4267scheduler context.  The @code{obj_name} determines the scheduler object name
4268and can be used in @code{rtems_scheduler_ident()} to get the scheduler object
4269identifier.
4270
4271The last step is to define which processor uses which scheduler.
4272For this purpose a scheduler assignment table must be defined.  The entry count
4273of this table must be equal to the configured maximum processors
4274(@code{CONFIGURE_SMP_MAXIMUM_PROCESSORS}).  A processor assignment to a
4275scheduler can be optional or mandatory.  The boot processor must have a
4276scheduler assigned.  In case the system needs more mandatory processors than
4277available then a fatal run-time error will occur.  To specify the scheduler
4278assignments define @code{CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS} to a list of
4279@code{RTEMS_SCHEDULER_ASSIGN(index, attr)} and
4280@code{RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER} macros.  The @code{index} parameter
4281must be a valid index into the scheduler table.  The @code{attr} parameter
4282defines the scheduler assignment attributes.  By default a scheduler assignment
4283to a processor is optional.  For the scheduler assignment attribute use one of
4284the mutually exclusive variants
4285
4286@itemize @bullet
4287@item @code{RTEMS_SCHEDULER_ASSIGN_DEFAULT},
4288@item @code{RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY}, and
4289@item @code{RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL}.
4290@end itemize
4291
4292@subheading ERRORS:
4293
4294In case one of the scheduler indices in
4295@code{CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS} is invalid a link-time error will
4296occur with an undefined reference to @code{RTEMS_SCHEDULER_INVALID_INDEX}.
4297
4298Some fatal errors may occur in case of scheduler configuration inconsistencies or a lack
4299of processors on the system.  The fatal source is
4300@code{RTEMS_FATAL_SOURCE_SMP}.  None of the errors is internal.
4301
4302@itemize @bullet
4303@item @code{SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER} - the boot
4304processor must have a scheduler assigned.
4305@item @code{SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT} - there exists a
4306mandatory processor beyond the range of physically or virtually available
4307processors.  The processor demand must be reduced for this system.
4308@item @code{SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED} - the start of a
4309mandatory processor failed during system initialization.  The system may not
4310have this processor at all or it could be a problem with a boot loader for
4311example.  Check the @code{CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS} definition.
4312@item @code{SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR} - it is not
4313allowed to start multitasking on a processor with no scheduler assigned.
4314@end itemize
4315
4316@subheading EXAMPLE:
4317
4318The following example shows a scheduler configuration for a hypothetical
4319product using two chip variants.  One variant has four processors which is used
4320for the normal product line and another provides eight processors for the
4321high-performance product line.  The first processor performs hard-real time
4322control of actuators and sensors.  The second processor is not used by RTEMS at
4323all and runs a Linux instance to provide a graphical user interface.  The
4324additional processors are used for a worker thread pool to perform data
4325processing operations.
4326
4327The processors managed by RTEMS use two Deterministic Priority scheduler
4328instances capable of dealing with 256 priority levels.  The scheduler with
4329index zero has the name @code{"IO  "}.  The scheduler with index one has the
4330name @code{"WORK"}.  The scheduler assignments of the first, third and fourth
4331processor are mandatory, so the system must have at least four processors,
4332otherwise a fatal run-time error will occur during system startup.  The
4333processor assignments for the fifth up to the eighth processor are optional so
4334that the same application can be used for the normal and high-performance
4335product lines.  The second processor has no scheduler assigned and runs Linux.
4336A hypervisor will ensure that the two systems cannot interfere in an
4337undesirable way.
4338
4339@example
4340@group
4341#define CONFIGURE_SMP_MAXIMUM_PROCESSORS 8
4342
4343#define CONFIGURE_MAXIMUM_PRIORITY 255
4344
4345/* Make the scheduler algorithm available */
4346
4347#define CONFIGURE_SCHEDULER_PRIORITY_SMP
4348
4349#include <rtems/scheduler.h>
4350
4351/* Create contexts for the two scheduler instances */
4352
4353RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1);
4354
4355RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1);
4356
4357/* Define the scheduler table */
4358
4359#define CONFIGURE_SCHEDULER_CONTROLS \
4360  RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \
4361    io, \
4362    rtems_build_name('I', 'O', ' ', ' ') \
4363  ), \
4364  RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \
4365    work, \
4366    rtems_build_name('W', 'O', 'R', 'K') \
4367  )
4368
4369/* Define the processor to scheduler assignments */
4370
4371#define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \
4372  RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
4373  RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \
4374  RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
4375  RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
4376  RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
4377  RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
4378  RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
4379  RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL)
4380@end group
4381@end example
4382
4383@c
4384@c === SMP Specific Configuration Parameters ===
4385@c
4386@section SMP Specific Configuration Parameters
4387
4388When RTEMS is configured to support SMP target systems, there are other
4389configuration parameters which apply.
4390
4391@c XXX - add --enable-smp
4392
4393@c
4394@c === CONFIGURE_SMP_APPLICATION ===
4395@c
4396@subsection Enable SMP Support for Applications
4397
4398@findex CONFIGURE_SMP_APPLICATION
4399
4400@table @b
4401@item CONSTANT:
4402@code{CONFIGURE_SMP_APPLICATION}
4403
4404@item DATA TYPE:
4405Boolean feature macro.
4406
4407@item RANGE:
4408Defined or undefined.
4409
4410@item DEFAULT VALUE:
4411This is not defined by default.
4412
4413@end table
4414
4415@subheading DESCRIPTION:
4416@code{CONFIGURE_SMP_APPLICATION} must be defined to enable SMP support for the
4417application.
4418
4419@subheading NOTES:
4420This define may go away in the future in case all RTEMS components are SMP ready.
4421
4422@c
4423@c === CONFIGURE_SMP_MAXIMUM_PROCESSORS ===
4424@c
4425@subsection Specify Maximum Processors in SMP System
4426
4427@findex CONFIGURE_SMP_MAXIMUM_PROCESSORS
4428
4429@table @b
4430@item CONSTANT:
4431@code{CONFIGURE_SMP_MAXIMUM_PROCESSORS}
4432
4433@item DATA TYPE:
4434Unsigned integer (@code{uint32_t}).
4435
4436@item RANGE:
4437Defined or undefined.
4438
4439@item DEFAULT VALUE:
4440The default value is 1, (if CONFIGURE_SMP_APPLICATION is defined).
4441
4442@end table
4443
4444@subheading DESCRIPTION:
4445@code{CONFIGURE_SMP_MAXIMUM_PROCESSORS} must be set to the number of
4446processors in the SMP configuration.
4447
4448@subheading NOTES:
4449If there are more processors available than configured, the rest will be
4450ignored.
4451
4452@c
4453@c === Device Driver Table ===
4454@c
4455@section Device Driver Table
4456
4457This section defines the configuration parameters related
4458to the automatic generation of a Device Driver Table.  As
4459@code{<rtems/confdefs.h>} only is aware of a small set of
4460standard device drivers, the generated Device Driver
4461Table is suitable for simple applications with no
4462custom device drivers.
4463
4464Note that network device drivers are not configured in the Device Driver Table.
4465
4466@c
4467@c === CONFIGURE_MAXIMUM_DRIVERS ===
4468@c
4469@subsection Specifying the Maximum Number of Device Drivers
4470
4471@findex CONFIGURE_MAXIMUM_DRIVERS
4472
4473@table @b
4474@item CONSTANT:
4475@code{CONFIGURE_MAXIMUM_DRIVERS}
4476
4477@item DATA TYPE:
4478Unsigned integer (@code{uint32_t}).
4479
4480@item RANGE:
4481Zero or positive.
4482
4483@item DEFAULT VALUE:
4484This is computed by default, and is set to the number of device drivers
4485configured using the @code{CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER}
4486configuration parameters.
4487
4488@end table
4489
4490@subheading DESCRIPTION:
4491@code{CONFIGURE_MAXIMUM_DRIVERS} is defined as the number of device
4492drivers per node.
4493
4494@subheading NOTES:
4495If the application will dynamically install device drivers, then this
4496configuration parameter must be larger than the number of statically
4497configured device drivers. Drivers configured using the
4498@code{CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER} configuration parameters
4499are statically installed.
4500
4501@c
4502@c === CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER ===
4503@c
4504@subsection Enable Console Device Driver
4505
4506@findex CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
4507
4508@table @b
4509@item CONSTANT:
4510@code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER}
4511
4512@item DATA TYPE:
4513Boolean feature macro.
4514
4515@item RANGE:
4516Defined or undefined.
4517
4518@item DEFAULT VALUE:
4519This is not defined by default.
4520
4521@end table
4522
4523@subheading DESCRIPTION:
4524@code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER} is defined if the
4525application wishes to include the Console Device Driver.
4526
4527@subheading NOTES:
4528This device driver is responsible for providing standard input and output
4529using @i{/dev/console}.
4530
4531BSPs should be constructed in a manner that allows @code{printk()}
4532to work properly without the need for the console driver to be configured.
4533
4534@c
4535@c === CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER ===
4536@c
4537@subsection Enable Clock Driver
4538
4539@findex CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
4540
4541@table @b
4542@item CONSTANT:
4543@code{CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER}
4544
4545@item DATA TYPE:
4546Boolean feature macro.
4547
4548@item RANGE:
4549Defined or undefined.
4550
4551@item DEFAULT VALUE:
4552This is not defined by default.
4553
4554@end table
4555
4556@subheading DESCRIPTION:
4557@code{CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER} is defined if the
4558application wishes to include the Clock Device Driver.
4559
4560@subheading NOTES:
4561This device driver is responsible for providing a regular
4562interrupt which invokes the @code{rtems_clock_tick} directive.
4563
4564If neither the Clock Driver not Benchmark Timer is enabled and
4565the configuration parameter
4566@code{CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER} is not defined,
4567then a compile time error will occur.
4568
4569@c
4570@c === CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER ===
4571@c
4572@subsection Enable the Benchmark Timer Driver
4573
4574@findex CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
4575
4576@table @b
4577@item CONSTANT:
4578@code{CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER}
4579
4580@item DATA TYPE:
4581Boolean feature macro.
4582
4583@item RANGE:
4584Defined or undefined.
4585
4586@item DEFAULT VALUE:
4587This is not defined by default.
4588
4589@end table
4590
4591@subheading DESCRIPTION:
4592@code{CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER} is defined if the
4593application wishes to include the Timer Driver.  This device driver is
4594used to benchmark execution times by the RTEMS Timing Test Suites.
4595
4596@subheading NOTES:
4597If neither the Clock Driver not Benchmark Timer is enabled and
4598the configuration parameter
4599@code{CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER} is not defined,
4600then a compile time error will occur.
4601
4602@c
4603@c === CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER ===
4604@c
4605@subsection Specify Clock and Benchmark Timer Drivers Are Not Needed
4606
4607@findex CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
4608
4609@table @b
4610@item CONSTANT:
4611@code{CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER}
4612
4613@item DATA TYPE:
4614Boolean feature macro.
4615
4616@item RANGE:
4617Defined or undefined.
4618
4619@item DEFAULT VALUE:
4620This is not defined by default.
4621
4622@end table
4623
4624@subheading DESCRIPTION:
4625@code{CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER} is defined when
4626the application does @b{NOT} want the Clock Device Driver and is @b{NOT}
4627using the Timer Driver.  The inclusion or exclusion of the Clock Driver
4628must be explicit in user applications.
4629
4630@subheading NOTES:
4631This configuration parameter is intended to prevent the common user error
4632of using the Hello World example as the baseline for an application and
4633leaving out a clock tick source.
4634
4635@c
4636@c === CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER ===
4637@c
4638@subsection Enable Real-Time Clock Driver
4639
4640@findex CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER
4641
4642@table @b
4643@item CONSTANT:
4644@code{CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER}
4645
4646@item DATA TYPE:
4647Boolean feature macro.
4648
4649@item RANGE:
4650Defined or undefined.
4651
4652@item DEFAULT VALUE:
4653This is not defined by default.
4654
4655@end table
4656
4657@subheading DESCRIPTION:
4658@code{CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER} is defined if the
4659application wishes to include the Real-Time Clock Driver.
4660
4661@subheading NOTES:
4662Most BSPs do not include support for a real-time clock. This is because
4663many boards do not include the required hardware.
4664
4665If this is defined and the BSP does not have this device driver, then
4666the user will get a link time error for an undefined symbol.
4667
4668@c
4669@c === CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER ===
4670@c
4671@subsection Enable the Watchdog Device Driver
4672
4673@findex CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER
4674
4675@table @b
4676@item CONSTANT:
4677@code{CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER}
4678
4679@item DATA TYPE:
4680Boolean feature macro.
4681
4682@item RANGE:
4683Defined or undefined.
4684
4685@item DEFAULT VALUE:
4686This is not defined by default.
4687
4688@end table
4689
4690@subheading DESCRIPTION:
4691@code{CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER}
4692is defined if the application wishes to include the Watchdog Driver.
4693
4694@subheading NOTES:
4695Most BSPs do not include support for a watchdog device driver. This is
4696because many boards do not include the required hardware.
4697
4698If this is defined and the BSP does not have this device driver, then
4699the user will get a link time error for an undefined symbol.
4700
4701@c
4702@c === CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER ===
4703@c
4704@subsection Enable the Graphics Frame Buffer Device Driver
4705
4706@findex CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER
4707
4708@table @b
4709@item CONSTANT:
4710@code{CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER}
4711
4712@item DATA TYPE:
4713Boolean feature macro.
4714
4715@item RANGE:
4716Defined or undefined.
4717
4718@item DEFAULT VALUE:
4719This is not defined by default.
4720
4721@end table
4722
4723@subheading DESCRIPTION:
4724@code{CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER} is defined
4725if the application wishes to include the BSP's Frame Buffer Device Driver.
4726
4727@subheading NOTES:
4728Most BSPs do not include support for a Frame Buffer Device Driver. This is
4729because many boards do not include the required hardware.
4730
4731If this is defined and the BSP does not have this device driver, then
4732the user will get a link time error for an undefined symbol.
4733
4734@c
4735@c === CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER ===
4736@c
4737@subsection Enable Stub Device Driver
4738
4739@findex CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER
4740
4741@table @b
4742@item CONSTANT:
4743@code{CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER}
4744
4745@item DATA TYPE:
4746Boolean feature macro.
4747
4748@item RANGE:
4749Defined or undefined.
4750
4751@item DEFAULT VALUE:
4752This is not defined by default.
4753
4754@end table
4755
4756@subheading DESCRIPTION:
4757@code{CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER} is defined if the
4758application wishes to include the Stub Device Driver.
4759
4760@subheading NOTES:
4761This device driver simply provides entry points that return successful
4762and is primarily a test fixture. It is supported by all BSPs.
4763
4764@c
4765@c === CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS ===
4766@c
4767@subsection Specify Application Prerequisite Device Drivers
4768
4769@findex CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS
4770
4771@table @b
4772@item CONSTANT:
4773@code{CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS}
4774
4775@item DATA TYPE:
4776device driver entry structures
4777
4778@item RANGE:
4779Undefined or set of device driver entry structures
4780
4781@item DEFAULT VALUE:
4782This is not defined by default.
4783
4784@end table
4785
4786@subheading DESCRIPTION:
4787@code{CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS} is defined if the
4788application has device drivers it needs to include in the Device Driver
4789Table.  This should be defined to the set of device driver entries that
4790will be placed in the table at the @b{FRONT} of the Device Driver Table
4791and initialized before any other drivers @b{EXCEPT} any BSP prerequisite
4792drivers.
4793
4794@subheading NOTES:
4795In some cases, it is used by System On Chip BSPs to support peripheral
4796buses beyond those normally found on the System On Chip. For example,
4797this is used by one RTEMS system which has implemented a SPARC/ERC32
4798based board with VMEBus. The VMEBus Controller initialization is performed
4799by a device driver configured via this configuration parameter.
4800
4801@c XXX Add example
4802
4803@c
4804@c === CONFIGURE_APPLICATION_EXTRA_DRIVERS ===
4805@c
4806@subsection Specify Extra Application Device Drivers
4807
4808@findex CONFIGURE_APPLICATION_EXTRA_DRIVERS
4809
4810@table @b
4811@item CONSTANT:
4812@code{CONFIGURE_APPLICATION_EXTRA_DRIVERS}
4813
4814@item DATA TYPE:
4815device driver entry structures
4816
4817@item RANGE:
4818Undefined or set of device driver entry structures
4819
4820@item DEFAULT VALUE:
4821This is not defined by default.
4822
4823@end table
4824
4825@subheading DESCRIPTION:
4826@code{CONFIGURE_APPLICATION_EXTRA_DRIVERS} is defined if the
4827application has device drivers it needs to include in the Device Driver
4828Table.  This should be defined to the set of device driver entries that
4829will be placed in the table at the @b{END} of the Device Driver Table.
4830
4831@subheading NOTES:
4832None.
4833
4834@c
4835@c === CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER ===
4836@c
4837@subsection Enable /dev/null Device Driver
4838
4839@findex CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER
4840@cindex /dev/null
4841
4842@table @b
4843@item CONSTANT:
4844@code{CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER}
4845
4846@item DATA TYPE:
4847Boolean feature macro.
4848
4849@item RANGE:
4850Defined or undefined.
4851
4852@item DEFAULT VALUE:
4853This is not defined by default.
4854
4855@end table
4856
4857@subheading DESCRIPTION:
4858This configuration variable is specified to enable @i{/dev/null}
4859device driver.
4860
4861@subheading NOTES:
4862This device driver is supported by all BSPs.
4863
4864@c
4865@c === CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER ===
4866@c
4867@subsection Enable /dev/zero Device Driver
4868
4869@findex CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER
4870@cindex /dev/zero
4871
4872@table @b
4873@item CONSTANT:
4874@code{CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER}
4875
4876@item DATA TYPE:
4877Boolean feature macro.
4878
4879@item RANGE:
4880Defined or undefined.
4881
4882@item DEFAULT VALUE:
4883This is not defined by default.
4884
4885@end table
4886
4887@subheading DESCRIPTION:
4888This configuration variable is specified to enable @i{/dev/zero}
4889device driver.
4890
4891@subheading NOTES:
4892This device driver is supported by all BSPs.
4893
4894@c
4895@c === CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE ===
4896@c
4897@subsection Specifying Application Defined Device Driver Table
4898
4899@findex CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE
4900
4901@table @b
4902@item CONSTANT:
4903@code{CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE}
4904
4905@item DATA TYPE:
4906Boolean feature macro.
4907
4908@item RANGE:
4909Defined or undefined.
4910
4911@item DEFAULT VALUE:
4912This is not defined by default, indicating the @code{<rtems/confdefs.h>}
4913is providing the device driver table.
4914
4915@end table
4916
4917@subheading DESCRIPTION:
4918@code{CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE} is defined if the application
4919wishes to provide their own Device Driver Table.
4920
4921The table must be an array of @code{rtems_driver_address_table} entries named
4922@code{_IO_Driver_address_table}.  The application must also provide a const
4923variable @code{_IO_Number_of_drivers} of type @code{size_t} indicating the
4924number of entries in the @code{_IO_Driver_address_table}.
4925
4926@subheading NOTES:
4927It is expected that there the application would only rarely need to do this.
4928
4929@c
4930@c === Multiprocessing Configuration ===
4931@c
4932@section Multiprocessing Configuration
4933
4934This section defines the multiprocessing related system configuration
4935parameters supported by @code{<rtems/confdefs.h>}.  They are only used
4936if the Multiprocessing Support (distinct from the SMP support) is enabled
4937at configure time using the @code{--enable-multiprocessing} option.
4938
4939Additionally, this class of Configuration Constants are only applicable if
4940@code{CONFIGURE_MP_APPLICATION} is defined.
4941
4942@c
4943@c === CONFIGURE_MP_APPLICATION ===
4944@c
4945@subsection Specify Application Will Use Multiprocessing
4946
4947@findex CONFIGURE_MP_APPLICATION
4948
4949@table @b
4950@item CONSTANT:
4951@code{CONFIGURE_MP_APPLICATION}
4952
4953@item DATA TYPE:
4954Boolean feature macro.
4955
4956@item RANGE:
4957Defined or undefined.
4958
4959@item DEFAULT VALUE:
4960This is not defined by default.
4961
4962@end table
4963
4964@subheading DESCRIPTION:
4965This configuration parameter must be defined to indicate
4966that the application intends to be part of a multiprocessing
4967configuration. Additional configuration parameters are assumed to be
4968provided.
4969
4970@subheading NOTES:
4971This has no impact unless RTEMS was configured and built using the
4972@code{--enable-multiprocessing} option.
4973
4974@c
4975@c === CONFIGURE_MP_NODE_NUMBER ===
4976@c
4977@subsection Configure Node Number in Multiprocessor Configuration
4978
4979@findex CONFIGURE_MP_NODE_NUMBER
4980
4981@table @b
4982@item CONSTANT:
4983@code{CONFIGURE_MP_NODE_NUMBER}
4984
4985@item DATA TYPE:
4986Unsigned integer (@code{uint32_t}).
4987
4988@item RANGE:
4989Positive.
4990
4991@item DEFAULT VALUE:
4992The default value is @code{NODE_NUMBER}, which is assumed to be
4993set by the compilation environment.
4994
4995@end table
4996
4997@subheading DESCRIPTION:
4998@code{CONFIGURE_MP_NODE_NUMBER} is the node number of
4999this node in a multiprocessor system.
5000
5001@subheading NOTES:
5002In the RTEMS Multiprocessing Test Suite, the node number is derived from
5003the Makefile variable @code{NODE_NUMBER}. The same code is compiled with
5004the @code{NODE_NUMBER} set to different values. The test programs behave
5005differently based upon their node number.
5006
5007
5008@c
5009@c === CONFIGURE_MP_MAXIMUM_NODES ===
5010@c
5011@subsection Configure Maximum Node in Multiprocessor Configuration
5012
5013@findex CONFIGURE_MP_MAXIMUM_NODES
5014
5015@table @b
5016@item CONSTANT:
5017@code{CONFIGURE_MP_MAXIMUM_NODES}
5018
5019@item DATA TYPE:
5020Unsigned integer (@code{uint32_t}).
5021
5022@item RANGE:
5023Positive.
5024
5025@item DEFAULT VALUE:
5026The default value is 2.
5027
5028@end table
5029
5030@subheading DESCRIPTION:
5031@code{CONFIGURE_MP_MAXIMUM_NODES} is the maximum number of nodes in a
5032multiprocessor system.
5033
5034@subheading NOTES:
5035None.
5036
5037@c
5038@c === CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS ===
5039@c
5040@subsection Configure Maximum Global Objects in Multiprocessor Configuration
5041
5042@findex CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS
5043
5044@table @b
5045@item CONSTANT:
5046@code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS}
5047
5048@item DATA TYPE:
5049Unsigned integer (@code{uint32_t}).
5050
5051@item RANGE:
5052Positive.
5053
5054@item DEFAULT VALUE:
5055The default value is 32.
5056
5057@end table
5058
5059@subheading DESCRIPTION:
5060@code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS} is the maximum number of
5061concurrently active global objects in a multiprocessor system.
5062
5063@subheading NOTES:
5064This value corresponds to the total number of objects which can be
5065created with the @code{RTEMS_GLOBAL} attribute.
5066
5067@c
5068@c === CONFIGURE_MP_MAXIMUM_PROXIES ===
5069@c
5070@subsection Configure Maximum Proxies in Multiprocessor Configuration
5071
5072@findex CONFIGURE_MP_MAXIMUM_PROXIES
5073
5074@table @b
5075@item CONSTANT:
5076@code{CONFIGURE_MP_MAXIMUM_PROXIES}
5077
5078@item DATA TYPE:
5079Unsigned integer (@code{uint32_t}).
5080
5081@item RANGE:
5082Undefined or positive.
5083
5084@item DEFAULT VALUE:
5085The default value is 32.
5086
5087@end table
5088
5089@subheading DESCRIPTION:
5090@code{CONFIGURE_MP_MAXIMUM_PROXIES} is the maximum number of concurrently
5091active thread/task proxies on this node in a multiprocessor system.
5092
5093@subheading NOTES:
5094Since a proxy is used to represent a remote task/thread which is blocking on
5095this node. This configuration parameter reflects the maximum number of
5096remote tasks/threads which can be blocked on objects on this node.
5097
5098@c XXX - add xref to proxy discussion in MP chapter
5099
5100@c
5101@c === CONFIGURE_MP_MPCI_TABLE_POINTER ===
5102@c
5103@subsection Configure MPCI in Multiprocessor Configuration
5104
5105@findex CONFIGURE_MP_MPCI_TABLE_POINTER
5106
5107@table @b
5108@item CONSTANT:
5109@code{CONFIGURE_MP_MPCI_TABLE_POINTER}
5110
5111@item DATA TYPE:
5112pointer to @code{rtems_mpci_table}
5113
5114@item RANGE:
5115undefined or valid pointer
5116
5117@item DEFAULT VALUE:
5118This is not defined by default.
5119
5120@end table
5121
5122@subheading DESCRIPTION:
5123@code{CONFIGURE_MP_MPCI_TABLE_POINTER} is the pointer to the
5124MPCI Configuration Table.  The default value of this field is
5125@code{&MPCI_table}.
5126
5127@subheading NOTES:
5128RTEMS provides a Shared Memory MPCI Device Driver which can be used on
5129any Multiprocessor System assuming the BSP provides the proper set of
5130supporting methods.
5131
5132@c
5133@c === CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE ===
5134@c
5135@subsection Do Not Generate Multiprocessor Configuration Table
5136
5137@findex CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE
5138
5139@table @b
5140@item CONSTANT:
5141@code{CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE}
5142
5143@item DATA TYPE:
5144Boolean feature macro.
5145
5146@item RANGE:
5147Defined or undefined.
5148
5149@item DEFAULT VALUE:
5150This is not defined by default.
5151
5152@end table
5153
5154@subheading DESCRIPTION:
5155@code{CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE} is defined if the
5156application wishes to provide their own Multiprocessing Configuration
5157Table.  The generated table is named @code{Multiprocessing_configuration}.
5158
5159@subheading NOTES:
5160This is a configuration parameter which is very unlikely to be used by
5161an application. If you find yourself wanting to use it in an application,
5162please reconsider and discuss this on the RTEMS Users mailing list.
5163
5164@c
5165@c === Ada Tasks ===
5166@c
5167@section Ada Tasks
5168
5169This section defines the system configuration parameters supported
5170by @code{<rtems/confdefs.h>} related to configuring RTEMS to support
5171a task using Ada tasking with GNAT/RTEMS.
5172
5173These configuration parameters are only available when RTEMS is built with
5174the @code{--enable-ada} configure option and the application specifies
5175@code{CONFIGURE_GNAT_RTEMS}.
5176
5177Additionally RTEMS includes an Ada language binding to the Classic
5178API which has a test suite. This test suite is enabled only when
5179@code{--enable-tests} and @code{--enable-expada} are specified on the
5180configure command.
5181
5182@c
5183@c === CONFIGURE_GNAT_RTEMS ===
5184@c
5185@subsection Specify Application Includes Ada Code
5186
5187@findex CONFIGURE_GNAT_RTEMS
5188
5189@table @b
5190@item CONSTANT:
5191@code{CONFIGURE_GNAT_RTEMS}
5192
5193@item DATA TYPE:
5194Boolean feature macro.
5195
5196@item RANGE:
5197Defined or undefined.
5198
5199@item DEFAULT VALUE:
5200This is not defined by default.
5201
5202@end table
5203
5204@subheading DESCRIPTION:
5205@code{CONFIGURE_GNAT_RTEMS} is defined to inform RTEMS that the GNAT
5206Ada run-time is to be used by the application.
5207
5208@subheading NOTES:
5209This configuration parameter is critical as it makes
5210@code{<rtems/confdefs.h>} configure the resources (POSIX API Threads,
5211Mutexes, Condition Variables, and Keys) used implicitly by the GNAT
5212run-time.
5213
5214@c
5215@c === CONFIGURE_MAXIMUM_ADA_TASKS ===
5216@c
5217@subsection Specify the Maximum Number of Ada Tasks.
5218
5219@findex CONFIGURE_MAXIMUM_ADA_TASKS
5220
5221@table @b
5222@item CONSTANT:
5223@code{CONFIGURE_MAXIMUM_ADA_TASKS}
5224
5225@item DATA TYPE:
5226Unsigned integer (@code{uint32_t}).
5227
5228@item RANGE:
5229Undefined or positive.
5230
5231@item DEFAULT VALUE:
5232If @code{CONFIGURE_GNAT_RTEMS} is defined, then the
5233default value is 20, otherwise the default value is 0.
5234
5235@end table
5236
5237@subheading DESCRIPTION:
5238@code{CONFIGURE_MAXIMUM_ADA_TASKS} is the number of Ada tasks that can
5239be concurrently active in the system.
5240
5241@subheading NOTES:
5242None.
5243
5244@c
5245@c === CONFIGURE_MAXIMUM_FAKE_ADA_TASKS ===
5246@c
5247@subsection Specify the Maximum Fake Ada Tasks
5248
5249@findex CONFIGURE_MAXIMUM_FAKE_ADA_TASKS
5250
5251@table @b
5252@item CONSTANT:
5253@findex @code{CONFIGURE_MAXIMUM_FAKE_ADA_TASKS}
5254
5255@item DATA TYPE:
5256Unsigned integer (@code{uint32_t}).
5257
5258@item RANGE:
5259Zero or positive.
5260
5261@item DEFAULT VALUE:
5262The default value is 0.
5263
5264@end table
5265
5266@subheading DESCRIPTION:
5267@code{CONFIGURE_MAXIMUM_FAKE_ADA_TASKS} is the number of @i{fake} Ada tasks
5268that can be concurrently active in the system.  A @i{fake} Ada task is
5269a non-Ada task that makes calls back into Ada code and thus implicitly
5270uses the Ada run-time.
5271
5272@subheading NOTES:
5273None.
5274
5275@c
5276@c === PCI Library ===
5277@c
5278@section PCI Library
5279
5280This section defines the system configuration parameters supported
5281by @code{rtems/confdefs.h} related to configuring the PCI Library
5282for RTEMS.
5283
5284The PCI Library startup behaviour can be configured in four different
5285ways depending on how @code{CONFIGURE_PCI_CONFIG_LIB} is defined:
5286
5287@itemize @bullet
5288@findex PCI_LIB_AUTO
5289@item @code{PCI_LIB_AUTO} is used to enable the PCI auto configuration
5290software. PCI will be automatically probed, PCI buses enumerated, all
5291devices and bridges will be initialized using Plug & Play software
5292routines. The PCI device tree will be populated based on the PCI devices
5293found in the system, PCI devices will be configured by allocating address
5294region resources automatically in PCI space according to the BSP or host
5295bridge driver set up.
5296
5297@findex PCI_LIB_READ
5298@item @code{PCI_LIB_READ} is used to enable the PCI read configuration
5299software. The current PCI configuration is read to create the RAM
5300representation (the PCI device tree) of the PCI devices present. PCI devices
5301are assumed to already have been initialized and PCI buses enumerated, it is
5302therefore required that a BIOS or a boot loader has set up configuration space
5303prior to booting into RTEMS.
5304
5305@findex PCI_LIB_STATIC
5306@item @code{PCI_LIB_STATIC} is used to enable the PCI static configuration
5307software. The user provides a PCI tree with information how all PCI devices
5308are to be configured at compile time by linking in a custom
5309@code{struct pci_bus pci_hb} tree. The static PCI library will not probe PCI
5310for devices, instead it will assume that all devices defined by the user are
5311present, it will enumerate the PCI buses and configure all PCI devices in
5312static configuration accordingly. Since probe and allocation software is not
5313needed the startup is faster, has smaller footprint and does not require
5314dynamic memory allocation.
5315
5316@findex PCI_LIB_PERIPHERAL
5317@item @code{PCI_LIB_PERIPHERAL} is used to enable the PCI peripheral
5318configuration. It is similar to @code{PCI_LIB_STATIC}, but it will never write
5319the configuration to the PCI devices since PCI peripherals are not allowed to
5320access PCI configuration space.
5321
5322@end itemize
5323
5324Note that selecting PCI_LIB_STATIC or PCI_LIB_PERIPHERAL but not defining
5325@code{pci_hb} will reuslt in link errors. Note also that in these modes
5326Plug & Play is not performed.
5327
5328@c
5329@c === Go Tasks ===
5330@c
5331@section Go Tasks
5332
5333@c
5334@c === CONFIGURE_ENABLE_GO ===
5335@c
5336@subsection Specify Application Includes Go Code
5337
5338@findex CONFIGURE_ENABLE_GO
5339
5340@table @b
5341@item CONSTANT:
5342@code{CONFIGURE_ENABLE_GO}
5343
5344@item DATA TYPE:
5345Boolean feature macro.
5346
5347@item RANGE:
5348Defined or undefined.
5349
5350@item DEFAULT VALUE:
5351This is not defined by default.
5352
5353@end table
5354
5355@subheading DESCRIPTION:
5356@code{CONFIGURE_ENABLE_GO} is defined to inform RTEMS that the Go
5357run-time is to be used by the application.
5358
5359@subheading NOTES:
5360The Go language support is experimental
5361
5362@c
5363@c === CONFIGURE_MAXIMUM_GOROUTINES ===
5364@c
5365@subsection Specify the maximum number of Go routines
5366
5367@findex CONFIGURE_MAXIMUM_GOROUTINES
5368
5369@table @b
5370@item CONSTANT:
5371@code{CONFIGURE_MAXIMUM_GOROUTINES}
5372
5373@item DATA TYPE:
5374Unsigned integer (@code{uint32_t}).
5375
5376@item RANGE:
5377Zero or positive.
5378
5379@item DEFAULT VALUE:
5380The default value is 400
5381
5382@end table
5383
5384@subheading DESCRIPTION:
5385@code{CONFIGURE_MAXIMUM_GOROUTINES} is defined to specify the maximum number of
5386Go routines.
5387
5388@subheading NOTES:
5389The Go language support is experimental
5390
5391@c
5392@c === CONFIGURE_MAXIMUM_GO_CHANNELS ===
5393@c
5394@subsection Specify the maximum number of Go Channels
5395
5396@findex CONFIGURE_MAXIMUM_GO_CHANNELS
5397
5398@table @b
5399@item CONSTANT:
5400@code{CONFIGURE_MAXIMUM_GO_CHANNELS}
5401
5402@item DATA TYPE:
5403Unsigned integer (@code{uint32_t}).
5404
5405@item RANGE:
5406Zero or positive.
5407
5408@item DEFAULT VALUE:
5409The default value is 500
5410
5411@end table
5412
5413@subheading DESCRIPTION:
5414@code{CONFIGURE_MAXIMUM_GO_CHANNELS} is defined to specify the maximum number
5415of Go channels.
5416
5417@subheading NOTES:
5418The Go language support is experimental
5419
5420@c
5421@c === Configuration Data Structures ===
5422@c
5423@section Configuration Data Structures
5424
5425It is recommended that applications be configured using
5426@code{<rtems/confdefs.h>} as it is simpler and insulates applications
5427from changes in the underlying data structures.  However, it is sometimes
5428important to understand the data structures that are automatically filled
5429in by the configuration parameters.  This section describes the primary
5430configuration data structures.
5431
5432If the user wishes to see the details of a particular data structure,
5433they are are advised to look at the source code. After all, that is one
5434of the advantages of RTEMS.
Note: See TracBrowser for help on using the repository browser.