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

4.11
Last change on this file since db9964f1 was db9964f1, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 24, 2010 at 3:52:21 PM

2010-11-24 Gedare Bloom <giddyup44@…>

PR 1647/cpukit

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