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

4.104.114.84.95
Last change on this file since 6449498 was 6449498, checked in by Joel Sherrill <joel.sherrill@…>, on 01/17/02 at 21:47:47

2001-01-17 Joel Sherrill <joel@…>

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