source: rtems/doc/user/conf.t @ 66c50e2

4.104.114.9
Last change on this file since 66c50e2 was 66c50e2, checked in by Joel Sherrill <joel.sherrill@…>, on Dec 4, 2007 at 10:18:30 PM

2007-12-04 Joel Sherrill <joel.sherrill@…>

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