source: rtems/doc/user/conf.t @ 11be37d

4.11
Last change on this file since 11be37d was 11be37d, checked in by Joel Sherrill <joel.sherrill@…>, on Jun 17, 2010 at 6:45:36 PM

2010-06-17 Joel Sherrill <joel.sherrill@…>

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