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

4.104.114.9
Last change on this file since d5671b1 was d5671b1, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 29, 2008 at 9:37:00 PM

2008-01-29 Joel Sherrill <joel.sherrill@…>

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