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

4.11
Last change on this file since cb9bb9d1 was cb9bb9d1, checked in by Joel Sherrill <joel.sherrill@…>, on Oct 20, 2015 at 7:47:10 PM

CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK was undocumented and not error checked

closes #2431.

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