source: rtems/doc/user/conf.t @ 96a0303b

4.104.11
Last change on this file since 96a0303b was 96a0303b, checked in by Joel Sherrill <joel.sherrill@…>, on Sep 17, 2008 at 7:03:10 PM

2008-09-17 Joel Sherrill <joel.sherrill@…>

  • user/conf.t: Fix typo.
  • Property mode set to 100644
File size: 79.8 KB
Line 
1@c  COPYRIGHT (c) 1988-2008.
2@c  On-Line Applications Research Corporation (OAR).
3@c  All rights reserved.
4@c
5@c  $Id$
6@c
7
8@c The following macros from confdefs.h have not been discussed in this
9@c chapter:
10@c
11@c CONFIGURE_NEWLIB_EXTENSION - probably not needed
12@c
13@c In addition, there should be examples of defining your own
14@c Device Driver Table, Init task table, etc.
15@c
16@c Regardless, this is a big step up. :)
17@c
18
19@chapter Configuring a System
20
21@section Introduction
22
23RTEMS must be configured for an application.  This configuration
24information encompasses a variety of information including
25the length of each clock tick, the maximum number of each RTEMS
26object that can be created, the application initialization tasks,
27and the device drivers in the application.  This information
28is placed in data structures that are given to RTEMS at
29system initialization time.  This chapter details the
30format of these data structures as well as a simpler
31mechanism to automate the generation of these structures.
32
33@ifset is-Ada
34System configuration is ALWAYS done from C.  When developing
35an Ada application, the user is responsible for creating at
36least one C file which contains the Ada run-time initialization
37and the RTEMS System Configuration.  There is no Ada binding
38for RTEMS System Configuration information.  Thus all examples
39and data structures shown in this chapter are in C.
40@end ifset
41
42@section Automatic Generation of System Configuration
43
44@cindex confdefs.h
45@findex confdefs.h
46
47RTEMS provides the @code{rtems/confdefs.h} C language header file that
48based on the setting of a variety of macros can automatically
49produce nearly all of the configuration tables required
50by an RTEMS application.  Rather than building the individual
51tables by hand, the application simply specifies the values
52for the configuration parameters it wishes to set.  In the following
53example, the configuration information for a simple system with
54a message queue and a time slice of 50 milliseconds is configured:
55
56@example
57@group
58#define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
59#define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
60
61#define CONFIGURE_MICROSECONDS_PER_TICK   1000 /* 1 millisecond */
62#define CONFIGURE_TICKS_PER_TIMESLICE       50 /* 50 milliseconds */
63
64#define CONFIGURE_MAXIMUM_TASKS 4
65#define CONFIGURE_RTEMS_INIT_TASKS_TABLE
66@end group
67@end example
68
69This system will begin execution with the single initialization task
70named @code{Init}.  It will be configured to have both a console
71device driver (for standard I/O) and a clock tick device driver.
72
73For each configuration parameter in the configuration tables, the
74macro corresponding to that field is discussed.  Most systems
75can be easily configured using the @code{rtems/confdefs.h} mechanism.
76
77The @code{CONFIGURE_INIT} constant must be defined in order to
78make @code{rtems/confdefs.h} instantiate the configuration data
79structures.  This can only be defined in one source file per
80application that includes @code{rtems/confdefs.h} or the symbol
81table will be instantiated multiple times and linking errors
82produced.
83
84The user should be aware that the defaults are intentionally
85set as low as possible.  By default, no application resources
86are configured.  The @code{rtems/confdefs.h} file ensures that
87at least one application tasks or thread is configured
88and that at least one of the initialization task/thread
89tables is configured.
90
91The @code{rtems/confdefs.h} file estimates the amount of
92memory required for the RTEMS Executive Workspace.  This
93estimate is only as accurate as the information given
94to @code{rtems/confdefs.h} and may be either too high or too
95low for a variety of reasons.  Some of the reasons that
96@code{rtems/confdefs.h} may reserve too much memory for RTEMS
97are:
98
99@itemize @bullet
100@item All tasks/threads are assumed to be floating point.
101@end itemize
102
103Conversely, there are many more reasons, the resource
104estimate could be too low:
105
106@itemize @bullet
107@item Task/thread stacks greater than minimum size must be
108accounted for explicitly by developer.
109
110@item Memory for messages is not included.
111
112@item Device driver requirements are not included.
113
114
115@item Network stack requirements are not included.
116
117@item Requirements for add-on libraries are not included.
118@end itemize
119
120In general, @code{rtems/confdefs.h} is very accurate when given
121enough information.  However, it is quite easy to use
122a library and not account for its resources.
123
124The following subsection list all of the constants which can be
125set by the user.
126
127@subsection Library Support Definitions
128
129This section defines the file system and IO library
130related configuration parameters supported by
131@code{rtems/confdefs.h}.
132
133@itemize @bullet
134@findex CONFIGURE_MALLOC_STATISTICS
135@item @code{CONFIGURE_MALLOC_STATISTICS} is defined when the application
136wishes to enable the gathering of more detailed statistics on the
137C Malloc Family of routines.
138
139@findex CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
140@item @code{CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK} is defined by a BSP
141to indicate that it does not allocate all available memory to the
142C Program Heap used by the Malloc Family of routines.  If defined,
143when @code{malloc()} is unable to allocate memory, it will call
144the BSP supplied @code{sbrk()} to obtain more memory.
145
146@findex CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS
147@item @code{CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS} is set to the
148maximum number of files that can be concurrently open.  Libio requires
149a Classic RTEMS semaphore for each file descriptor as well as one
150global one.  The default value is 3 file descriptors which is
151enough to support standard input, output, and error output.
152
153@findex CONFIGURE_TERMIOS_DISABLED
154@item @code{CONFIGURE_TERMIOS_DISABLED} is defined if the
155software implementing POSIX termios functionality is
156not going to be used by this application.  By default, this
157is not defined and resources are reserved for the
158termios functionality.
159
160@findex CONFIGURE_NUMBER_OF_TERMIOS_PORTS
161@item @code{CONFIGURE_NUMBER_OF_TERMIOS_PORTS} is set to the
162number of ports using the termios functionality.  Each
163concurrently active termios port requires resources.
164By default, this is set to 1 so a console port can be
165used.
166
167@findex CONFIGURE_HAS_OWN_MOUNT_TABLE
168@item @code{CONFIGURE_HAS_OWN_MOUNT_TABLE} is defined when the
169application provides their own filesystem mount table.  The
170mount table is an array of @code{rtems_filesystem_mount_table_t}
171entries pointed to by the global variable
172@code{rtems_filesystem_mount_table}.  The number of
173entries in this table is in an integer variable named
174@code{rtems_filesystem_mount_table_t}.
175
176@findex CONFIGURE_USE_IMFS_AS_BASE_FILESYSTEM
177@item @code{CONFIGURE_USE_IMFS_AS_BASE_FILESYSTEM} is defined
178if the application wishes to use the full functionality
179IMFS.  By default, the miniIMFS is used.  The miniIMFS
180is a minimal functionality subset of the In-Memory
181FileSystem (IMFS).  The miniIMFS is comparable
182in functionality to the pseudo-filesystem name space provided
183before RTEMS release 4.5.0.  The miniIMFS supports
184only directories and device nodes and is smaller in executable
185code size than the full IMFS.
186
187@findex STACK_CHECKER_ON
188@item @code{STACK_CHECKER_ON} is defined when the application
189wishes to enable run-time stack bounds checking.  This increases
190the time required to create tasks as well as adding overhead
191to each context switch.  By default, this is not defined and
192thus stack checking is disabled.
193
194@end itemize
195
196@subsection Basic System Information
197
198This section defines the general system configuration parameters supported by
199@code{rtems/confdefs.h}.
200
201@itemize @bullet
202@findex CONFIGURE_HAS_OWN_CONFIGURATION_TABLE
203@item @code{CONFIGURE_HAS_OWN_CONFIGURATION_TABLE} should only be defined
204if the application is providing their own complete set of configuration
205tables.
206
207@findex CONFIGURE_EXECUTIVE_RAM_WORK_AREA
208@item @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA} is the base
209address of the RTEMS RAM Workspace.  By default, this value
210is NULL indicating that the BSP is to determine the location
211of the RTEMS RAM Workspace.
212
213@findex CONFIGURE_UNIFIED_WORK_AREAS
214@item @code{CONFIGURE_UNIFIED_WORK_AREAS} configures RTEMS to use a
215single memory pool for the RTEMS Workspace and C Program Heap.  If not
216defined, there will be separate memory pools for the RTEMS Workspace and
217C Program Heap.  Having separate pools does have some advantages in the
218event a task blows a stack or writes outside its memory area. However,
219in low memory systems the overhead of the two pools plus the potential
220for unused memory in either pool is very undesirable.
221
222In high memory environments, this is desirable when you want to use the
223RTEMS "unlimited" objects option.  You will be able to create objects
224until you run out of all available memory rather then just until you
225run out of RTEMS Workspace.
226
227@item @code{CONFIGURE_MICROSECONDS_PER_TICK} is the length
228of time between clock ticks.  By default, this is set to
22910000 microseconds.
230
231@findex CONFIGURE_TICKS_PER_TIMESLICE
232@item @code{CONFIGURE_TICKS_PER_TIMESLICE} is the length
233of the timeslice quantum in ticks for each task.  By
234default, this is 50.
235
236@findex CONFIGURE_MAXIMUM_PRIORITY
237@item @code{CONFIGURE_MAXIMUM_PRIORITY} is the maximum numeric priority
238of any task in the system and one less that the number of priority levels
239in the system.  The numerically greatest priority is the logically lowest
240priority in the system and will thus be used by the IDLE task.  Valid values
241for this configuration parameter must be one (1) less than than a power
242of two (2) between 4 and 256 inclusively.  In other words, valid values
243are 3, 7, 31, 63, 127, and 255.  Reducing the number of priorities in the
244system reduces the amount of memory allocated from the RTEMS Workspace.
245By default, RTEMS supports 256 priority levels ranging from 0 to 255 so
246the default value for this field is 255.
247
248@findex CONFIGURE_MICROSECONDS_PER_TICK
249@fnindex CONFIGURE_MINIMUM_STACK_SIZE
250@item @code{CONFIGURE_MINIMUM_STACK_SIZE} is set to the number of bytes
251the application wants the minimum stack size to be for every task or
252thread in the system.  By default, this is set to the recommended minimum
253stack size for this processor.
254
255@fnindex CONFIGURE_INTERRUPT_STACK_SIZE
256@item @code{CONFIGURE_INTERRUPT_STACK_SIZE} is set to the
257size of the interrupt stack.  The interrupt stack size is
258usually set by the BSP but since this memory may be allocated
259from the RTEMS Ram Workspace, it must be accounted for.  The
260default for this field is the configured minimum stack size.  [NOTE:
261In some BSPs, changing this constant does NOT change the
262size of the interrupt stack, only the amount of memory
263reserved for it.] If not specified, the interrupt stack
264will be of minimum size.  The default value is the configured
265minimum stack size.
266
267@findex CONFIGURE_TASK_STACK_ALLOCATOR
268@item @code{CONFIGURE_TASK_STACK_ALLOCATOR}
269may point to a user provided routine to allocate task stacks.
270The default value for this field is NULL which indicates that
271task stacks will be allocated from the RTEMS Workspace.
272
273@findex CONFIGURE_TASK_STACK_DEALLOCATOR
274@item @code{CONFIGURE_TASK_STACK_DEALLOCATOR}
275may point to a user provided routine to free task stacks.
276The default value for this field is NULL which indicates that
277task stacks will be allocated from the RTEMS Workspace.
278
279@findex CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY
280@item @code{CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY}
281indicates whether RTEMS should zero the RTEMS Workspace and
282C Program Heap as part of its initialization.  If set to
283TRUE, the Workspace is zeroed.  Otherwise, it is not.
284Unless overridden by the BSP, the default value for this
285field is FALSE.
286
287@findex CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE
288@item @code{CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE} is a helper macro
289which is used to assist in computing the total amount of memory
290required for message buffers.  Each message queue will have its
291own configuration with maximum message size and maximum number of
292pending messages.  The interface for this macro is as follows:
293
294@example
295CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)
296@end example
297
298Where @code{max_messages} is the maximum number of pending messages
299and @code{size_per} is the size in bytes of the user message.
300
301@findex CONFIGURE_MESSAGE_BUFFER_MEMORY
302@item @code{CONFIGURE_MESSAGE_BUFFER_MEMORY} is set to the number of
303bytes the application requires to be reserved for pending message queue
304buffers.  This value should include memory for all buffers across
305all APIs.  The default value is 0.
306
307The following illustrates how the help macro
308@code{CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE} can be used to assist in
309calculating the message buffer memory required.  In this example, there
310are two message queues used in this application.  The first message
311queue has maximum of 24 pending messages with the message structure
312defined by the type @code{one_message_type}.  The other message queue
313has maximum of 500 pending messages with the message structure defined
314by the type @code{other_message_type}.
315
316@example
317
318#define CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE \
319 (CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \
320    24, sizeof(one_message_type) + \
321  CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \
322    500, sizeof(other_message_type) \
323 )
324@end example
325
326@findex CONFIGURE_MEMORY_OVERHEAD
327@item @code{CONFIGURE_MEMORY_OVERHEAD} is set to the number of
328kilobytes the application wishes to add to the requirements calculated
329by @code{rtems/confdefs.h}.  The default value is 0.
330
331@findex CONFIGURE_EXTRA_TASK_STACKS
332@item @code{CONFIGURE_EXTRA_TASK_STACKS} is set to the number of
333bytes the applications wishes to add to the task stack requirements
334calculated by @code{rtems/confdefs.h}.  This parameter is very important.
335If the application creates tasks with stacks larger then the
336minimum, then that memory is NOT accounted for by @code{rtems/confdefs.h}.
337The default value is 0.
338
339@end itemize
340
341NOTE: The required size of the Executive RAM Work Area is calculated
342automatically when using the @code{rtems/confdefs.h} mechanism.
343
344@c
345@c
346@c
347@subsection Idle Task Configuration
348
349This section defines the IDLE task related configuration parameters
350supported by @code{rtems/confdefs.h}.
351
352@itemize @bullet
353
354@fnindex CONFIGURE_IDLE_TASK_BODY
355@item @code{CONFIGURE_IDLE_TASK_BODY} is set to the method name
356corresponding to the application specific IDLE thread body.  If
357not specified, the BSP or RTEMS default IDLE thread body will
358be used.  The default value is NULL.
359
360@fnindex CONFIGURE_IDLE_TASK_STACK_SIZE
361@item @code{CONFIGURE_IDLE_TASK_STACK_SIZE} is set to the
362desired stack size for the IDLE task.  If not specified,
363the IDLE task will have a stack of minimum size.  The default
364value is the configured minimum stack size.
365
366@fnindex CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION
367@item @code{CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION} is set to
368indicate that the user has configured @b{NO} user initialization tasks
369or threads and that the user provided IDLE task will perform application
370initialization and then transform itself into an IDLE task.  If you
371use this option be careful, the user IDLE task @b{CANNOT} block at
372all during the initialization sequence.  Further, once application
373initialization is complete, it must make itself preemptible and
374enter an IDLE body loop.  By default, this is not the mode of operation
375and the user is assumed to provide one or more initialization tasks.
376
377@end itemize
378
379@c
380@c
381@c
382@subsection Device Driver Table
383
384This section defines the configuration parameters related
385to the automatic generation of a Device Driver Table.  As
386@code{rtems/confdefs.h} only is aware of a small set of
387standard device drivers, the generated Device Driver
388Table is suitable for simple applications with no
389custom device drivers.
390
391@itemize @bullet
392@findex CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE
393@item @code{CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE} is defined if
394the application wishes to provide their own Device Driver Table.
395The table generated is an array of @code{rtems_driver_address_table}
396entries named @code{Device_drivers}.  By default, this is not
397defined indicating the @code{rtems/confdefs.h} is providing the
398device driver table.
399
400@findex CONFIGURE_MAXIMUM_DRIVERS
401@item @code{CONFIGURE_MAXIMUM_DRIVERS} is defined
402as the number of device drivers per node.  By default, this is
403set to 10.
404
405@findex CONFIGURE_MAXIMUM_DEVICES
406@item @code{CONFIGURE_MAXIMUM_DEVICES} is defined
407to the number of individual devices that may be registered
408in the system.  By default, this is set to 20.
409
410@findex CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
411@item @code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER}
412is defined
413if the application wishes to include the Console Device Driver.
414This device driver is responsible for providing standard input
415and output using "/dev/console".  By default, this is not
416defined.
417
418@findex CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
419@item @code{CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER}
420is defined
421if the application wishes to include the Clock Device Driver.
422This device driver is responsible for providing a regular
423interrupt which invokes the @code{rtems_clock_tick} directive.
424By default, this is not defined.
425
426@findex CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
427@item @code{CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER}
428is defined if the application wishes to include the Timer Driver.
429This device driver is used to benchmark execution times
430by the RTEMS Timing Test Suites.  By default, this is not
431defined.
432
433@findex CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
434@item @code{CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER} is defined
435when the application does @b{NOT} want the Clock Device Driver
436and is @b{NOT} using the Timer Driver.  The inclusion or
437exclusion of the Clock Driver must be explicit in typical
438user applications.  This is intended to prevent the common
439user error of using the Hello World example as the baseline
440for an application and leaving out a clock tick source.
441
442@findex CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER
443@item @code{CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER}
444is defined if the application wishes to include the Real-Time Clock Driver.
445By default, this is not defined.
446
447@findex CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER
448@item @code{CONFIGURE_APPLICATION_NEEDS_WATCHDOG_DRIVER}
449is defined if the application wishes to include the Watchdog Driver.
450By default, this is not defined.
451
452@findex CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER
453@item @code{CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER}
454is defined if the application wishes to include the Stub Device Driver.
455This device driver simply provides entry points that return
456successful and is primarily a test fixture.
457By default, this is not defined.
458
459@findex CONFIGURE_BSP_PREREQUISITE_DRIVERS
460@item @code{CONFIGURE_BSP_PREREQUISITE_DRIVERS} is defined if the
461BSP has device drivers it needs to include in the Device Driver
462Table.  This should be defined to the set of device driver entries that
463will be placed in the table at the @b{FRONT} of the Device Driver Table
464and initialized before any other drivers @b{INCLUDING} any application
465prerequisite drivers.  By default,this is not defined.
466
467@findex CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS
468@item @code{CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS} is defined if the
469application has device drivers it needs to include in the Device Driver
470Table.  This should be defined to the set of device driver entries that
471will be placed in the table at the @b{FRONT} of the Device Driver Table
472and initialized before any other drivers @b{EXCEPT} any BSP prerequisite
473drivers.  By default,this is not defined.
474
475@findex CONFIGURE_APPLICATION_EXTRA_DRIVERS
476@item @code{CONFIGURE_APPLICATION_EXTRA_DRIVERS} is defined if the
477application has device drivers it needs to include in the Device Driver
478Table.  This should be defined to the set of device driver entries that
479will be placed in the table at the @b{END} of the Device Driver Table.
480By default,this is not defined.
481
482@end itemize
483
484@subsection Multiprocessing Configuration
485
486This section defines the multiprocessing related
487system configuration parameters supported by @code{rtems/confdefs.h}.
488This class of Configuration Constants are only applicable if
489@code{CONFIGURE_MP_APPLICATION} is defined.
490
491@itemize @bullet
492@findex CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE
493@item @code{CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE} is defined
494if the application wishes to provide their own Multiprocessing
495Configuration Table.  The generated table is named
496@code{Multiprocessing_configuration}.  By default, this
497is not defined.
498
499@findex CONFIGURE_MP_NODE_NUMBER
500@item @code{CONFIGURE_MP_NODE_NUMBER} is the node number of
501this node in a multiprocessor system.  The default node number
502is @code{NODE_NUMBER} which is set directly in RTEMS test Makefiles.
503
504@findex CONFIGURE_MP_MAXIMUM_NODES
505@item @code{CONFIGURE_MP_MAXIMUM_NODES} is the maximum number
506of nodes in a multiprocessor system.  The default is 2.
507
508@findex CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS
509@item @code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS}
510is the maximum number
511of concurrently active global objects in a multiprocessor
512system.  The default is 32.
513
514@findex CONFIGURE_MP_MAXIMUM_PROXIES
515@item @code{CONFIGURE_MP_MAXIMUM_PROXIES} is the maximum number
516of concurrently active thread/task proxies in a multiprocessor
517system.  The default is 32.
518
519@findex CONFIGURE_MP_MPCI_TABLE_POINTER
520@item @code{CONFIGURE_MP_MPCI_TABLE_POINTER} is the pointer
521to the MPCI Configuration Table.  The default value of
522this field is @code{&MPCI_table}.
523@end itemize
524
525@subsection Classic API Configuration
526
527This section defines the Classic API related
528system configuration parameters supported by @code{rtems/confdefs.h}.
529
530@itemize @bullet
531@findex CONFIGURE_MAXIMUM_TASKS
532@item @code{CONFIGURE_MAXIMUM_TASKS} is the maximum number of
533Classic API tasks that can be concurrently active.
534The default for this field is 0.
535
536@findex CONFIGURE_DISABLE_CLASSIC_NOTEPADS
537@item @code{CONFIGURE_DISABLE_CLASSIC_NOTEPADS} should be defined
538if the user does not want to have support for Classic API Notepads
539in their application.  By default, this is not defined and Classic API
540Notepads are supported.
541
542@findex CONFIGURE_MAXIMUM_TIMERS
543@item @code{CONFIGURE_MAXIMUM_TIMERS} is the maximum number of
544Classic API timers that can be concurrently active.
545The default for this field is 0.
546
547@findex CONFIGURE_MAXIMUM_SEMAPHORES
548@item @code{CONFIGURE_MAXIMUM_SEMAPHORES} is the maximum number of
549Classic API semaphores that can be concurrently active.
550The default for this field is 0.
551
552@findex CONFIGURE_MAXIMUM_MESSAGE_QUEUES
553@item @code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES} is the maximum number of
554Classic API message queues that can be concurrently active.
555The default for this field is 0.
556
557@findex CONFIGURE_MAXIMUM_PARTITIONS
558@item @code{CONFIGURE_MAXIMUM_PARTITIONS} is the maximum number of
559Classic API partitions that can be concurrently active.
560The default for this field is 0.
561
562@findex CONFIGURE_MAXIMUM_REGIONS
563@item @code{CONFIGURE_MAXIMUM_REGIONS} is the maximum number of
564Classic API regions that can be concurrently active.
565The default for this field is 0.
566
567@findex CONFIGURE_MAXIMUM_PORTS
568@item @code{CONFIGURE_MAXIMUM_PORTS} is the maximum number of
569Classic API ports that can be concurrently active.
570The default for this field is 0.
571
572@findex CONFIGURE_MAXIMUM_PERIODS
573@item @code{CONFIGURE_MAXIMUM_PERIODS} is the maximum number of
574Classic API rate monotonic periods that can be concurrently active.
575The default for this field is 0.
576
577@findex CONFIGURE_MAXIMUM_USER_EXTENSIONS
578@item @code{CONFIGURE_MAXIMUM_USER_EXTENSIONS} is the maximum number of
579Classic API user extensions that can be concurrently active.
580The default for this field is 0.
581
582@end itemize
583
584@subsection Classic API Initialization Tasks Table Configuration
585
586The @code{rtems/confdefs.h} configuration system can automatically
587generate an Initialization Tasks Table named
588@code{Initialization_tasks} with a single entry.  The following
589parameters control the generation of that table.
590
591@itemize @bullet
592@findex CONFIGURE_RTEMS_INIT_TASKS_TABLE
593@item @code{CONFIGURE_RTEMS_INIT_TASKS_TABLE} is defined
594if the user wishes to use a Classic RTEMS API Initialization
595Task Table.  The application may choose to use the initialization
596tasks or threads table from another API.  By default, this
597field is not defined as the user MUST select their own
598API for initialization tasks.
599
600@findex CONFIGURE_HAS_OWN_INIT_TASK_TABLE
601@item @code{CONFIGURE_HAS_OWN_INIT_TASK_TABLE} is defined
602if the user wishes to define their own Classic API Initialization
603Tasks Table.  This table should be named @code{Initialization_tasks}.
604By default, this is not defined.
605
606@findex CONFIGURE_INIT_TASK_NAME
607@item @code{CONFIGURE_INIT_TASK_NAME} is the name
608of the single initialization task defined by the
609Classic API Initialization Tasks Table.  By default
610the value is @code{rtems_build_name( 'U', 'I', '1', ' ' )}.
611
612@findex CONFIGURE_INIT_TASK_STACK_SIZE
613@item @code{CONFIGURE_INIT_TASK_STACK_SIZE}
614is the stack size
615of the single initialization task defined by the
616Classic API Initialization Tasks Table.  By default
617value is the configured minimum stack size.
618
619@findex CONFIGURE_INIT_TASK_PRIORITY
620@item @code{CONFIGURE_INIT_TASK_PRIORITY}
621is the initial priority
622of the single initialization task defined by the
623Classic API Initialization Tasks Table.  By default
624the value is 1 which is the highest priority
625in the Classic API.
626
627@findex CONFIGURE_INIT_TASK_ATTRIBUTES
628@item @code{CONFIGURE_INIT_TASK_ATTRIBUTES}
629is the task attributes
630of the single initialization task defined by the
631Classic API Initialization Tasks Table.  By default
632the value is @code{RTEMS_DEFAULT_ATTRIBUTES}.
633
634@findex CONFIGURE_INIT_TASK_ENTRY_POINT
635@item @code{CONFIGURE_INIT_TASK_ENTRY_POINT}
636is the entry point (a.k.a. function name)
637of the single initialization task defined by the
638Classic API Initialization Tasks Table.  By default
639the value is @code{Init}.
640
641@findex CONFIGURE_INIT_TASK_INITIAL_MODES
642@item @code{CONFIGURE_INIT_TASK_INITIAL_MODES}
643is the initial execution mode
644of the single initialization task defined by the
645Classic API Initialization Tasks Table.  By default
646the value is @code{RTEMS_NO_PREEMPT}.
647
648@findex CONFIGURE_INIT_TASK_ARGUMENTS
649@item @code{CONFIGURE_INIT_TASK_ARGUMENTS}
650is the task argument
651of the single initialization task defined by the
652Classic API Initialization Tasks Table.  By default
653the value is 0.
654
655@end itemize
656
657
658@subsection POSIX API Configuration
659
660The parameters in this section are used to configure resources
661for the RTEMS POSIX API.  They are only relevant if the POSIX API
662is enabled at configure time using the @code{--enable-posix} option.
663
664@itemize @bullet
665@findex CONFIGURE_MAXIMUM_POSIX_THREADS
666@item @code{CONFIGURE_MAXIMUM_POSIX_THREADS} is the maximum number of
667POSIX API threads that can be concurrently active.
668The default is 0.
669
670@findex CONFIGURE_MAXIMUM_POSIX_MUTEXES
671@item @code{CONFIGURE_MAXIMUM_POSIX_MUTEXES} is the maximum number of
672POSIX API mutexes that can be concurrently active.
673The default is 0.
674
675@findex CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES
676@item @code{CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES} is the maximum number of
677POSIX API condition variables that can be concurrently active.
678The default is 0.
679
680@findex CONFIGURE_MAXIMUM_POSIX_KEYS
681@item @code{CONFIGURE_MAXIMUM_POSIX_KEYS} is the maximum number of
682POSIX API keys that can be concurrently active.
683The default is 0.
684
685@findex CONFIGURE_MAXIMUM_POSIX_TIMERS
686@item @code{CONFIGURE_MAXIMUM_POSIX_TIMERS} is the maximum number of
687POSIX API timers that can be concurrently active.
688The default is 0.
689
690@findex CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS
691@item @code{CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS} is the maximum number of
692POSIX API queued signals that can be concurrently active.
693The default is 0.
694
695@findex CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES
696@item @code{CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES} is the maximum number of
697POSIX API message queues that can be concurrently active.
698The default is 0.
699
700@findex CONFIGURE_MAXIMUM_POSIX_SEMAPHORES
701@item @code{CONFIGURE_MAXIMUM_POSIX_SEMAPHORES} is the maximum number of
702POSIX API semaphores that can be concurrently active.
703The default is 0.
704
705@end itemize
706
707@subsection POSIX Initialization Threads Table Configuration
708
709The @code{rtems/confdefs.h} configuration system can automatically
710generate a POSIX Initialization Threads Table named
711@code{POSIX_Initialization_threads} with a single entry.  The following
712parameters control the generation of that table.
713
714@itemize @bullet
715@findex CONFIGURE_POSIX_INIT_THREAD_TABLE
716@item @code{CONFIGURE_POSIX_INIT_THREAD_TABLE}
717is defined
718if the user wishes to use a POSIX API Initialization
719Threads Table.  The application may choose to use the initialization
720tasks or threads table from another API.  By default, this
721field is not defined as the user MUST select their own
722API for initialization tasks.
723
724@findex CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE
725@item @code{CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE}
726is defined if the user wishes to define their own POSIX API Initialization
727Threads Table.  This table should be named @code{POSIX_Initialization_threads}.
728By default, this is not defined.
729
730@findex CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT
731@item @code{CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT}
732is the entry point (a.k.a. function name)
733of the single initialization thread defined by the
734POSIX API Initialization Threads Table.  By default
735the value is @code{POSIX_Init}.
736
737@findex CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE
738@item @code{CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE}
739is the stack size of the single initialization thread defined by the
740POSIX API Initialization Threads Table.  By default
741value is twice the configured minimum stack size.
742
743@end itemize
744
745@subsection ITRON API Configuration
746
747The parameters in this section are used to configure resources
748for the RTEMS ITRON API.  They are only relevant if the POSIX API
749is enabled at configure time using the @code{--enable-itron} option.
750
751@itemize @bullet
752@findex CONFIGURE_MAXIMUM_ITRON_TASKS
753@item @code{CONFIGURE_MAXIMUM_ITRON_TASKS}
754is the maximum number of
755ITRON API tasks that can be concurrently active.
756The default is 0.
757
758@findex CONFIGURE_MAXIMUM_ITRON_SEMAPHORES
759@item @code{CONFIGURE_MAXIMUM_ITRON_SEMAPHORES}
760is the maximum number of
761ITRON API semaphores that can be concurrently active.
762The default is 0.
763
764@findex CONFIGURE_MAXIMUM_ITRON_EVENTFLAGS
765@item @code{CONFIGURE_MAXIMUM_ITRON_EVENTFLAGS}
766is the maximum number of
767ITRON API eventflags that can be concurrently active.
768The default is 0.
769
770@findex CONFIGURE_MAXIMUM_ITRON_MAILBOXES
771@item @code{CONFIGURE_MAXIMUM_ITRON_MAILBOXES}
772is the maximum number of
773ITRON API mailboxes that can be concurrently active.
774The default is 0.
775
776@findex CONFIGURE_MAXIMUM_ITRON_MESSAGE_BUFFERS
777@item @code{CONFIGURE_MAXIMUM_ITRON_MESSAGE_BUFFERS}
778is the maximum number of
779ITRON API message buffers that can be concurrently active.
780The default is 0.
781
782@findex CONFIGURE_MAXIMUM_ITRON_PORTS
783@item @code{CONFIGURE_MAXIMUM_ITRON_PORTS}
784is the maximum number of
785ITRON API ports that can be concurrently active.
786The default is 0.
787
788@findex CONFIGURE_MAXIMUM_ITRON_MEMORY_POOLS
789@item @code{CONFIGURE_MAXIMUM_ITRON_MEMORY_POOLS}
790is the maximum number of
791ITRON API memory pools that can be concurrently active.
792The default is 0.
793
794@findex CONFIGURE_MAXIMUM_ITRON_FIXED_MEMORY_POOLS
795@item @code{CONFIGURE_MAXIMUM_ITRON_FIXED_MEMORY_POOLS}
796is the maximum number of
797ITRON API fixed memory pools that can be concurrently active.
798The default is 0.
799
800@end itemize
801
802@subsection ITRON Initialization Task Table Configuration
803
804The @code{rtems/confdefs.h} configuration system can automatically
805generate an ITRON Initialization Tasks Table named
806@code{ITRON_Initialization_tasks} with a single entry.  The following
807parameters control the generation of that table.
808
809@itemize @bullet
810@findex CONFIGURE_ITRON_INIT_TASK_TABLE
811@item @code{CONFIGURE_ITRON_INIT_TASK_TABLE} is defined
812if the user wishes to use a ITRON API Initialization
813Tasks Table.  The application may choose to use the initialization
814tasks or threads table from another API.  By default, this
815field is not defined as the user MUST select their own
816API for initialization tasks.
817
818@findex CONFIGURE_ITRON_HAS_OWN_INIT_TASK_TABLE
819@item @code{CONFIGURE_ITRON_HAS_OWN_INIT_TASK_TABLE}
820is defined if the user wishes to define their own ITRON API Initialization
821Tasks Table.  This table should be named @code{ITRON_Initialization_tasks}.
822By default, this is not defined.
823
824@findex CONFIGURE_ITRON_INIT_TASK_ENTRY_POINT
825@item @code{CONFIGURE_ITRON_INIT_TASK_ENTRY_POINT}
826is the entry point (a.k.a. function name)
827of the single initialization task defined by the
828ITRON API Initialization Tasks Table.  By default
829the value is @code{ITRON_Init}.
830
831@findex CONFIGURE_ITRON_INIT_TASK_ATTRIBUTES
832@item @code{CONFIGURE_ITRON_INIT_TASK_ATTRIBUTES}
833is the attribute set
834of the single initialization task defined by the
835ITRON API Initialization Tasks Table.  By default
836the value is @code{TA_HLNG}.
837
838@findex CONFIGURE_ITRON_INIT_TASK_PRIORITY
839@item @code{CONFIGURE_ITRON_INIT_TASK_PRIORITY}
840is the initial priority
841of the single initialization task defined by the
842ITRON API Initialization Tasks Table.  By default
843the value is @code{1} which is the highest priority
844in the ITRON API.
845
846@findex CONFIGURE_ITRON_INIT_TASK_STACK_SIZE
847@item @code{CONFIGURE_ITRON_INIT_TASK_STACK_SIZE}
848is the stack size of the single initialization task defined by the
849ITRON API Initialization Tasks Table.  By default
850value is the configured minimum stack size.
851
852@end itemize
853
854@subsection Ada Tasks
855
856This section defines the system configuration parameters supported
857by @code{rtems/confdefs.h} related to configuring RTEMS to support
858a task using Ada tasking with GNAT.
859
860@itemize @bullet
861@findex CONFIGURE_GNAT_RTEMS
862@item @code{CONFIGURE_GNAT_RTEMS} is defined to inform
863RTEMS that the GNAT Ada run-time is to be used by the
864application.  This configuration parameter is critical
865as it makes @code{rtems/confdefs.h} configure the resources
866(mutexes and keys) used implicitly by the GNAT run-time.
867By default, this parameter is not defined.
868
869@findex CONFIGURE_MAXIMUM_ADA_TASKS
870@item @code{CONFIGURE_MAXIMUM_ADA_TASKS} is the
871number of Ada tasks that can be concurrently active
872in the system.  By default, when @code{CONFIGURE_GNAT_RTEMS}
873is defined, this is set to 20.
874
875@findex CONFIGURE_MAXIMUM_FAKE_ADA_TASKS
876@item @code{CONFIGURE_MAXIMUM_FAKE_ADA_TASKS} is
877the number of "fake" Ada tasks that can be concurrently
878active in the system.  A "fake" Ada task is a non-Ada
879task that makes calls back into Ada code and thus
880implicitly uses the Ada run-time.
881
882@end itemize
883
884@section Configuration Table
885
886@cindex Configuration Table
887@cindex RTEMS Configuration Table
888
889The RTEMS Configuration Table is used to tailor an
890application for its specific needs.  For example, the user can
891configure the number of device drivers or which APIs may be used.
892THe address of the user-defined Configuration Table is passed as an
893argument to the @code{rtems_initialize_executive}
894directive, which MUST be the first RTEMS directive called. 
895The RTEMS Configuration Table is defined in the following C structure:
896
897@findex rtems_configuration_table
898@example
899@group
900typedef struct @{
901  void                           *work_space_start;
902  uint32_t                        work_space_size;
903  uint32_t                        maximum_extensions;
904  uint32_t                        microseconds_per_tick;
905  uint32_t                        ticks_per_timeslice;
906  void                          (*idle_task)( void );
907  uint32_t                        idle_task_stack_size;
908  uint32_t                        interrupt_stack_size;
909  void *                        (*stack_allocate_hook)( uint32_t );
910  void                          (*stack_free_hook)( void * );
911  bool                            do_zero_of_workspace;
912  uint32_t                        maximum_drivers;
913  uint32_t                        number_of_device_drivers;
914  rtems_driver_address_table     *Device_driver_table;
915  uint32_t                        number_of_initial_extensions;
916  rtems_extensions_table         *User_extension_table;
917#if defined(RTEMS_MULTIPROCESSING)
918  rtems_multiprocessing_table    *User_multiprocessing_table;
919#endif
920  rtems_api_configuration_table  *RTEMS_api_configuration;
921  posix_api_configuration_table  *POSIX_api_configuration;
922  itron_api_configuration        *ITRON_api_configuration;
923@} rtems_configuration_table;
924@end group
925@end example
926
927@table @b
928@item work_space_start
929is the address of the RTEMS RAM Workspace. 
930This area contains items such as the
931various object control blocks (TCBs, QCBs, ...) and task stacks.
932If the address is not aligned on a four-word boundary, then
933RTEMS will invoke the fatal error handler during
934@code{rtems_initialize_executive}.
935When using the @code{rtems/confdefs.h} mechanism for configuring
936an RTEMS application, the value for this field corresponds
937to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA}
938which defaults to @code{NULL}.  Normally, this field should be
939configured as @code{NULL} as BSPs will assign memory for the
940RTEMS RAM Workspace as part of system initialization.
941
942@item work_space_size
943is the calculated size of the
944RTEMS RAM Workspace.  The section Sizing the RTEMS RAM Workspace
945details how to arrive at this number.
946When using the @code{rtems/confdefs.h} mechanism for configuring
947an RTEMS application, the value for this field corresponds
948to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_SIZE}
949and is calculated based on the other system configuration settings.
950
951@item microseconds_per_tick
952is number of microseconds per clock tick.
953When using the @code{rtems/confdefs.h} mechanism for configuring
954an RTEMS application, the value for this field corresponds
955to the setting of the macro @code{CONFIGURE_MICROSECONDS_PER_TICK}.
956If not defined by the application, then the
957@code{CONFIGURE_MICROSECONDS_PER_TICK} macro defaults to 10000
958(10 milliseconds).
959
960@item ticks_per_timeslice
961is the number of clock ticks for a timeslice.
962When using the @code{rtems/confdefs.h} mechanism for configuring
963an RTEMS application, the value for this field corresponds
964to the setting of the macro @code{CONFIGURE_TICKS_PER_TIMESLICE}.
965
966@item idle_task
967is the address of the optional user
968provided routine which is used as the system's IDLE task.  If
969this field is not NULL, then the RTEMS default IDLE task is not
970used.  This field may be NULL to indicate that the default IDLE
971is to be used.  When using the @code{rtems/confdefs.h} mechanism
972for configuring an RTEMS application, the value for this field
973corresponds to the setting of the macro @code{CONFIGURE_IDLE_TASK_BODY}.
974
975@item idle_task_stack_size
976is the size of the RTEMS idle task stack in bytes.  If this number is less
977than the configured minimum stack size, then the idle task's stack will
978be set to the minimum.  When using the @code{rtems/confdefs.h} mechanism
979for configuring an RTEMS application, the value for this field corresponds
980to the setting of the macro @code{CONFIGURE_IDLE_TASK_STACK_SIZE}.
981
982@item interrupt_stack_size
983is the size of the RTEMS interrupt stack in bytes.  If this number is less
984than configured minimum stack size, then the interrupt stack will be set
985to the minimum.  When using the @code{rtems/confdefs.h} mechanism for
986configuring an RTEMS application, the value for this field corresponds
987to the setting of the macro @code{CONFIGURE_INTERRUPT_STACK_SIZE}.
988
989@item stack_allocate_hook
990may point to a user provided routine to allocate task stacks.
991The default is to allocate task stacks from the RTEMS Workspace.
992When using the @code{rtems/confdefs.h} mechanism
993for configuring an RTEMS application, the value for this field
994corresponds to the setting of the macro
995@code{CONFIGURE_TASK_STACK_ALLOCATOR}.
996
997@item stack_free_hook
998may point to a user provided routine to free task stacks.
999The default is to allocate task stacks from the RTEMS Workspace.
1000When using the @code{rtems/confdefs.h} mechanism
1001for configuring an RTEMS application, the value for this field
1002corresponds to the setting of the macro
1003@code{CONFIGURE_TASK_STACK_DEALLOCATOR}.
1004
1005@item do_zero_of_workspace
1006indicates whether RTEMS should zero the RTEMS Workspace and
1007C Program Heap as part of its initialization.  If set to
1008TRUE, the Workspace is zeroed.  Otherwise, it is not.
1009When using the @code{rtems/confdefs.h} mechanism
1010for configuring an RTEMS application, the value for this field
1011corresponds to the setting of the macro
1012@code{CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY}.
1013
1014@item maximum_drivers
1015is the maximum number of device drivers that can be registered.
1016When using the @code{rtems/confdefs.h} mechanism for configuring
1017an RTEMS application, the value for this field corresponds
1018to the setting of the macro @code{CONFIGURE_MAXIMUM_DRIVERS}.
1019
1020@item number_of_device_drivers
1021is the number of device drivers for the system.  There should be
1022the same number of entries in the Device Driver Table.  If this field
1023is zero, then the @code{User_driver_address_table} entry should be NULL.
1024When using the @code{rtems/confdefs.h} mechanism for configuring
1025an RTEMS application, the value for this field is calculated
1026automatically based on the number of entries in the
1027Device Driver Table.  This calculation is based on the assumption
1028that the Device Driver Table is named @code{Device_drivers}
1029and defined in C.  This table may be generated automatically
1030for simple applications using only the device drivers that correspond
1031to the following macros:
1032
1033@itemize @bullet
1034
1035@item @code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER}
1036@item @code{CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER}
1037@item @code{CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER}
1038@item @code{CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER}
1039@item @code{CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER}
1040
1041@end itemize
1042
1043Note that network device drivers are not configured in the
1044Device Driver Table.
1045
1046@item Device_driver_table
1047is the address of the Device Driver Table.  This table contains the entry
1048points for each device driver.  If the number_of_device_drivers field is zero,
1049then this entry should be NULL. The format of this table will be
1050discussed below.
1051When using the @code{rtems/confdefs.h} mechanism for configuring
1052an RTEMS application, the Device Driver Table is assumed to be
1053named @code{Device_drivers} and defined in C.  If the application is providing
1054its own Device Driver Table, then the macro
1055@code{CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE} must be defined to indicate
1056this and prevent @code{rtems/confdefs.h} from generating the table.
1057
1058@item number_of_initial_extensions
1059is the number of initial user extensions.  There should be
1060the same number of entries as in the User_extension_table.  If this field
1061is zero, then the User_driver_address_table entry should be NULL.
1062When using the @code{rtems/confdefs.h} mechanism for configuring
1063an RTEMS application, the value for this field corresponds
1064to the setting of the macro @code{CONFIGURE_NUMBER_OF_INITIAL_EXTENSIONS}
1065which is set automatically by @code{rtems/confdefs.h} based on the size
1066of the User Extensions Table.
1067
1068@item User_extension_table
1069is the address of the User
1070Extension Table.  This table contains the entry points for the
1071static set of optional user extensions.  If no user extensions
1072are configured, then this entry should be NULL.  The format of
1073this table will be discussed below.
1074When using the @code{rtems/confdefs.h} mechanism for configuring
1075an RTEMS application, the User Extensions Table is named
1076@code{Configuration_Initial_Extensions} and defined in
1077confdefs.h.  It is initialized based on the following
1078macros:
1079
1080@itemize @bullet
1081
1082@item @code{CONFIGURE_INITIAL_EXTENSIONS}
1083@item @code{STACK_CHECKER_EXTENSION}
1084
1085@end itemize
1086
1087The application may configure one or more initial user extension
1088sets by setting the @code{CONFIGURE_INITIAL_EXTENSIONS} macro.  By
1089defining the @code{STACK_CHECKER_EXTENSION} macro, the task stack bounds
1090checking user extension set is automatically included in the
1091application.
1092
1093@item User_multiprocessing_table
1094is the address of the Multiprocessor Configuration Table.  This
1095table contains information needed by RTEMS only when used in a multiprocessor
1096configuration.  This field must be NULL when RTEMS is used in a
1097single processor configuration.
1098When using the @code{rtems/confdefs.h} mechanism for configuring
1099an RTEMS application, the Multiprocessor Configuration Table
1100is automatically generated when the @code{CONFIGURE_MP_APPLICATION}
1101is defined.  If @code{CONFIGURE_MP_APPLICATION} is not defined, the this
1102entry is set to NULL.  The generated table has the name
1103@code{Multiprocessing_configuration}.
1104
1105@item RTEMS_api_configuration
1106is the address of the RTEMS API Configuration Table.  This table
1107contains information needed by the RTEMS API.  This field should be
1108NULL if the RTEMS API is not used.  [NOTE: Currently the RTEMS API
1109is required to support support components such as BSPs and libraries
1110which use this API.]  This table is built automatically and this
1111entry filled in, if using the @code{rtems/confdefs.h} application
1112configuration mechanism.  The generated table has the name
1113@code{Configuration_RTEMS_API}.
1114
1115@item POSIX_api_configuration
1116is the address of the POSIX API Configuration Table.  This table
1117contains information needed by the POSIX API.  This field should be
1118NULL if the POSIX API is not used.  This table is built automatically
1119and this entry filled in, if using the @code{rtems/confdefs.h} application
1120configuration mechanism.  The @code{rtems/confdefs.h} application
1121mechanism will fill this field in with the address of the
1122@code{Configuration_POSIX_API} table of POSIX API is configured
1123and NULL if the POSIX API is not configured.
1124
1125@end table
1126
1127@section RTEMS API Configuration Table
1128
1129@cindex RTEMS API Configuration Table
1130
1131The RTEMS API Configuration Table is used to configure the
1132managers which constitute the RTEMS API for a particular application. 
1133For example, the user can configure the maximum number of tasks for
1134this application. The RTEMS API Configuration Table is defined in
1135the following C structure:
1136
1137@findex rtems_api_configuration_table
1138@example
1139@group
1140typedef struct @{
1141  uint32_t  maximum_tasks;
1142  uint32_t  maximum_timers;
1143  uint32_t  maximum_semaphores;
1144  uint32_t  maximum_message_queues;
1145  uint32_t  maximum_partitions;
1146  uint32_t  maximum_regions;
1147  uint32_t  maximum_ports;
1148  uint32_t  maximum_periods;
1149  uint32_t  maximum_barriers;
1150  uint32_t  number_of_initialization_tasks;
1151  rtems_initialization_tasks_table *User_initialization_tasks_table;
1152@} rtems_api_configuration_table;
1153@end group
1154@end example
1155
1156@table @b
1157@item maximum_tasks
1158is the maximum number of tasks that
1159can be concurrently active (created) in the system including
1160initialization tasks.
1161When using the @code{rtems/confdefs.h} mechanism for configuring
1162an RTEMS application, the value for this field corresponds
1163to the setting of the macro @code{CONFIGURE_MAXIMUM_TASKS}.
1164If not defined by the application, then the @code{CONFIGURE_MAXIMUM_TASKS}
1165macro defaults to 0.
1166
1167@item maximum_timers
1168is the maximum number of timers
1169that can be concurrently active in the system.
1170When using the @code{rtems/confdefs.h} mechanism for configuring
1171an RTEMS application, the value for this field corresponds
1172to the setting of the macro @code{CONFIGURE_MAXIMUM_TIMERS}.
1173If not defined by the application, then the @code{CONFIGURE_MAXIMUM_TIMERS}
1174macro defaults to 0.
1175
1176@item maximum_semaphores
1177is the maximum number of
1178semaphores that can be concurrently active in the system.
1179When using the @code{rtems/confdefs.h} mechanism for configuring
1180an RTEMS application, the value for this field corresponds
1181to the setting of the macro @code{CONFIGURE_MAXIMUM_SEMAPHORES}.
1182If not defined by the application, then the @code{CONFIGURE_MAXIMUM_SEMAPHORES}
1183macro defaults to 0.
1184
1185@item maximum_message_queues
1186is the maximum number of
1187message queues that can be concurrently active in the system.
1188When using the @code{rtems/confdefs.h} mechanism for configuring
1189an RTEMS application, the value for this field corresponds
1190to the setting of the macro @code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES}.
1191If not defined by the application, then the
1192@code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES} macro defaults to 0.
1193
1194@item maximum_partitions
1195is the maximum number of
1196partitions that can be concurrently active in the system.
1197When using the @code{rtems/confdefs.h} mechanism for configuring
1198an RTEMS application, the value for this field corresponds
1199to the setting of the macro @code{CONFIGURE_MAXIMUM_PARTITIONS}.
1200If not defined by the application, then the @code{CONFIGURE_MAXIMUM_PARTITIONS}
1201macro defaults to 0.
1202
1203@item maximum_regions
1204is the maximum number of regions
1205that can be concurrently active in the system.
1206When using the @code{rtems/confdefs.h} mechanism for configuring
1207an RTEMS application, the value for this field corresponds
1208to the setting of the macro @code{CONFIGURE_MAXIMUM_REGIONS}.
1209If not defined by the application, then the @code{CONFIGURE_MAXIMUM_REGIONS}
1210macro defaults to 0.
1211
1212@item maximum_ports
1213is the maximum number of ports into
1214dual-port memory areas that can be concurrently active in the
1215system.
1216When using the @code{rtems/confdefs.h} mechanism for configuring
1217an RTEMS application, the value for this field corresponds
1218to the setting of the macro @code{CONFIGURE_MAXIMUM_PORTS}.
1219If not defined by the application, then the @code{CONFIGURE_MAXIMUM_PORTS}
1220macro defaults to 0.
1221
1222@item number_of_initialization_tasks
1223is the number of initialization tasks configured.  At least one
1224RTEMS initialization task or POSIX initializatin must be configured
1225in order for the user's application to begin executing.
1226When using the @code{rtems/confdefs.h} mechanism for configuring
1227an RTEMS application, the user must define the
1228@code{CONFIGURE_RTEMS_INIT_TASKS_TABLE} to indicate that there
1229is one or more RTEMS initialization task.  If the application
1230only has one RTEMS initialization task, then the automatically
1231generated Initialization Task Table will be sufficient.  The following
1232macros correspond to the single initialization task:
1233 
1234@itemize @bullet
1235
1236@item @code{CONFIGURE_INIT_TASK_NAME} - is the name of the task. 
1237If this macro is not defined by the application, then this defaults
1238to the task name of @code{"UI1 "} for User Initialization Task 1.
1239
1240@item @code{CONFIGURE_INIT_TASK_STACK_SIZE} - is the stack size
1241of the single initialization task.  If this macro is not defined
1242by the application, then this defaults to configured minimum
1243stack size.
1244
1245@item @code{CONFIGURE_INIT_TASK_PRIORITY} - is the initial priority
1246of the single initialization task.  If this macro is not defined
1247by the application, then this defaults to 1.
1248
1249@item @code{CONFIGURE_INIT_TASK_ATTRIBUTES} - is the attributes
1250of the single initialization task.  If this macro is not defined
1251by the application, then this defaults to @code{RTEMS_DEFAULT_ATTRIBUTES}.
1252
1253@item @code{CONFIGURE_INIT_TASK_ENTRY_POINT} - is the entry point
1254of the single initialization task.  If this macro is not defined
1255by the application, then this defaults to the C language routine
1256@code{Init}.
1257
1258@item @code{CONFIGURE_INIT_TASK_INITIAL_MODES} - is the initial execution
1259modes of the single initialization task.  If this macro is not defined
1260by the application, then this defaults to @code{RTEMS_NO_PREEMPT}.
1261
1262@item @code{CONFIGURE_INIT_TASK_ARGUMENTS} - is the argument passed to the
1263of the single initialization task.  If this macro is not defined
1264by the application, then this defaults to 0.
1265
1266
1267@end itemize
1268
1269
1270has the option to have
1271 value for this field corresponds
1272to the setting of the macro @code{}.
1273
1274@item User_initialization_tasks_table
1275is the address of the Initialization Task Table. This table contains the
1276information needed to create and start each of the
1277initialization tasks.  The format of this table will be discussed below.
1278When using the @code{rtems/confdefs.h} mechanism for configuring
1279an RTEMS application, the value for this field corresponds
1280to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA}.
1281
1282@end table
1283
1284@section POSIX API Configuration Table
1285
1286@cindex POSIX API Configuration Table
1287
1288The POSIX API Configuration Table is used to configure the
1289managers which constitute the POSIX API for a particular application.
1290For example, the user can configure the maximum number of threads for
1291this application. The POSIX API Configuration Table is defined in
1292the following C structure:
1293 
1294@findex posix_initialization_threads_table
1295@findex posix_api_configuration_table
1296@example
1297@group
1298typedef struct @{
1299  void       *(*thread_entry)(void *);
1300@} posix_initialization_threads_table;
1301 
1302typedef struct @{
1303  int                                 maximum_threads;
1304  int                                 maximum_mutexes;
1305  int                                 maximum_condition_variables;
1306  int                                 maximum_keys;
1307  int                                 maximum_timers;
1308  int                                 maximum_queued_signals;
1309  int                                 maximum_message_queues;
1310  int                                 maximum_semaphores;
1311  int                                 maximum_barriers;
1312  int                                 maximum_rwlocks;
1313  int                                 maximum_spinlocks;
1314  int                                 number_of_initialization_tasks;
1315  posix_initialization_threads_table *User_initialization_tasks_table;
1316@} posix_api_configuration_table;
1317@end group
1318@end example
1319 
1320@table @b
1321@item maximum_threads
1322is the maximum number of threads that
1323can be concurrently active (created) in the system including
1324initialization threads.
1325When using the @code{rtems/confdefs.h} mechanism for configuring
1326an RTEMS application, the value for this field corresponds
1327to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_THREADS}.
1328If not defined by the application, then the
1329@code{CONFIGURE_MAXIMUM_POSIX_THREADS} macro defaults to 0.
1330
1331@item maximum_mutexes
1332is the maximum number of mutexes that can be concurrently
1333active in the system.
1334When using the @code{rtems/confdefs.h} mechanism for configuring
1335an RTEMS application, the value for this field corresponds
1336to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_MUTEXES}.
1337If not defined by the application, then the
1338@code{CONFIGURE_MAXIMUM_POSIX_MUTEXES} macro defaults to 0.
1339
1340@item maximum_condition_variables
1341is the maximum number of condition variables that can be
1342concurrently active in the system.
1343When using the @code{rtems/confdefs.h} mechanism for configuring
1344an RTEMS application, the value for this field corresponds
1345to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES}.
1346If not defined by the application, then the
1347@code{CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES} macro defaults to 0.
1348
1349@item maximum_keys
1350is the maximum number of keys that can be concurrently active in the system.
1351When using the @code{rtems/confdefs.h} mechanism for configuring
1352an RTEMS application, the value for this field corresponds
1353to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_KEYS}.
1354If not defined by the application, then the
1355@code{CONFIGURE_MAXIMUM_POSIX_KEYS} macro defaults to 0.
1356
1357@item maximum_timers
1358is the maximum number of POSIX timers that can be concurrently active
1359in the system.
1360When using the @code{rtems/confdefs.h} mechanism for configuring
1361an RTEMS application, the value for this field corresponds
1362to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_TIMERS}.
1363If not defined by the application, then the
1364@code{CONFIGURE_MAXIMUM_POSIX_TIMERS} macro defaults to 0.
1365
1366@item maximum_queued_signals
1367is the maximum number of queued signals that can be concurrently
1368pending in the system.
1369When using the @code{rtems/confdefs.h} mechanism for configuring
1370an RTEMS application, the value for this field corresponds
1371to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS}.
1372If not defined by the application, then the
1373@code{CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS} macro defaults to 0.
1374
1375@item number_of_initialization_threads
1376is the number of initialization threads configured.  At least one
1377initialization threads must be configured.
1378When using the @code{rtems/confdefs.h} mechanism for configuring
1379an RTEMS application, the user must define the
1380@code{CONFIGURE_POSIX_INIT_THREAD_TABLE} to indicate that there
1381is one or more POSIX initialization thread.  If the application
1382only has one POSIX initialization thread, then the automatically
1383generated POSIX Initialization Thread Table will be sufficient.  The following
1384macros correspond to the single initialization task:
1385
1386@itemize @bullet
1387
1388@item @code{CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT} - is the entry
1389point of the thread.  If this macro is not defined by the application,
1390then this defaults to the C routine @code{POSIX_Init}.
1391
1392@item @code{CONFIGURE_POSIX_INIT_TASK_STACK_SIZE} - is the stack size
1393of the single initialization thread.  If this macro is not defined
1394by the application, then this defaults to twice the configured
1395minimum stack size.
1396
1397@end itemize
1398 
1399@item User_initialization_threads_table
1400is the address of the Initialization Threads Table. This table contains the
1401information needed to create and start each of the initialization threads. 
1402The format of each entry in this table is defined in the
1403@code{posix_initialization_threads_table} structure.
1404When using the @code{rtems/confdefs.h} mechanism for configuring
1405an RTEMS application, the value for this field corresponds
1406to the address of the @code{POSIX_Initialization_threads} structure.
1407
1408@end table
1409
1410@section CPU Dependent Information Table
1411
1412@cindex CPU Dependent Information Table
1413
1414The CPU Dependent Information Table is used to
1415describe processor dependent information required by RTEMS.
1416This table is generally used to supply RTEMS with information
1417only known by the Board Support Package.  The contents of this
1418table are discussed in the CPU Dependent Information Table
1419chapter of the Applications Supplement document for a specific
1420target processor.
1421
1422The @code{rtems/confdefs.h} mechanism does not support generating this
1423table.  It is normally filled in by the Board Support Package.
1424
1425@section Initialization Task Table
1426
1427@cindex Initialization Tasks Table
1428
1429The Initialization Task Table is used to describe
1430each of the user initialization tasks to the Initialization
1431Manager.  The table contains one entry for each initialization
1432task the user wishes to create and start.  The fields of this
1433data structure directly correspond to arguments to the
1434@code{@value{DIRPREFIX}task_create} and
1435@code{@value{DIRPREFIX}task_start} directives.  The number of entries is
1436found in the @code{number_of_initialization_tasks} entry in the
1437Configuration Table. 
1438
1439The format of each entry in the
1440Initialization Task Table is defined in the following C structure:
1441
1442@findex rtems_initialization_tasks_table
1443@example
1444typedef struct @{
1445  rtems_name           name;
1446  size_t               stack_size;
1447  rtems_task_priority  initial_priority;
1448  rtems_attribute      attribute_set;
1449  rtems_task_entry     entry_point;
1450  rtems_mode           mode_set;
1451  rtems_task_argument  argument;
1452@} rtems_initialization_tasks_table;
1453@end example
1454
1455@table @b
1456@item name
1457is the name of this initialization task.
1458
1459@item stack_size
1460is the size of the stack for this initialization task.
1461
1462@item initial_priority
1463is the priority of this initialization task.
1464
1465@item attribute_set
1466is the attribute set used during creation of this initialization task.
1467
1468@item entry_point
1469is the address of the entry point of this initialization task.
1470
1471@item mode_set
1472is the initial execution mode of this initialization task.
1473
1474@item argument
1475is the initial argument for this initialization task.
1476
1477@end table
1478
1479A typical declaration for an Initialization Task Table might appear as follows:
1480
1481@example
1482rtems_initialization_tasks_table
1483Initialization_tasks[2] = @{
1484   @{ INIT_1_NAME,
1485     1024,
1486     1,
1487     DEFAULT_ATTRIBUTES,
1488     Init_1,
1489     DEFAULT_MODES,
1490     1
1491
1492   @},
1493   @{ INIT_2_NAME,
1494     1024,
1495     250,
1496     FLOATING_POINT,
1497     Init_2,
1498     NO_PREEMPT,
1499     2
1500
1501   @}
1502@};
1503@end example
1504
1505@section Driver Address Table
1506
1507@cindex Device Driver Table
1508
1509The Device Driver Table is used to inform the I/O Manager of the set of
1510entry points for each device driver configured in the system.  The table
1511contains one entry for each device driver required by the application.
1512The number of entries is defined in the number_of_device_drivers entry
1513in the Configuration Table.  This table is copied to the Device Drive
1514Table during the IO Manager's initialization giving the entries in this
1515table the lower major numbers.  The format of each entry in the Device
1516Driver Table is defined in the following C structure:
1517
1518@findex rtems_driver_address_table
1519@example
1520typedef struct @{
1521  rtems_device_driver_entry initialization_entry;
1522  rtems_device_driver_entry open_entry;
1523  rtems_device_driver_entry close_entry;
1524  rtems_device_driver_entry read_entry;
1525  rtems_device_driver_entry write_entry;
1526  rtems_device_driver_entry control_entry;
1527@} rtems_driver_address_table;
1528@end example
1529
1530@table @b
1531@item initialization_entry
1532is the address of the entry point called by
1533@code{rtems_io_initialize}
1534to initialize a device driver and its associated devices.
1535
1536@item open_entry
1537is the address of the entry point called by @code{rtems_io_open}.
1538
1539@item close_entry
1540is the address of the entry point called by @code{rtems_io_close}.
1541
1542@item read_entry
1543is the address of the entry point called by @code{rtems_io_read}.
1544
1545@item write_entry
1546is the address of the entry point called by @code{rtems_io_write}.
1547
1548@item control_entry
1549is the address of the entry point called by @code{rtems_io_control}.
1550
1551@end table
1552
1553Driver entry points configured as NULL will always
1554return a status code of @code{@value{RPREFIX}SUCCESSFUL}.  No user code will be
1555executed in this situation.
1556
1557A typical declaration for a Device Driver Table might appear as follows:
1558
1559@example
1560rtems_driver_address_table Driver_table[2] = @{
1561   @{ tty_initialize, tty_open,  tty_close,  /* major = 0 */
1562     tty_read,       tty_write, tty_control
1563   @},
1564   @{ lp_initialize, lp_open,    lp_close,   /* major = 1 */
1565     NULL,          lp_write,   lp_control
1566   @}
1567@};
1568@end example
1569
1570More information regarding the construction and
1571operation of device drivers is provided in the I/O Manager
1572chapter.
1573
1574@section User Extensions Table
1575
1576@cindex User Extensions Table
1577
1578The User Extensions Table is used to inform RTEMS of
1579the optional user-supplied static extension set.  This table
1580contains one entry for each possible extension.  The entries are
1581called at critical times in the life of the system and
1582individual tasks.  The application may create dynamic extensions
1583in addition to this single static set.  The format of each entry
1584in the User Extensions Table is defined in the following C structure:
1585
1586@example
1587typedef void           rtems_extension;
1588typedef rtems_extension (*rtems_task_create_extension)(
1589   Thread_Control * /* executing */,
1590   Thread_Control * /* created */
1591);
1592typedef rtems_extension (*rtems_task_delete_extension)(
1593   Thread_Control * /* executing */,
1594   Thread_Control * /* deleted */
1595);
1596typedef rtems_extension (*rtems_task_start_extension)(
1597   Thread_Control * /* executing */,
1598   Thread_Control * /* started */
1599);
1600typedef rtems_extension (*rtems_task_restart_extension)(
1601   Thread_Control * /* executing */,
1602   Thread_Control * /* restarted */
1603);
1604typedef rtems_extension (*rtems_task_switch_extension)(
1605   Thread_Control * /* executing */,
1606   Thread_Control * /* heir */
1607);
1608typedef rtems_extension (*rtems_task_begin_extension)(
1609   Thread_Control * /* beginning */
1610);
1611typedef rtems_extension (*rtems_task_exitted_extension)(
1612   Thread_Control * /* exiting */
1613);
1614typedef rtems_extension (*rtems_fatal_extension)(
1615   Internal_errors_Source /* the_source */,
1616   bool                   /* is_internal */,
1617   uint32_t               /* the_error */
1618);
1619
1620typedef struct @{
1621  rtems_task_create_extension      thread_create;
1622  rtems_task_start_extension       thread_start;
1623  rtems_task_restart_extension     thread_restart;
1624  rtems_task_delete_extension      thread_delete;
1625  rtems_task_switch_extension      thread_switch;
1626  rtems_task_begin_extension       thread_begin;
1627  rtems_task_exitted_extension     thread_exitted;
1628  rtems_fatal_extension            fatal;
1629@} rtems_extensions_table;
1630@end example
1631
1632@table @b
1633
1634@item thread_create
1635is the address of the
1636user-supplied subroutine for the TASK_CREATE extension.  If this
1637extension for task creation is defined, it is called from the
1638task_create directive.  A value of NULL indicates that no
1639extension is provided.
1640
1641@item thread_start
1642is the address of the user-supplied
1643subroutine for the TASK_START extension.  If this extension for
1644task initiation is defined, it is called from the task_start
1645directive.  A value of NULL indicates that no extension is
1646provided.
1647
1648@item thread_restart
1649is the address of the user-supplied
1650subroutine for the TASK_RESTART extension.  If this extension
1651for task re-initiation is defined, it is called from the
1652task_restart directive.  A value of NULL indicates that no
1653extension is provided.
1654
1655@item thread_delete
1656is the address of the user-supplied
1657subroutine for the TASK_DELETE extension.  If this RTEMS
1658extension for task deletion is defined, it is called from the
1659task_delete directive.  A value of NULL indicates that no
1660extension is provided.
1661
1662@item thread_switch
1663is the address of the user-supplied
1664subroutine for the task context switch extension.  This
1665subroutine is called from RTEMS dispatcher after the current
1666task has been swapped out but before the new task has been
1667swapped in.  A value of NULL indicates that no extension is
1668provided.  As this routine is invoked after saving the current
1669task's context and before restoring the heir task's context, it
1670is not necessary for this routine to save and restore any
1671registers.
1672
1673@item thread_begin
1674is the address of the user-supplied
1675subroutine which is invoked immediately before a task begins
1676execution.  It is invoked in the context of the beginning task.
1677A value of NULL indicates that no extension is provided.
1678
1679@item thread_exitted
1680is the address of the user-supplied
1681subroutine which is invoked when a task exits.  This procedure
1682is responsible for some action which will allow the system to
1683continue execution (i.e. delete or restart the task) or to
1684terminate with a fatal error.  If this field is set to NULL, the
1685default RTEMS TASK_EXITTED handler will be invoked.
1686
1687@item fatal
1688is the address of the user-supplied
1689subroutine for the FATAL extension.  This RTEMS extension of
1690fatal error handling is called from the
1691@code{@value{DIRPREFIX}fatal_error_occurred}
1692directive.  If the user's fatal error handler returns or if this
1693entry is NULL then the default RTEMS fatal error handler will be
1694executed.
1695
1696@end table
1697
1698A typical declaration for a User Extension Table
1699which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and
1700FATAL extension might appear as follows:
1701
1702@example
1703rtems_extensions_table User_extensions = @{
1704   task_create_extension,
1705   NULL,
1706   NULL,
1707   task_delete_extension,
1708   task_switch_extension,
1709   NULL,
1710   NULL,
1711   fatal_extension
1712@};
1713@end example
1714
1715More information regarding the user extensions is
1716provided in the User Extensions chapter.
1717
1718@section Multiprocessor Configuration Table
1719
1720@cindex Multiprocessor Configuration Table
1721
1722The Multiprocessor Configuration Table contains
1723information needed when using RTEMS in a multiprocessor
1724configuration.  Many of the details associated with configuring
1725a multiprocessor system are dependent on the multiprocessor
1726communications layer provided by the user.  The address of the
1727Multiprocessor Configuration Table should be placed in the
1728@code{User_multiprocessing_table} entry in the primary Configuration
1729Table.  Further details regarding many of the entries in the
1730Multiprocessor Configuration Table will be provided in the
1731Multiprocessing chapter. 
1732
1733
1734When using the @code{rtems/confdefs.h} mechanism for configuring
1735an RTEMS application, the macro @code{CONFIGURE_MP_APPLICATION} must
1736be defined to automatically generate the Multiprocessor Configuration Table.
1737If @code{CONFIGURE_MP_APPLICATION}, is not defined, then a NULL pointer
1738is configured as the address of this table.
1739
1740The format of the Multiprocessor Configuration Table is defined in
1741the following C structure:
1742
1743@example
1744typedef struct @{
1745  uint32_t          node;
1746  uint32_t          maximum_nodes;
1747  uint32_t          maximum_global_objects;
1748  uint32_t          maximum_proxies;
1749  uint32_t          extra_mpci_receive_server_stack;
1750  rtems_mpci_table *User_mpci_table;
1751@} rtems_multiprocessing_table;
1752@end example
1753
1754@table @b
1755@item node
1756is a unique processor identifier
1757and is used in routing messages between nodes in a
1758multiprocessor configuration.  Each processor must have a unique
1759node number.  RTEMS assumes that node numbers start at one and
1760increase sequentially.  This assumption can be used to advantage
1761by the user-supplied MPCI layer.  Typically, this requirement is
1762made when the node numbers are used to calculate the address of
1763inter-processor communication links.  Zero should be avoided as
1764a node number because some MPCI layers use node zero to
1765represent broadcasted packets.  Thus, it is recommended that
1766node numbers start at one and increase sequentially.
1767When using the @code{rtems/confdefs.h} mechanism for configuring
1768an RTEMS application, the value for this field corresponds
1769to the setting of the macro @code{CONFIGURE_MP_NODE_NUMBER}.
1770If not defined by the application, then the @code{CONFIGURE_MP_NODE_NUMBER}
1771macro defaults to the value of the @code{NODE_NUMBER} macro which is
1772set on the compiler command line by the RTEMS Multiprocessing Test Suites.
1773
1774
1775@item maximum_nodes
1776is the number of processor nodes in the system.
1777When using the @code{rtems/confdefs.h} mechanism for configuring
1778an RTEMS application, the value for this field corresponds
1779to the setting of the macro @code{CONFIGURE_MP_MAXIMUM_NODES}.
1780If not defined by the application, then the @code{CONFIGURE_MP_MAXIMUM_NODES}
1781macro defaults to the value 2.
1782
1783@item maximum_global_objects
1784is the maximum number of global objects which can exist at any
1785given moment in the entire system.  If this parameter is not the
1786same on all nodes in the system, then a fatal error is generated
1787to inform the user that the system is inconsistent.
1788When using the @code{rtems/confdefs.h} mechanism for configuring
1789an RTEMS application, the value for this field corresponds
1790to the setting of the macro @code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS}.
1791If not defined by the application, then the
1792@code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS} macro defaults to the value 32.
1793
1794
1795@item maximum_proxies
1796is the maximum number of proxies which can exist at any given moment
1797on this particular node.  A proxy is a substitute task control block
1798which represent a task residing on a remote node when that task blocks
1799on a remote object.  Proxies are used in situations in which delayed
1800interaction is required with a remote node.
1801When using the @code{rtems/confdefs.h} mechanism for configuring
1802an RTEMS application, the value for this field corresponds
1803to the setting of the macro @code{CONFIGURE_MP_MAXIMUM_PROXIES}.
1804If not defined by the application, then the @code{CONFIGURE_MP_MAXIMUM_PROXIES}
1805macro defaults to the value 32.
1806
1807@item extra_mpci_receive_server_stack
1808is the extra stack space allocated for the RTEMS MPCI receive server task
1809in bytes.  The MPCI receive server may invoke nearly all directives and
1810may require extra stack space on some targets.
1811
1812@item User_mpci_table
1813is the address of the Multiprocessor Communications Interface
1814Table.  This table contains the entry points of user-provided functions
1815which constitute the multiprocessor communications layer.  This table
1816must be provided in multiprocessor configurations with all
1817entries configured.  The format of this table and details
1818regarding its entries can be found in the next section.
1819When using the @code{rtems/confdefs.h} mechanism for configuring
1820an RTEMS application, the value for this field corresponds
1821to the setting of the macro @code{CONFIGURE_MP_MPCI_TABLE_POINTER}.
1822If not defined by the application, then the
1823@code{CONFIGURE_MP_MPCI_TABLE_POINTER} macro defaults to the
1824address of the table named @code{MPCI_table}.
1825
1826
1827@end table
1828
1829@section Multiprocessor Communications Interface Table
1830
1831@cindex  Multiprocessor Communications Interface Table
1832
1833This table defines the set of callouts that must be provided by
1834an Multiprocessor Communications Interface implementation. 
1835
1836When using the @code{rtems/confdefs.h} mechanism for configuring
1837an RTEMS application, the name of this table is assumed
1838to be @code{MPCI_table} unless the application sets
1839the @code{CONFIGURE_MP_MPCI_TABLE_POINTER} when configuring a
1840multiprocessing system.
1841
1842The format of this table is defined in
1843the following C structure:
1844
1845@example
1846typedef struct @{
1847  uint32_t                        default_timeout; /* in ticks */
1848  uint32_t                        maximum_packet_size;
1849  rtems_mpci_initialization_entry initialization;
1850  rtems_mpci_get_packet_entry     get_packet;
1851  rtems_mpci_return_packet_entry  return_packet;
1852  rtems_mpci_send_entry           send_packet;
1853  rtems_mpci_receive_entry        receive_packet;
1854@} rtems_mpci_table;
1855@end example
1856
1857@table @b
1858@item default_timeout
1859is the default maximum length of time a task should block waiting for
1860a response to a directive which results in communication with a remote node.
1861The maximum length of time is a function the user supplied
1862multiprocessor communications layer and the media used.  This
1863timeout only applies to directives which would not block if the
1864operation were performed locally.
1865
1866@item maximum_packet_size
1867is the size in bytes of the longest packet which the MPCI layer is capable
1868of sending.  This value should represent the total number of bytes available
1869for a RTEMS interprocessor messages.
1870
1871@item initialization
1872is the address of the entry point for the initialization procedure of the
1873user supplied multiprocessor communications layer.
1874
1875@item get_packet
1876is the address of the entry point for the procedure called by RTEMS to
1877obtain a packet from the user supplied multiprocessor communications layer.
1878
1879@item return_packet
1880is the address of the entry point for the procedure called by RTEMS to
1881return a packet to the user supplied multiprocessor communications layer.
1882
1883@item send
1884is the address of the entry point for the procedure called by RTEMS to
1885send an envelope to another node.  This procedure is part of the user
1886supplied multiprocessor communications layer.
1887
1888@item receive
1889is the address of the entry point for the
1890procedure called by RTEMS to retrieve an envelope containing a
1891message from another node.  This procedure is part of the user
1892supplied multiprocessor communications layer.
1893
1894@end table
1895
1896More information regarding the required functionality of these
1897entry points is provided in the Multiprocessor chapter.
1898
1899@section Determining Memory Requirements
1900
1901Since memory is a critical resource in many real-time
1902embedded systems, the RTEMS Classic API was specifically designed to allow
1903unused managers to be forcibly excluded from the run-time environment.
1904This allows the application designer the flexibility to tailor
1905RTEMS to most efficiently meet system requirements while still
1906satisfying even the most stringent memory constraints.  As
1907result, the size of the RTEMS executive is application
1908dependent.
1909
1910It is not necessary for RTEMS Application Developers to calculate
1911the amount of memory required for the RTEMS Workspace.  This
1912is done automatically by @code{<rtems/confdefs.h>}. 
1913See @ref{Configuring a System Sizing the RTEMS RAM Workspace} for
1914more details on how
1915this works.  In the event, you are interested in the memory required
1916for an instance of a particular RTEMS object, please run the test
1917@code{spsize} on your target board.
1918
1919RTEMS is built to be a library and any routines that you do not
1920directly or indirectly require in your application will @b{NOT}
1921be included in your executable image.  However, some managers
1922may be explicitly excluded and no attempt to create these instances
1923of these objects will succeed even if they are configured.
1924The following Classic API managers may be optionally excluded:
1925
1926@itemize @bullet
1927@item signal
1928@item region
1929@item dual ported memory
1930@item event
1931@item multiprocessing
1932@item partition
1933@item timer
1934@item semaphore
1935@item message
1936@item rate monotonic
1937@end itemize
1938
1939RTEMS is designed to be built and installed as a library
1940that is linked into the application.  As such, much of
1941RTEMS is implemented in such a way that there is a single
1942entry point per source file.  This avoids having the
1943linker being forced to pull large object files in their
1944entirety into an application when the application references
1945a single symbol.  In the event you discover an RTEMS method
1946that is included in your executable but never entered, please
1947let us know.  It might be an opportunity to break a dependency
1948and shrink many RTEMS applications.
1949
1950RTEMS based applications must somehow provide memory
1951for RTEMS' code and data space.  Although RTEMS' data space must
1952be in RAM, its code space can be located in either ROM or RAM.
1953In addition, the user must allocate RAM for the RTEMS RAM
1954Workspace.  The size of this area is application dependent and
1955can be calculated using the formula provided in the Memory
1956Requirements chapter of the Applications Supplement document
1957for a specific target processor.
1958
1959All private RTEMS data variables and routine names used by
1960RTEMS begin with the underscore ( _ ) character followed by an
1961upper-case letter.  If RTEMS is linked with an application, then
1962the application code should NOT contain any symbols which begin
1963with the underscore character and followed by an upper-case
1964letter to avoid any naming conflicts.  All RTEMS directive names
1965should be treated as reserved words.
1966
1967@section Sizing the RTEMS RAM Workspace
1968
1969The RTEMS RAM Workspace is a user-specified block of
1970memory reserved for use by RTEMS.  The application should NOT
1971modify this memory.  This area consists primarily of the RTEMS
1972data structures whose exact size depends upon the values
1973specified in the Configuration Table.  In addition, task stacks
1974and floating point context areas are dynamically allocated from
1975the RTEMS RAM Workspace.
1976
1977The @code{rtems/confdefs.h} mechanism calcalutes the size
1978of the RTEMS RAM Workspace automatically.  It assumes that
1979all tasks are floating point and that all will be allocated
1980the miminum stack space.  This calculation also automatically
1981includes the memory that will be allocated for internal use
1982by RTEMS.  The following macros may be set
1983by the application to make the calculation
1984of memory required more accurate:
1985
1986@itemize @bullet
1987
1988@item @code{CONFIGURE_MEMORY_OVERHEAD}
1989@item @code{CONFIGURE_EXTRA_TASK_STACKS}
1990
1991@end itemize
1992
1993The starting address of the RTEMS RAM Workspace must
1994be aligned on a four-byte boundary.  Failure to properly align
1995the workspace area will result in the
1996@code{@value{DIRPREFIX}fatal_error_occurred}
1997directive being invoked with the
1998@code{@value{RPREFIX}INVALID_ADDRESS} error code.
1999
2000The file @code{<rtems/confdefs.h>} will calculate the
2001value that is specified as the @code{work_space_size}
2002parameter of the Configuration Table. There are many
2003parameters the application developer can specify to
2004help @code{<rtems/confdefs.h>} in its calculations.  Correctly
2005specifying the application requirements via parameters
2006such as @code{CONFIGURE_EXTRA_TASK_STACKS} and
2007@code{CONFIGURE_MAXIMUM_TASKS} is critical.
2008
2009The allocation of objects can operate in two modes. The default mode
2010has an object number ceiling. No more than the specified number of
2011objects can be allocated from the RTEMS RAM Workspace. The number of objects
2012specified in the particular API Configuration table fields are
2013allocated at initialisation. The second mode allows the number of
2014objects to grow to use the available free memory in the RTEMS RAM Workspace.
2015
2016The auto-extending mode can be enabled individually for each object
2017type by using the macro @code{rtems_resource_unlimited}. This takes a value
2018as a parameter, and is used to set the object maximum number field in
2019an API Configuration table. The value is an allocation unit size. When
2020RTEMS is required to grow the object table it is grown by this
2021size. The kernel will return the object memory back to the RTEMS RAM Workspace
2022when an object is destroyed. The kernel will only return an allocated
2023block of objects to the RTEMS RAM Workspace if at least half the allocation
2024size of free objects remain allocated. RTEMS always keeps one
2025allocation block of objects allocated. Here is an example of using
2026@code{rtems_resource_unlimited}:
2027
2028@example
2029#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
2030@end example
2031
2032The user is cautioned that future versions of RTEMS may not have the
2033same memory requirements per object. Although the value calculated is
2034suficient for a particular target processor and release of RTEMS,
2035memory usage is subject to change across versions and target
2036processors.  To avoid problems, the user should accurately
2037specify each configuration parameter and allow
2038@code{<rtems/confdefs.h>} to calculate the memory requirements.
2039The memory requirements are likely to change each
2040time one of the following events occurs:
2041
2042@itemize @bullet
2043@item a configuration parameter is modified,
2044@item task or interrupt stack requirements change,
2045@item task floating point attribute is altered,
2046@item RTEMS is upgraded, or
2047@item the target processor is changed.
2048@end itemize
2049
2050Failure to provide enough space in the RTEMS RAM
2051Workspace will result in the
2052@code{@value{DIRPREFIX}fatal_error_occurred} directive
2053being invoked with the appropriate error code.
Note: See TracBrowser for help on using the repository browser.