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

4.11
Last change on this file since b9a7dc3b was b9a7dc3b, checked in by Sebastian Huber <sebastian.huber@…>, on Jul 8, 2015 at 8:10:09 AM

doc: Clarify SMP configuration defines

  • Property mode set to 100644
File size: 135.7 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
4421ready.  This configuration define is ignored on uni-processor configurations.
4422
4423@c
4424@c === CONFIGURE_SMP_MAXIMUM_PROCESSORS ===
4425@c
4426@subsection Specify Maximum Processors in SMP System
4427
4428@findex CONFIGURE_SMP_MAXIMUM_PROCESSORS
4429
4430@table @b
4431@item CONSTANT:
4432@code{CONFIGURE_SMP_MAXIMUM_PROCESSORS}
4433
4434@item DATA TYPE:
4435Unsigned integer (@code{uint32_t}).
4436
4437@item RANGE:
4438Defined or undefined.
4439
4440@item DEFAULT VALUE:
4441The default value is 1, (if CONFIGURE_SMP_APPLICATION is defined).
4442
4443@end table
4444
4445@subheading DESCRIPTION:
4446@code{CONFIGURE_SMP_MAXIMUM_PROCESSORS} must be set to the number of
4447processors in the SMP configuration.
4448
4449@subheading NOTES:
4450If there are more processors available than configured, the rest will be
4451ignored.  This configuration define is ignored on uni-processor configurations.
4452
4453@c
4454@c === Device Driver Table ===
4455@c
4456@section Device Driver Table
4457
4458This section defines the configuration parameters related
4459to the automatic generation of a Device Driver Table.  As
4460@code{<rtems/confdefs.h>} only is aware of a small set of
4461standard device drivers, the generated Device Driver
4462Table is suitable for simple applications with no
4463custom device drivers.
4464
4465Note that network device drivers are not configured in the Device Driver Table.
4466
4467@c
4468@c === CONFIGURE_MAXIMUM_DRIVERS ===
4469@c
4470@subsection Specifying the Maximum Number of Device Drivers
4471
4472@findex CONFIGURE_MAXIMUM_DRIVERS
4473
4474@table @b
4475@item CONSTANT:
4476@code{CONFIGURE_MAXIMUM_DRIVERS}
4477
4478@item DATA TYPE:
4479Unsigned integer (@code{uint32_t}).
4480
4481@item RANGE:
4482Zero or positive.
4483
4484@item DEFAULT VALUE:
4485This is computed by default, and is set to the number of device drivers
4486configured using the @code{CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER}
4487configuration parameters.
4488
4489@end table
4490
4491@subheading DESCRIPTION:
4492@code{CONFIGURE_MAXIMUM_DRIVERS} is defined as the number of device
4493drivers per node.
4494
4495@subheading NOTES:
4496If the application will dynamically install device drivers, then this
4497configuration parameter must be larger than the number of statically
4498configured device drivers. Drivers configured using the
4499@code{CONFIGURE_APPLICATIONS_NEEDS_XXX_DRIVER} configuration parameters
4500are statically installed.
4501
4502@c
4503@c === CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER ===
4504@c
4505@subsection Enable Console Device Driver
4506
4507@findex CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
4508
4509@table @b
4510@item CONSTANT:
4511@code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER}
4512
4513@item DATA TYPE:
4514Boolean feature macro.
4515
4516@item RANGE:
4517Defined or undefined.
4518
4519@item DEFAULT VALUE:
4520This is not defined by default.
4521
4522@end table
4523
4524@subheading DESCRIPTION:
4525@code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER} is defined if the
4526application wishes to include the Console Device Driver.
4527
4528@subheading NOTES:
4529This device driver is responsible for providing standard input and output
4530using @i{/dev/console}.
4531
4532BSPs should be constructed in a manner that allows @code{printk()}
4533to work properly without the need for the console driver to be configured.
4534
4535@c
4536@c === CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER ===
4537@c
4538@subsection Enable Clock Driver
4539
4540@findex CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
4541
4542@table @b
4543@item CONSTANT:
4544@code{CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER}
4545
4546@item DATA TYPE:
4547Boolean feature macro.
4548
4549@item RANGE:
4550Defined or undefined.
4551
4552@item DEFAULT VALUE:
4553This is not defined by default.
4554
4555@end table
4556
4557@subheading DESCRIPTION:
4558@code{CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER} is defined if the
4559application wishes to include the Clock Device Driver.
4560
4561@subheading NOTES:
4562This device driver is responsible for providing a regular
4563interrupt which invokes the @code{rtems_clock_tick} directive.
4564
4565If neither the Clock Driver not Benchmark Timer is enabled and
4566the configuration parameter
4567@code{CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER} is not defined,
4568then a compile time error will occur.
4569
4570@c
4571@c === CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER ===
4572@c
4573@subsection Enable the Benchmark Timer Driver
4574
4575@findex CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
4576
4577@table @b
4578@item CONSTANT:
4579@code{CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER}
4580
4581@item DATA TYPE:
4582Boolean feature macro.
4583
4584@item RANGE:
4585Defined or undefined.
4586
4587@item DEFAULT VALUE:
4588This is not defined by default.
4589
4590@end table
4591
4592@subheading DESCRIPTION:
4593@code{CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER} is defined if the
4594application wishes to include the Timer Driver.  This device driver is
4595used to benchmark execution times by the RTEMS Timing Test Suites.
4596
4597@subheading NOTES:
4598If neither the Clock Driver not Benchmark Timer is enabled and
4599the configuration parameter
4600@code{CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER} is not defined,
4601then a compile time error will occur.
4602
4603@c
4604@c === CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER ===
4605@c
4606@subsection Specify Clock and Benchmark Timer Drivers Are Not Needed
4607
4608@findex CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
4609
4610@table @b
4611@item CONSTANT:
4612@code{CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER}
4613
4614@item DATA TYPE:
4615Boolean feature macro.
4616
4617@item RANGE:
4618Defined or undefined.
4619
4620@item DEFAULT VALUE:
4621This is not defined by default.
4622
4623@end table
4624
4625@subheading DESCRIPTION:
4626@code{CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER} is defined when
4627the application does @b{NOT} want the Clock Device Driver and is @b{NOT}
4628using the Timer Driver.  The inclusion or exclusion of the Clock Driver
4629must be explicit in user applications.
4630
4631@subheading NOTES:
4632This configuration parameter is intended to prevent the common user error
4633of using the Hello World example as the baseline for an application and
4634leaving out a clock tick source.
4635
4636@c
4637@c === CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER ===
4638@c
4639@subsection Enable Real-Time Clock Driver
4640
4641@findex CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER
4642
4643@table @b
4644@item CONSTANT:
4645@code{CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER}
4646
4647@item DATA TYPE:
4648Boolean feature macro.
4649
4650@item RANGE:
4651Defined or undefined.
4652
4653@item DEFAULT VALUE:
4654This is not defined by default.
4655
4656@end table
4657
4658@subheading DESCRIPTION:
4659@code{CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER} is defined if the
4660application wishes to include the Real-Time Clock Driver.
4661
4662@subheading NOTES:
4663Most BSPs do not include support for a real-time clock. This is because
4664many boards do not include the required hardware.
4665
4666If this is defined and the BSP does not have this device driver, then
4667the user will get a link time error for an undefined symbol.
4668
4669@c
4670@c === CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER ===
4671@c
4672@subsection Enable the Watchdog Device Driver
4673
4674@findex CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER
4675
4676@table @b
4677@item CONSTANT:
4678@code{CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER}
4679
4680@item DATA TYPE:
4681Boolean feature macro.
4682
4683@item RANGE:
4684Defined or undefined.
4685
4686@item DEFAULT VALUE:
4687This is not defined by default.
4688
4689@end table
4690
4691@subheading DESCRIPTION:
4692@code{CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER}
4693is defined if the application wishes to include the Watchdog Driver.
4694
4695@subheading NOTES:
4696Most BSPs do not include support for a watchdog device driver. This is
4697because many boards do not include the required hardware.
4698
4699If this is defined and the BSP does not have this device driver, then
4700the user will get a link time error for an undefined symbol.
4701
4702@c
4703@c === CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER ===
4704@c
4705@subsection Enable the Graphics Frame Buffer Device Driver
4706
4707@findex CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER
4708
4709@table @b
4710@item CONSTANT:
4711@code{CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER}
4712
4713@item DATA TYPE:
4714Boolean feature macro.
4715
4716@item RANGE:
4717Defined or undefined.
4718
4719@item DEFAULT VALUE:
4720This is not defined by default.
4721
4722@end table
4723
4724@subheading DESCRIPTION:
4725@code{CONFIGURE_APPLICATION_NEEDS_FRAME_BUFFER_DRIVER} is defined
4726if the application wishes to include the BSP's Frame Buffer Device Driver.
4727
4728@subheading NOTES:
4729Most BSPs do not include support for a Frame Buffer Device Driver. This is
4730because many boards do not include the required hardware.
4731
4732If this is defined and the BSP does not have this device driver, then
4733the user will get a link time error for an undefined symbol.
4734
4735@c
4736@c === CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER ===
4737@c
4738@subsection Enable Stub Device Driver
4739
4740@findex CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER
4741
4742@table @b
4743@item CONSTANT:
4744@code{CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER}
4745
4746@item DATA TYPE:
4747Boolean feature macro.
4748
4749@item RANGE:
4750Defined or undefined.
4751
4752@item DEFAULT VALUE:
4753This is not defined by default.
4754
4755@end table
4756
4757@subheading DESCRIPTION:
4758@code{CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER} is defined if the
4759application wishes to include the Stub Device Driver.
4760
4761@subheading NOTES:
4762This device driver simply provides entry points that return successful
4763and is primarily a test fixture. It is supported by all BSPs.
4764
4765@c
4766@c === CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS ===
4767@c
4768@subsection Specify Application Prerequisite Device Drivers
4769
4770@findex CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS
4771
4772@table @b
4773@item CONSTANT:
4774@code{CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS}
4775
4776@item DATA TYPE:
4777device driver entry structures
4778
4779@item RANGE:
4780Undefined or set of device driver entry structures
4781
4782@item DEFAULT VALUE:
4783This is not defined by default.
4784
4785@end table
4786
4787@subheading DESCRIPTION:
4788@code{CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS} is defined if the
4789application has device drivers it needs to include in the Device Driver
4790Table.  This should be defined to the set of device driver entries that
4791will be placed in the table at the @b{FRONT} of the Device Driver Table
4792and initialized before any other drivers @b{EXCEPT} any BSP prerequisite
4793drivers.
4794
4795@subheading NOTES:
4796In some cases, it is used by System On Chip BSPs to support peripheral
4797buses beyond those normally found on the System On Chip. For example,
4798this is used by one RTEMS system which has implemented a SPARC/ERC32
4799based board with VMEBus. The VMEBus Controller initialization is performed
4800by a device driver configured via this configuration parameter.
4801
4802@c XXX Add example
4803
4804@c
4805@c === CONFIGURE_APPLICATION_EXTRA_DRIVERS ===
4806@c
4807@subsection Specify Extra Application Device Drivers
4808
4809@findex CONFIGURE_APPLICATION_EXTRA_DRIVERS
4810
4811@table @b
4812@item CONSTANT:
4813@code{CONFIGURE_APPLICATION_EXTRA_DRIVERS}
4814
4815@item DATA TYPE:
4816device driver entry structures
4817
4818@item RANGE:
4819Undefined or set of device driver entry structures
4820
4821@item DEFAULT VALUE:
4822This is not defined by default.
4823
4824@end table
4825
4826@subheading DESCRIPTION:
4827@code{CONFIGURE_APPLICATION_EXTRA_DRIVERS} is defined if the
4828application has device drivers it needs to include in the Device Driver
4829Table.  This should be defined to the set of device driver entries that
4830will be placed in the table at the @b{END} of the Device Driver Table.
4831
4832@subheading NOTES:
4833None.
4834
4835@c
4836@c === CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER ===
4837@c
4838@subsection Enable /dev/null Device Driver
4839
4840@findex CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER
4841@cindex /dev/null
4842
4843@table @b
4844@item CONSTANT:
4845@code{CONFIGURE_APPLICATION_NEEDS_NULL_DRIVER}
4846
4847@item DATA TYPE:
4848Boolean feature macro.
4849
4850@item RANGE:
4851Defined or undefined.
4852
4853@item DEFAULT VALUE:
4854This is not defined by default.
4855
4856@end table
4857
4858@subheading DESCRIPTION:
4859This configuration variable is specified to enable @i{/dev/null}
4860device driver.
4861
4862@subheading NOTES:
4863This device driver is supported by all BSPs.
4864
4865@c
4866@c === CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER ===
4867@c
4868@subsection Enable /dev/zero Device Driver
4869
4870@findex CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER
4871@cindex /dev/zero
4872
4873@table @b
4874@item CONSTANT:
4875@code{CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER}
4876
4877@item DATA TYPE:
4878Boolean feature macro.
4879
4880@item RANGE:
4881Defined or undefined.
4882
4883@item DEFAULT VALUE:
4884This is not defined by default.
4885
4886@end table
4887
4888@subheading DESCRIPTION:
4889This configuration variable is specified to enable @i{/dev/zero}
4890device driver.
4891
4892@subheading NOTES:
4893This device driver is supported by all BSPs.
4894
4895@c
4896@c === CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE ===
4897@c
4898@subsection Specifying Application Defined Device Driver Table
4899
4900@findex CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE
4901
4902@table @b
4903@item CONSTANT:
4904@code{CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE}
4905
4906@item DATA TYPE:
4907Boolean feature macro.
4908
4909@item RANGE:
4910Defined or undefined.
4911
4912@item DEFAULT VALUE:
4913This is not defined by default, indicating the @code{<rtems/confdefs.h>}
4914is providing the device driver table.
4915
4916@end table
4917
4918@subheading DESCRIPTION:
4919@code{CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE} is defined if the application
4920wishes to provide their own Device Driver Table.
4921
4922The table must be an array of @code{rtems_driver_address_table} entries named
4923@code{_IO_Driver_address_table}.  The application must also provide a const
4924variable @code{_IO_Number_of_drivers} of type @code{size_t} indicating the
4925number of entries in the @code{_IO_Driver_address_table}.
4926
4927@subheading NOTES:
4928It is expected that there the application would only rarely need to do this.
4929
4930@c
4931@c === Multiprocessing Configuration ===
4932@c
4933@section Multiprocessing Configuration
4934
4935This section defines the multiprocessing related system configuration
4936parameters supported by @code{<rtems/confdefs.h>}.  They are only used
4937if the Multiprocessing Support (distinct from the SMP support) is enabled
4938at configure time using the @code{--enable-multiprocessing} option.
4939
4940Additionally, this class of Configuration Constants are only applicable if
4941@code{CONFIGURE_MP_APPLICATION} is defined.
4942
4943@c
4944@c === CONFIGURE_MP_APPLICATION ===
4945@c
4946@subsection Specify Application Will Use Multiprocessing
4947
4948@findex CONFIGURE_MP_APPLICATION
4949
4950@table @b
4951@item CONSTANT:
4952@code{CONFIGURE_MP_APPLICATION}
4953
4954@item DATA TYPE:
4955Boolean feature macro.
4956
4957@item RANGE:
4958Defined or undefined.
4959
4960@item DEFAULT VALUE:
4961This is not defined by default.
4962
4963@end table
4964
4965@subheading DESCRIPTION:
4966This configuration parameter must be defined to indicate
4967that the application intends to be part of a multiprocessing
4968configuration. Additional configuration parameters are assumed to be
4969provided.
4970
4971@subheading NOTES:
4972This has no impact unless RTEMS was configured and built using the
4973@code{--enable-multiprocessing} option.
4974
4975@c
4976@c === CONFIGURE_MP_NODE_NUMBER ===
4977@c
4978@subsection Configure Node Number in Multiprocessor Configuration
4979
4980@findex CONFIGURE_MP_NODE_NUMBER
4981
4982@table @b
4983@item CONSTANT:
4984@code{CONFIGURE_MP_NODE_NUMBER}
4985
4986@item DATA TYPE:
4987Unsigned integer (@code{uint32_t}).
4988
4989@item RANGE:
4990Positive.
4991
4992@item DEFAULT VALUE:
4993The default value is @code{NODE_NUMBER}, which is assumed to be
4994set by the compilation environment.
4995
4996@end table
4997
4998@subheading DESCRIPTION:
4999@code{CONFIGURE_MP_NODE_NUMBER} is the node number of
5000this node in a multiprocessor system.
5001
5002@subheading NOTES:
5003In the RTEMS Multiprocessing Test Suite, the node number is derived from
5004the Makefile variable @code{NODE_NUMBER}. The same code is compiled with
5005the @code{NODE_NUMBER} set to different values. The test programs behave
5006differently based upon their node number.
5007
5008
5009@c
5010@c === CONFIGURE_MP_MAXIMUM_NODES ===
5011@c
5012@subsection Configure Maximum Node in Multiprocessor Configuration
5013
5014@findex CONFIGURE_MP_MAXIMUM_NODES
5015
5016@table @b
5017@item CONSTANT:
5018@code{CONFIGURE_MP_MAXIMUM_NODES}
5019
5020@item DATA TYPE:
5021Unsigned integer (@code{uint32_t}).
5022
5023@item RANGE:
5024Positive.
5025
5026@item DEFAULT VALUE:
5027The default value is 2.
5028
5029@end table
5030
5031@subheading DESCRIPTION:
5032@code{CONFIGURE_MP_MAXIMUM_NODES} is the maximum number of nodes in a
5033multiprocessor system.
5034
5035@subheading NOTES:
5036None.
5037
5038@c
5039@c === CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS ===
5040@c
5041@subsection Configure Maximum Global Objects in Multiprocessor Configuration
5042
5043@findex CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS
5044
5045@table @b
5046@item CONSTANT:
5047@code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS}
5048
5049@item DATA TYPE:
5050Unsigned integer (@code{uint32_t}).
5051
5052@item RANGE:
5053Positive.
5054
5055@item DEFAULT VALUE:
5056The default value is 32.
5057
5058@end table
5059
5060@subheading DESCRIPTION:
5061@code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS} is the maximum number of
5062concurrently active global objects in a multiprocessor system.
5063
5064@subheading NOTES:
5065This value corresponds to the total number of objects which can be
5066created with the @code{RTEMS_GLOBAL} attribute.
5067
5068@c
5069@c === CONFIGURE_MP_MAXIMUM_PROXIES ===
5070@c
5071@subsection Configure Maximum Proxies in Multiprocessor Configuration
5072
5073@findex CONFIGURE_MP_MAXIMUM_PROXIES
5074
5075@table @b
5076@item CONSTANT:
5077@code{CONFIGURE_MP_MAXIMUM_PROXIES}
5078
5079@item DATA TYPE:
5080Unsigned integer (@code{uint32_t}).
5081
5082@item RANGE:
5083Undefined or positive.
5084
5085@item DEFAULT VALUE:
5086The default value is 32.
5087
5088@end table
5089
5090@subheading DESCRIPTION:
5091@code{CONFIGURE_MP_MAXIMUM_PROXIES} is the maximum number of concurrently
5092active thread/task proxies on this node in a multiprocessor system.
5093
5094@subheading NOTES:
5095Since a proxy is used to represent a remote task/thread which is blocking on
5096this node. This configuration parameter reflects the maximum number of
5097remote tasks/threads which can be blocked on objects on this node.
5098
5099@c XXX - add xref to proxy discussion in MP chapter
5100
5101@c
5102@c === CONFIGURE_MP_MPCI_TABLE_POINTER ===
5103@c
5104@subsection Configure MPCI in Multiprocessor Configuration
5105
5106@findex CONFIGURE_MP_MPCI_TABLE_POINTER
5107
5108@table @b
5109@item CONSTANT:
5110@code{CONFIGURE_MP_MPCI_TABLE_POINTER}
5111
5112@item DATA TYPE:
5113pointer to @code{rtems_mpci_table}
5114
5115@item RANGE:
5116undefined or valid pointer
5117
5118@item DEFAULT VALUE:
5119This is not defined by default.
5120
5121@end table
5122
5123@subheading DESCRIPTION:
5124@code{CONFIGURE_MP_MPCI_TABLE_POINTER} is the pointer to the
5125MPCI Configuration Table.  The default value of this field is
5126@code{&MPCI_table}.
5127
5128@subheading NOTES:
5129RTEMS provides a Shared Memory MPCI Device Driver which can be used on
5130any Multiprocessor System assuming the BSP provides the proper set of
5131supporting methods.
5132
5133@c
5134@c === CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE ===
5135@c
5136@subsection Do Not Generate Multiprocessor Configuration Table
5137
5138@findex CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE
5139
5140@table @b
5141@item CONSTANT:
5142@code{CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE}
5143
5144@item DATA TYPE:
5145Boolean feature macro.
5146
5147@item RANGE:
5148Defined or undefined.
5149
5150@item DEFAULT VALUE:
5151This is not defined by default.
5152
5153@end table
5154
5155@subheading DESCRIPTION:
5156@code{CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE} is defined if the
5157application wishes to provide their own Multiprocessing Configuration
5158Table.  The generated table is named @code{Multiprocessing_configuration}.
5159
5160@subheading NOTES:
5161This is a configuration parameter which is very unlikely to be used by
5162an application. If you find yourself wanting to use it in an application,
5163please reconsider and discuss this on the RTEMS Users mailing list.
5164
5165@c
5166@c === Ada Tasks ===
5167@c
5168@section Ada Tasks
5169
5170This section defines the system configuration parameters supported
5171by @code{<rtems/confdefs.h>} related to configuring RTEMS to support
5172a task using Ada tasking with GNAT/RTEMS.
5173
5174These configuration parameters are only available when RTEMS is built with
5175the @code{--enable-ada} configure option and the application specifies
5176@code{CONFIGURE_GNAT_RTEMS}.
5177
5178Additionally RTEMS includes an Ada language binding to the Classic
5179API which has a test suite. This test suite is enabled only when
5180@code{--enable-tests} and @code{--enable-expada} are specified on the
5181configure command.
5182
5183@c
5184@c === CONFIGURE_GNAT_RTEMS ===
5185@c
5186@subsection Specify Application Includes Ada Code
5187
5188@findex CONFIGURE_GNAT_RTEMS
5189
5190@table @b
5191@item CONSTANT:
5192@code{CONFIGURE_GNAT_RTEMS}
5193
5194@item DATA TYPE:
5195Boolean feature macro.
5196
5197@item RANGE:
5198Defined or undefined.
5199
5200@item DEFAULT VALUE:
5201This is not defined by default.
5202
5203@end table
5204
5205@subheading DESCRIPTION:
5206@code{CONFIGURE_GNAT_RTEMS} is defined to inform RTEMS that the GNAT
5207Ada run-time is to be used by the application.
5208
5209@subheading NOTES:
5210This configuration parameter is critical as it makes
5211@code{<rtems/confdefs.h>} configure the resources (POSIX API Threads,
5212Mutexes, Condition Variables, and Keys) used implicitly by the GNAT
5213run-time.
5214
5215@c
5216@c === CONFIGURE_MAXIMUM_ADA_TASKS ===
5217@c
5218@subsection Specify the Maximum Number of Ada Tasks.
5219
5220@findex CONFIGURE_MAXIMUM_ADA_TASKS
5221
5222@table @b
5223@item CONSTANT:
5224@code{CONFIGURE_MAXIMUM_ADA_TASKS}
5225
5226@item DATA TYPE:
5227Unsigned integer (@code{uint32_t}).
5228
5229@item RANGE:
5230Undefined or positive.
5231
5232@item DEFAULT VALUE:
5233If @code{CONFIGURE_GNAT_RTEMS} is defined, then the
5234default value is 20, otherwise the default value is 0.
5235
5236@end table
5237
5238@subheading DESCRIPTION:
5239@code{CONFIGURE_MAXIMUM_ADA_TASKS} is the number of Ada tasks that can
5240be concurrently active in the system.
5241
5242@subheading NOTES:
5243None.
5244
5245@c
5246@c === CONFIGURE_MAXIMUM_FAKE_ADA_TASKS ===
5247@c
5248@subsection Specify the Maximum Fake Ada Tasks
5249
5250@findex CONFIGURE_MAXIMUM_FAKE_ADA_TASKS
5251
5252@table @b
5253@item CONSTANT:
5254@findex @code{CONFIGURE_MAXIMUM_FAKE_ADA_TASKS}
5255
5256@item DATA TYPE:
5257Unsigned integer (@code{uint32_t}).
5258
5259@item RANGE:
5260Zero or positive.
5261
5262@item DEFAULT VALUE:
5263The default value is 0.
5264
5265@end table
5266
5267@subheading DESCRIPTION:
5268@code{CONFIGURE_MAXIMUM_FAKE_ADA_TASKS} is the number of @i{fake} Ada tasks
5269that can be concurrently active in the system.  A @i{fake} Ada task is
5270a non-Ada task that makes calls back into Ada code and thus implicitly
5271uses the Ada run-time.
5272
5273@subheading NOTES:
5274None.
5275
5276@c
5277@c === PCI Library ===
5278@c
5279@section PCI Library
5280
5281This section defines the system configuration parameters supported
5282by @code{rtems/confdefs.h} related to configuring the PCI Library
5283for RTEMS.
5284
5285The PCI Library startup behaviour can be configured in four different
5286ways depending on how @code{CONFIGURE_PCI_CONFIG_LIB} is defined:
5287
5288@itemize @bullet
5289@findex PCI_LIB_AUTO
5290@item @code{PCI_LIB_AUTO} is used to enable the PCI auto configuration
5291software. PCI will be automatically probed, PCI buses enumerated, all
5292devices and bridges will be initialized using Plug & Play software
5293routines. The PCI device tree will be populated based on the PCI devices
5294found in the system, PCI devices will be configured by allocating address
5295region resources automatically in PCI space according to the BSP or host
5296bridge driver set up.
5297
5298@findex PCI_LIB_READ
5299@item @code{PCI_LIB_READ} is used to enable the PCI read configuration
5300software. The current PCI configuration is read to create the RAM
5301representation (the PCI device tree) of the PCI devices present. PCI devices
5302are assumed to already have been initialized and PCI buses enumerated, it is
5303therefore required that a BIOS or a boot loader has set up configuration space
5304prior to booting into RTEMS.
5305
5306@findex PCI_LIB_STATIC
5307@item @code{PCI_LIB_STATIC} is used to enable the PCI static configuration
5308software. The user provides a PCI tree with information how all PCI devices
5309are to be configured at compile time by linking in a custom
5310@code{struct pci_bus pci_hb} tree. The static PCI library will not probe PCI
5311for devices, instead it will assume that all devices defined by the user are
5312present, it will enumerate the PCI buses and configure all PCI devices in
5313static configuration accordingly. Since probe and allocation software is not
5314needed the startup is faster, has smaller footprint and does not require
5315dynamic memory allocation.
5316
5317@findex PCI_LIB_PERIPHERAL
5318@item @code{PCI_LIB_PERIPHERAL} is used to enable the PCI peripheral
5319configuration. It is similar to @code{PCI_LIB_STATIC}, but it will never write
5320the configuration to the PCI devices since PCI peripherals are not allowed to
5321access PCI configuration space.
5322
5323@end itemize
5324
5325Note that selecting PCI_LIB_STATIC or PCI_LIB_PERIPHERAL but not defining
5326@code{pci_hb} will reuslt in link errors. Note also that in these modes
5327Plug & Play is not performed.
5328
5329@c
5330@c === Go Tasks ===
5331@c
5332@section Go Tasks
5333
5334@c
5335@c === CONFIGURE_ENABLE_GO ===
5336@c
5337@subsection Specify Application Includes Go Code
5338
5339@findex CONFIGURE_ENABLE_GO
5340
5341@table @b
5342@item CONSTANT:
5343@code{CONFIGURE_ENABLE_GO}
5344
5345@item DATA TYPE:
5346Boolean feature macro.
5347
5348@item RANGE:
5349Defined or undefined.
5350
5351@item DEFAULT VALUE:
5352This is not defined by default.
5353
5354@end table
5355
5356@subheading DESCRIPTION:
5357@code{CONFIGURE_ENABLE_GO} is defined to inform RTEMS that the Go
5358run-time is to be used by the application.
5359
5360@subheading NOTES:
5361The Go language support is experimental
5362
5363@c
5364@c === CONFIGURE_MAXIMUM_GOROUTINES ===
5365@c
5366@subsection Specify the maximum number of Go routines
5367
5368@findex CONFIGURE_MAXIMUM_GOROUTINES
5369
5370@table @b
5371@item CONSTANT:
5372@code{CONFIGURE_MAXIMUM_GOROUTINES}
5373
5374@item DATA TYPE:
5375Unsigned integer (@code{uint32_t}).
5376
5377@item RANGE:
5378Zero or positive.
5379
5380@item DEFAULT VALUE:
5381The default value is 400
5382
5383@end table
5384
5385@subheading DESCRIPTION:
5386@code{CONFIGURE_MAXIMUM_GOROUTINES} is defined to specify the maximum number of
5387Go routines.
5388
5389@subheading NOTES:
5390The Go language support is experimental
5391
5392@c
5393@c === CONFIGURE_MAXIMUM_GO_CHANNELS ===
5394@c
5395@subsection Specify the maximum number of Go Channels
5396
5397@findex CONFIGURE_MAXIMUM_GO_CHANNELS
5398
5399@table @b
5400@item CONSTANT:
5401@code{CONFIGURE_MAXIMUM_GO_CHANNELS}
5402
5403@item DATA TYPE:
5404Unsigned integer (@code{uint32_t}).
5405
5406@item RANGE:
5407Zero or positive.
5408
5409@item DEFAULT VALUE:
5410The default value is 500
5411
5412@end table
5413
5414@subheading DESCRIPTION:
5415@code{CONFIGURE_MAXIMUM_GO_CHANNELS} is defined to specify the maximum number
5416of Go channels.
5417
5418@subheading NOTES:
5419The Go language support is experimental
5420
5421@c
5422@c === Configuration Data Structures ===
5423@c
5424@section Configuration Data Structures
5425
5426It is recommended that applications be configured using
5427@code{<rtems/confdefs.h>} as it is simpler and insulates applications
5428from changes in the underlying data structures.  However, it is sometimes
5429important to understand the data structures that are automatically filled
5430in by the configuration parameters.  This section describes the primary
5431configuration data structures.
5432
5433If the user wishes to see the details of a particular data structure,
5434they are are advised to look at the source code. After all, that is one
5435of the advantages of RTEMS.
Note: See TracBrowser for help on using the repository browser.