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

4.104.114.84.95
Last change on this file since bae90e1 was bae90e1, checked in by Joel Sherrill <joel.sherrill@…>, on 07/03/99 at 19:06:57

Added a lot of information on confdefs.t

  • Property mode set to 100644
File size: 49.9 KB
Line 
1@c  COPYRIGHT (c) 1988-1998.
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
12@c CONFIGURE_MALLOC_REGION
13@c CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS
14@c CONFIGURE_LIBIO_SEMAPHORES
15@c CONFIGURE_INIT
16@c CONFIGURE_INTERRUPT_STACK_MEMORY
17@c CONFIGURE_GNAT_RTEMS
18@c     CONFIGURE_GNAT_MUTEXES
19@c     CONFIGURE_GNAT_KEYS
20@c     CONFIGURE_MAXIMUM_ADA_TASKS
21@c     CONFIGURE_MAXIMUM_FAKE_ADA_TASKS
22@c     CONFIGURE_ADA_TASKS_STACK
23@c
24@c In addition, there should be examples of defining your own
25@c Device Driver Table, Init task table, etc.
26@c
27@c Regardless, this is a big step up. :)
28@c
29
30@chapter Configuring a System
31
32@section Automatic Generation of System Configuration
33
34RTEMS provides the @code{confdefs.h} C language header file that
35based on the setting of a variety of macros can automatically
36produce nearly all of the configuration tables required
37by an RTEMS application.  Rather than building the individual
38tables by hand. the application simply specifies the values
39for the configuration parameters it wishes to set.  In the following
40example, the configuration information for a simple system with
41a message queue and a time slice of 50 milliseconds is configured:
42
43@example
44@group
45#define CONFIGURE_TEST_NEEDS_CONSOLE_DRIVER
46#define CONFIGURE_TEST_NEEDS_CLOCK_DRIVER
47
48#define CONFIGURE_MICROSECONDS_PER_TICK   1000 /* 1 millisecond */
49#define CONFIGURE_TICKS_PER_TIMESLICE       50 /* 50 milliseconds */
50
51#define CONFIGURE_RTEMS_INIT_TASKS_TABLE
52@end group
53@end example
54
55This system will begin execution with the single initialization task
56named @code{Init}.  It will be configured to have both a console
57device driver (for standard I/O) and a clock tick device driver.
58
59For each configuration parameter in the configuration tables, the
60macro corresponding to that field is discussed.  Most systems
61can be easily configured using the @code{confdefs.h} mechanism.
62
63@section Configuration Table
64
65The RTEMS Configuration Table is used to tailor an
66application for its specific needs.  For example, the user can
67configure the number of device drivers or which APIs may be used.
68THe address of the user-defined Configuration Table is passed as an
69argument to the @code{@value{DIRPREFIX}initialize_executive}
70directive, which MUST be the first RTEMS directive called. 
71The RTEMS Configuration Table
72is defined in the following @value{LANGUAGE} @value{STRUCTURE}:
73
74@ifset is-C
75@example
76@group
77typedef struct @{
78  void                             *work_space_start;
79  rtems_unsigned32                  work_space_size;
80  rtems_unsigned32                  maximum_extensions;
81  rtems_unsigned32                  microseconds_per_tick;
82  rtems_unsigned32                  ticks_per_timeslice;
83  rtems_unsigned32                  maximum_devices;
84  rtems_unsigned32                  number_of_device_drivers;
85  rtems_driver_address_table       *Device_driver_table;
86  rtems_unsigned32                  number_of_initial_extensions;
87  rtems_extensions_table           *User_extension_table;
88  rtems_multiprocessing_table      *User_multiprocessing_table;
89  rtems_api_configuration_table    *RTEMS_api_configuration;
90  posix_api_configuration_table    *POSIX_api_configuration;
91@} rtems_configuration_table;
92@end group
93@end example
94@end ifset
95
96@ifset is-Ada
97@example
98type Configuration_Table is
99   record
100       Work_Space_Start             : RTEMS.Address;
101       Work_Space_Size              : RTEMS.Unsigned32;
102       Maximum_Extensions           : RTEMS.Unsigned32;
103       Microseconds_Per_Tick        : RTEMS.Unsigned32;
104       Ticks_Per_Timeslice          : RTEMS.Unsigned32;
105       Maximum_Devices              : RTEMS.Unsigned32;
106       Number_Of_Device_Drivers     : RTEMS.Unsigned32;
107       Device_Driver_Table          : RTEMS.Driver_Address_Table_Pointer;
108       Number_Of_Initial_Extensions : RTEMS.Unsigned32;
109       User_Extension_Table         : RTEMS.Extensions_Table_Pointer;
110       User_Multiprocessing_Table   : RTEMS.Multiprocessing_Table_Pointer;
111       RTEMS_API_Configuration      : RTEMS.API_Configuration_Table_Pointer;
112       POSIX_API_Configuration      :
113                       RTEMS.POSIX_API_Configuration_Table_Pointer;
114   end record;
115
116type Configuration_Table_Pointer is access all Configuration_Table;
117@end example
118@end ifset
119
120@table @b
121@item work_space_start
122is the address of the RTEMS RAM Workspace. 
123This area contains items such as the
124various object control blocks (TCBs, QCBs, ...) and task stacks.
125If the address is not aligned on a four-word boundary, then
126RTEMS will invoke the fatal error handler during
127@code{@value{DIRPREFIX}initialize_executive}.
128When using the @code{confdefs.h} mechanism for configuring
129an RTEMS application, the value for this field corresponds
130to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA}.
131
132@item work_space_size
133is the calculated size of the
134RTEMS RAM Workspace.  The section Sizing the RTEMS RAM Workspace
135details how to arrive at this number.
136When using the @code{confdefs.h} mechanism for configuring
137an RTEMS application, the value for this field corresponds
138to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_SIZE}
139and is calculated based on the other system configuration settings.
140
141@item microseconds_per_tick
142is number of microseconds per clock tick.
143When using the @code{confdefs.h} mechanism for configuring
144an RTEMS application, the value for this field corresponds
145to the setting of the macro @code{CONFIGURE_MICROSECONDS_PER_TICK}.
146If not defined by the application, then the @code{CONFIGURE_MAXIMUM_TASKS}
147macro defaults to 10.
148XXX
149
150@item ticks_per_timeslice
151is the number of clock ticks for a timeslice.
152When using the @code{confdefs.h} mechanism for configuring
153an RTEMS application, the value for this field corresponds
154to the setting of the macro @code{CONFIGURE_TICKS_PER_TIMESLICE}.
155
156@item maximum_devices
157is the maximum number of devices that can be registered.
158When using the @code{confdefs.h} mechanism for configuring
159an RTEMS application, the value for this field corresponds
160to the setting of the macro @code{CONFIGURE_MAXIMUM_DEVICES}.
161
162@item number_of_device_drivers
163is the number of device drivers for the system.  There should be
164the same number of entries in the Device Driver Table.  If this field
165is zero, then the @code{User_driver_address_table} entry should be NULL.
166When using the @code{confdefs.h} mechanism for configuring
167an RTEMS application, the value for this field is calculated
168automatically based on the number of entries in the
169Device Driver Table.  This calculation is based on the assumption
170that the Device Driver Table is named @code{Device_drivers}
171and defined in C.  This table may be generated automatically
172for simple applications using only the device drivers that correspond
173to the following macros:
174
175@itemize @bullet
176
177@item @code{CONFIGURE_TEST_NEEDS_CONSOLE_DRIVER}
178@item @code{CONFIGURE_TEST_NEEDS_CLOCK_DRIVER}
179@item @code{CONFIGURE_TEST_NEEDS_TIMER_DRIVER}
180@item @code{CONFIGURE_TEST_NEEDS_RTC_DRIVER}
181@item @code{CONFIGURE_TEST_NEEDS_STUB_DRIVER}
182
183@end itemize
184
185Note that network device drivers are not configured in the
186Device Driver Table.
187
188@item Device_driver_table
189is the address of the Device Driver Table.  This table contains the entry
190points for each device driver.  If the number_of_device_drivers field is zero,
191then this entry should be NULL. The format of this table will be
192discussed below.
193When using the @code{confdefs.h} mechanism for configuring
194an RTEMS application, the Device Driver Table is assumed to be
195named @code{Device_drivers} and defined in C.  If the application is providing
196its own Device Driver Table, then the macro
197@code{CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE} must be defined to indicate
198this and prevent @code{confdefs.h} from generating the table.
199
200@item number_of_initial_extensions
201is the number of initial user extensions.  There should be
202the same number of entries as in the User_extension_table.  If this field
203is zero, then the User_driver_address_table entry should be NULL.
204When using the @code{confdefs.h} mechanism for configuring
205an RTEMS application, the value for this field corresponds
206to the setting of the macro @code{CONFIGURE_NUMBER_OF_INITIAL_EXTENSIONS}
207which is set automatically by @code{confdefs.h} based on the size
208of the User Extensions Table.
209
210@item User_extension_table
211is the address of the User
212Extension Table.  This table contains the entry points for the
213static set of optional user extensions.  If no user extensions
214are configured, then this entry should be NULL.  The format of
215this table will be discussed below.
216When using the @code{confdefs.h} mechanism for configuring
217an RTEMS application, the User Extensions Table is named
218@code{Configuration_Initial_Extensions} and defined in
219confdefs.h.  It is initialized based on the following
220macros:
221
222@itemize @bullet
223
224@item @code{CONFIGURE_INITIAL_EXTENSIONS}
225@item @code{STACK_CHECKER_EXTENSION}
226
227@end itemize
228
229The application may configure one or more initial user extension
230sets by setting the @code{CONFIGURE_INITIAL_EXTENSIONS} macro.  By
231defining the @code{STACK_CHECKER_EXTENSION} macro, the task stack bounds
232checking user extension set is automatically included in the
233application.
234
235@item User_multiprocessing_table
236is the address of the Multiprocessor Configuration Table.  This
237table contains information needed by RTEMS only when used in a multiprocessor
238configuration.  This field must be NULL when RTEMS is used in a
239single processor configuration.
240When using the @code{confdefs.h} mechanism for configuring
241an RTEMS application, the Multiprocessor Configuration Table
242is automatically generated when the @code{CONFIGURE_MPTEST}
243is defined.  If @code{CONFIGURE_MPTEST} is not defined, the this
244entry is set to NULL.  The generated table has the name
245@code{Multiprocessing_configuration}.
246
247@item RTEMS_api_configuration
248is the address of the RTEMS API Configuration Table.  This table
249contains information needed by the RTEMS API.  This field should be
250NULL if the RTEMS API is not used.  [NOTE: Currently the RTEMS API
251is required to support support components such as BSPs and libraries
252which use this API.]  This table is built automatically and this
253entry filled in, if using the @code{confdefs.h} application
254configuration mechanism.  The generated table has the name
255@code{Configuration_RTEMS_API}.
256
257@item POSIX_api_configuration
258is the address of the POSIX API Configuration Table.  This table
259contains information needed by the POSIX API.  This field should be
260NULL if the POSIX API is not used.  This table is built automatically
261and this entry filled in, if using the @code{confdefs.h} application
262configuration mechanism.  The @code{confdefs.h} application
263mechanism will fill this field in with the address of the
264@code{Configuration_POSIX_API} table of POSIX API is configured
265and NULL if the POSIX API is not configured.
266
267@end table
268
269@section RTEMS API Configuration Table
270
271The RTEMS API Configuration Table is used to configure the
272managers which constitute the RTEMS API for a particular application. 
273For example, the user can configure the maximum number of tasks for
274this application. The RTEMS API Configuration Table is defined in
275the following @value{LANGUAGE} @value{STRUCTURE}:
276
277@ifset is-C
278@example
279@group
280typedef struct @{
281  rtems_unsigned32                  maximum_tasks;
282  rtems_unsigned32                  maximum_timers;
283  rtems_unsigned32                  maximum_semaphores;
284  rtems_unsigned32                  maximum_message_queues;
285  rtems_unsigned32                  maximum_partitions;
286  rtems_unsigned32                  maximum_regions;
287  rtems_unsigned32                  maximum_ports;
288  rtems_unsigned32                  maximum_periods;
289  rtems_unsigned32                  number_of_initialization_tasks;
290  rtems_initialization_tasks_table *User_initialization_tasks_table;
291@} rtems_api_configuration_table;
292@end group
293@end example
294@end ifset
295
296@ifset is-Ada
297@example
298type API_Configuration_Table is
299   record
300      Maximum_Tasks                   : RTEMS.Unsigned32;
301      Maximum_Timers                  : RTEMS.Unsigned32;
302      Maximum_Semaphores              : RTEMS.Unsigned32;
303      Maximum_Message_queues          : RTEMS.Unsigned32;
304      Maximum_Partitions              : RTEMS.Unsigned32;
305      Maximum_Regions                 : RTEMS.Unsigned32;
306      Maximum_Ports                   : RTEMS.Unsigned32;
307      Maximum_Periods                 : RTEMS.Unsigned32;
308      Number_Of_Initialization_Tasks  : RTEMS.Unsigned32;
309      User_Initialization_Tasks_Table :
310                                RTEMS.Initialization_Tasks_Table_Pointer;
311   end record;
312
313type API_Configuration_Table_Pointer is access all API_Configuration_Table;
314@end example
315@end ifset
316
317@table @b
318@item maximum_tasks
319is the maximum number of tasks that
320can be concurrently active (created) in the system including
321initialization tasks.
322When using the @code{confdefs.h} mechanism for configuring
323an RTEMS application, the value for this field corresponds
324to the setting of the macro @code{CONFIGURE_MAXIMUM_TASKS}.
325If not defined by the application, then the @code{CONFIGURE_MAXIMUM_TASKS}
326macro defaults to 10.
327
328@item maximum_timers
329is the maximum number of timers
330that can be concurrently active in the system.
331When using the @code{confdefs.h} mechanism for configuring
332an RTEMS application, the value for this field corresponds
333to the setting of the macro @code{CONFIGURE_MAXIMUM_TIMERS}.
334If not defined by the application, then the @code{CONFIGURE_MAXIMUM_TIMERS}
335macro defaults to 0.
336
337@item maximum_semaphores
338is the maximum number of
339semaphores that can be concurrently active in the system.
340When using the @code{confdefs.h} mechanism for configuring
341an RTEMS application, the value for this field corresponds
342to the setting of the macro @code{CONFIGURE_MAXIMUM_SEMAPHORES}.
343If not defined by the application, then the @code{CONFIGURE_MAXIMUM_SEMAPHORES}
344macro defaults to 0.
345
346@item maximum_message_queues
347is the maximum number of
348message queues that can be concurrently active in the system.
349When using the @code{confdefs.h} mechanism for configuring
350an RTEMS application, the value for this field corresponds
351to the setting of the macro @code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES}.
352If not defined by the application, then the
353@code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES} macro defaults to 0.
354
355@item maximum_partitions
356is the maximum number of
357partitions that can be concurrently active in the system.
358When using the @code{confdefs.h} mechanism for configuring
359an RTEMS application, the value for this field corresponds
360to the setting of the macro @code{CONFIGURE_MAXIMUM_PARTITIONS}.
361If not defined by the application, then the @code{CONFIGURE_MAXIMUM_PARTITIONS}
362macro defaults to 0.
363
364@item maximum_regions
365is the maximum number of regions
366that can be concurrently active in the system.
367When using the @code{confdefs.h} mechanism for configuring
368an RTEMS application, the value for this field corresponds
369to the setting of the macro @code{CONFIGURE_MAXIMUM_REGIONS}.
370If not defined by the application, then the @code{CONFIGURE_MAXIMUM_REGIONS}
371macro defaults to 0.
372
373@item maximum_ports
374is the maximum number of ports into
375dual-port memory areas that can be concurrently active in the
376system.
377When using the @code{confdefs.h} mechanism for configuring
378an RTEMS application, the value for this field corresponds
379to the setting of the macro @code{CONFIGURE_MAXIMUM_PORTS}.
380If not defined by the application, then the @code{CONFIGURE_MAXIMUM_PORTS}
381macro defaults to 0.
382
383@item number_of_initialization_tasks
384is the number of initialization tasks configured.  At least one
385RTEMS initialization task or POSIX initializatin must be configured
386in order for the user's application to begin executing.
387When using the @code{confdefs.h} mechanism for configuring
388an RTEMS application, the user must define the
389@code{CONFIGURE_RTEMS_INIT_TASKS_TABLE} to indicate that there
390is one or more RTEMS initialization task.  If the application
391only has one RTEMS initialization task, then the automatically
392generated Initialization Task Table will be sufficient.  The following
393macros correspond to the single initialization task:
394 
395@itemize @bullet
396
397@item @code{CONFIGURE_INIT_TASK_NAME} - is the name of the task. 
398If this macro is not defined by the application, then this defaults
399to the task name of @code{"UI1 "} for User Initialization Task 1.
400
401@item @code{CONFIGURE_INIT_TASK_STACK_SIZE} - is the stack size
402of the single initialization task.  If this macro is not defined
403by the application, then this defaults to @code{RTEMS_MINIMUM_STACK_SIZE}.
404
405@item @code{CONFIGURE_INIT_TASK_PRIORITY} - is the initial priority
406of the single initialization task.  If this macro is not defined
407by the application, then this defaults to 1.
408
409@item @code{CONFIGURE_INIT_TASK_ATTRIBUTES} - is the attributes
410of the single initialization task.  If this macro is not defined
411by the application, then this defaults to @code{RTEMS_DEFAULT_ATTRIBUTES}.
412
413@item @code{CONFIGURE_INIT_TASK_ENTRY_POINT} - is the entry point
414of the single initialization task.  If this macro is not defined
415by the application, then this defaults to the C language routine
416@code{Init}.
417
418@item @code{CONFIGURE_INIT_TASK_INITIAL_MODES} - is the initial execution
419modes of the single initialization task.  If this macro is not defined
420by the application, then this defaults to @code{RTEMS_NO_PREEMPT}.
421
422@item @code{CONFIGURE_INIT_TASK_ARGUMENTS} - is the argument passed to the
423of the single initialization task.  If this macro is not defined
424by the application, then this defaults to 0.
425
426
427@end itemize
428
429
430has the option to have
431 value for this field corresponds
432to the setting of the macro @code{}.
433
434@item User_initialization_tasks_table
435is the address of the Initialization Task Table. This table contains the
436information needed to create and start each of the
437initialization tasks.  The format of this table will be discussed below.
438When using the @code{confdefs.h} mechanism for configuring
439an RTEMS application, the value for this field corresponds
440to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA}.
441
442@end table
443
444@section POSIX API Configuration Table
445
446The POSIX API Configuration Table is used to configure the
447managers which constitute the POSIX API for a particular application.
448For example, the user can configure the maximum number of threads for
449this application. The POSIX API Configuration Table is defined in
450the following @value{LANGUAGE} @value{STRUCTURE}:
451 
452@ifset is-C
453@example
454@group
455typedef struct @{
456  void       *(*thread_entry)(void *);
457@} posix_initialization_threads_table;
458 
459typedef struct @{
460  int                                 maximum_threads;
461  int                                 maximum_mutexes;
462  int                                 maximum_condition_variables;
463  int                                 maximum_keys;
464  int                                 maximum_timers;
465  int                                 maximum_queued_signals;
466  int                                 number_of_initialization_tasks;
467  posix_initialization_threads_table *User_initialization_tasks_table;
468@} posix_api_configuration_table;
469@end group
470@end example
471@end ifset
472
473@ifset is-Ada
474@example
475   type POSIX_Thread_Entry is access procedure (
476      Argument : in     RTEMS.Address
477   );
478
479   type POSIX_Initialization_Threads_Table_Entry is
480   record
481      Thread_Entry : RTEMS.POSIX_Thread_Entry;
482   end record;
483
484   type POSIX_Initialization_Threads_Table is array
485       ( RTEMS.Unsigned32 range <> ) of
486       RTEMS.POSIX_Initialization_Threads_Table_Entry;
487
488   type POSIX_Initialization_Threads_Table_Pointer is access all
489       POSIX_Initialization_Threads_Table;
490
491   type POSIX_API_Configuration_Table_Entry is
492      record
493         Maximum_Threads                 : Interfaces.C.Int;
494         Maximum_Mutexes                 : Interfaces.C.Int;
495         Maximum_Condition_Variables     : Interfaces.C.Int;
496         Maximum_Keys                    : Interfaces.C.Int;
497         Maximum_Timers                  : Interfaces.C.Int;
498         Maximum_Queued_Signals          : Interfaces.C.Int;
499         Number_Of_Initialization_Tasks  : Interfaces.C.Int;
500         User_Initialization_Tasks_Table :
501            RTEMS.POSIX_Initialization_Threads_Table_Pointer;
502      end record;
503
504   type POSIX_API_Configuration_Table is array ( RTEMS.Unsigned32 range <> ) of
505      RTEMS.POSIX_API_Configuration_Table_Entry;
506
507   type POSIX_API_Configuration_Table_Pointer is access all
508          RTEMS.POSIX_API_Configuration_Table;
509@end example
510@end ifset
511 
512@table @b
513@item maximum_threads
514is the maximum number of threads that
515can be concurrently active (created) in the system including
516initialization threads.
517When using the @code{confdefs.h} mechanism for configuring
518an RTEMS application, the value for this field corresponds
519to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_THREADS}.
520If not defined by the application, then the
521@code{CONFIGURE_MAXIMUM_POSIX_THREADS} macro defaults to 10.
522
523@item maximum_mutexes
524is the maximum number of mutexes that can be concurrently
525active in the system.
526When using the @code{confdefs.h} mechanism for configuring
527an RTEMS application, the value for this field corresponds
528to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_MUTEXES}.
529If not defined by the application, then the
530@code{CONFIGURE_MAXIMUM_POSIX_MUTEXES} macro defaults to 0.
531
532@item maximum_condition_variables
533is the maximum number of condition variables that can be
534concurrently active in the system.
535When using the @code{confdefs.h} mechanism for configuring
536an RTEMS application, the value for this field corresponds
537to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES}.
538If not defined by the application, then the
539@code{CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES} macro defaults to 0.
540
541@item maximum_keys
542is the maximum number of keys that can be concurrently active in the system.
543When using the @code{confdefs.h} mechanism for configuring
544an RTEMS application, the value for this field corresponds
545to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_KEYS}.
546If not defined by the application, then the
547@code{CONFIGURE_MAXIMUM_POSIX_KEYS} macro defaults to 0.
548
549@item maximum_timers
550is the maximum number of POSIX timers that can be concurrently active
551in the system.
552When using the @code{confdefs.h} mechanism for configuring
553an RTEMS application, the value for this field corresponds
554to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_TIMERS}.
555If not defined by the application, then the
556@code{CONFIGURE_MAXIMUM_POSIX_TIMERS} macro defaults to 0.
557
558@item maximum_queued_signals
559is the maximum number of queued signals that can be concurrently
560pending in the system.
561When using the @code{confdefs.h} mechanism for configuring
562an RTEMS application, the value for this field corresponds
563to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS}.
564If not defined by the application, then the
565@code{CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS} macro defaults to 0.
566
567@item number_of_initialization_threads
568is the number of initialization threads configured.  At least one
569initialization threads must be configured.
570When using the @code{confdefs.h} mechanism for configuring
571an RTEMS application, the user must define the
572@code{CONFIGURE_POSIX_INIT_THREAD_TABLE} to indicate that there
573is one or more POSIX initialization thread.  If the application
574only has one POSIX initialization thread, then the automatically
575generated POSIX Initialization Thread Table will be sufficient.  The following
576macros correspond to the single initialization task:
577
578@itemize @bullet
579
580@item @code{CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT} - is the entry
581point of the thread.  If this macro is not defined by the application,
582then this defaults to the C routine @code{POSIX_Init}.
583
584@item @code{CONFIGURE_POSIX_INIT_TASK_STACK_SIZE} - is the stack size
585of the single initialization thread.  If this macro is not defined
586by the application, then this defaults to
587@code{(RTEMS_MINIMUM_STACK_SIZE * 2)}.
588
589@end itemize
590 
591@item User_initialization_threads_table
592is the address of the Initialization Threads Table. This table contains the
593information needed to create and start each of the initialization threads. 
594The format of each entry in this table is defined in the
595@code{posix_initialization_threads_table} @value{STRUCTURE}.
596When using the @code{confdefs.h} mechanism for configuring
597an RTEMS application, the value for this field corresponds
598to the address of the @code{POSIX_Initialization_threads} structure.
599
600@end table
601
602@section CPU Dependent Information Table
603
604The CPU Dependent Information Table is used to
605describe processor dependent information required by RTEMS.
606This table is generally used to supply RTEMS with information
607only known by the Board Support Package.  The contents of this
608table are discussed in the CPU Dependent Information Table
609chapter of the Applications Supplement document for a specific
610target processor.
611
612The @code{confdefs.h} mechanism does not support generating this
613table.  It is normally filled in by the Board Support Package.
614
615@section Initialization Task Table
616
617The Initialization Task Table is used to describe
618each of the user initialization tasks to the Initialization
619Manager.  The table contains one entry for each initialization
620task the user wishes to create and start.  The fields of this
621data structure directly correspond to arguments to the
622@code{@value{DIRPREFIX}task_create} and
623@code{@value{DIRPREFIX}task_start} directives.  The number of entries is
624found in the @code{number_of_initialization_tasks} entry in the
625Configuration Table. 
626
627The format of each entry in the
628Initialization Task Table is defined in the following @value{LANGUAGE}
629@value{STRUCTURE}:
630
631@ifset is-C
632@example
633typedef struct @{
634  rtems_name           name;
635  rtems_unsigned32     stack_size;
636  rtems_task_priority  initial_priority;
637  rtems_attribute      attribute_set;
638  rtems_task_entry     entry_point;
639  rtems_mode           mode_set;
640  rtems_task_argument  argument;
641@} rtems_initialization_tasks_table;
642@end example
643@end ifset
644
645@ifset is-Ada
646@example
647type Initialization_Tasks_Table_Entry is
648   record
649      Name             : RTEMS.Name;          -- task name
650      Stack_Size       : RTEMS.Unsigned32;    -- task stack size
651      Initial_Priority : RTEMS.Task_priority; -- task priority
652      Attribute_Set    : RTEMS.Attribute;     -- task attributes
653      Entry_Point      : RTEMS.Task_Entry;    -- task entry point
654      Mode_Set         : RTEMS.Mode;          -- task initial mode
655      Argument         : RTEMS.Unsigned32;    -- task argument
656   end record;
657
658type Initialization_Tasks_Table is array ( RTEMS.Unsigned32 range <> ) of
659  RTEMS.Initialization_Tasks_Table_Entry;
660
661type Initialization_Tasks_Table_Pointer is access all
662     Initialization_Tasks_Table;
663@end example
664@end ifset
665
666@table @b
667@item name
668is the name of this initialization task.
669
670@item stack_size
671is the size of the stack for this initialization task.
672
673@item initial_priority
674is the priority of this initialization task.
675
676@item attribute_set
677is the attribute set used during creation of this initialization task.
678
679@item entry_point
680is the address of the entry point of this initialization task.
681
682@item mode_set
683is the initial execution mode of this initialization task.
684
685@item argument
686is the initial argument for this initialization task.
687
688@end table
689
690A typical declaration for an Initialization Task Table might appear as follows:
691
692@ifset is-C
693@example
694rtems_initialization_tasks_table
695Initialization_tasks[2] = @{
696   @{ INIT_1_NAME,
697     1024,
698     1,
699     DEFAULT_ATTRIBUTES,
700     Init_1,
701     DEFAULT_MODES,
702     1
703
704   @},
705   @{ INIT_2_NAME,
706     1024,
707     250,
708     FLOATING_POINT,
709     Init_2,
710     NO_PREEMPT,
711     2
712
713   @}
714@};
715@end example
716@end ifset
717
718@ifset is-Ada
719@example
720Initialization_Tasks : aliased RTEMS.Initialization_Tasks_Table( 1 .. 2 ) := (
721   (INIT_1_NAME,
722    1024,
723    1,
724    RTEMS.Default_Attributes,
725    Init_1'Access,
726    RTEMS.Default_Modes,
727    1),
728   (INIT_2_NAME,
729    1024,
730    250,
731    RTEMS.Floating_Point,
732    Init_2'Access,
733    RTEMS.No_Preempt,
734    2)
735);
736@end example
737@end ifset
738
739@section Driver Address Table
740
741The Device Driver Table is used to inform the I/O
742Manager of the set of entry points for each device driver
743configured in the system.  The table contains one entry for each
744device driver required by the application.  The number of
745entries is defined in the number_of_device_drivers entry in the
746Configuration Table.  The format of each entry in the Device
747Driver Table is defined in
748the following @value{LANGUAGE} @value{STRUCTURE}:
749
750@ifset is-C
751@example
752typedef struct @{
753  rtems_device_driver_entry initialization;
754  rtems_device_driver_entry open;
755  rtems_device_driver_entry close;
756  rtems_device_driver_entry read;
757  rtems_device_driver_entry write;
758  rtems_device_driver_entry control;
759@} rtems_driver_address_table;
760@end example
761@end ifset
762
763@ifset is-Ada
764@example
765type Driver_Address_Table_Entry is
766   record
767      Initialization : RTEMS.Device_Driver_Entry;
768      Open           : RTEMS.Device_Driver_Entry;
769      Close          : RTEMS.Device_Driver_Entry;
770      Read           : RTEMS.Device_Driver_Entry;
771      Write          : RTEMS.Device_Driver_Entry;
772      Control        : RTEMS.Device_Driver_Entry;
773   end record;
774
775type Driver_Address_Table is array ( RTEMS.Unsigned32 range <> ) of
776  RTEMS.Driver_Address_Table_Entry;
777
778type Driver_Address_Table_Pointer is access all Driver_Address_Table;
779@end example
780@end ifset
781
782@table @b
783@item initialization
784is the address of the entry point called by
785@code{@value{DIRPREFIX}io_initialize}
786to initialize a device driver and its associated devices.
787
788@item open
789is the address of the entry point called by @code{@value{DIRPREFIX}io_open}.
790
791@item close
792is the address of the entry point called by @code{@value{DIRPREFIX}io_close}.
793
794@item read
795is the address of the entry point called by @code{@value{DIRPREFIX}io_read}.
796
797@item write
798is the address of the entry point called by @code{@value{DIRPREFIX}io_write}.
799
800@item control
801is the address of the entry point called by @code{@value{DIRPREFIX}io_control}.
802
803@end table
804
805Driver entry points configured as NULL will always
806return a status code of @code{@value{RPREFIX}SUCCESSFUL}.  No user code will be
807executed in this situation.
808
809A typical declaration for a Device Driver Table might appear as follows:
810
811@ifset is-C
812@example
813rtems_driver_address_table Driver_table[2] = @{
814   @{ tty_initialize, tty_open,  tty_close,  /* major = 0 */
815     tty_read,       tty_write, tty_control
816   @},
817   @{ lp_initialize, lp_open,    lp_close,   /* major = 1 */
818     NULL,          lp_write,   lp_control
819   @}
820@};
821@end example
822@end ifset
823
824@ifset is-Ada
825@example
826@end example
827@end ifset
828
829More information regarding the construction and
830operation of device drivers is provided in the I/O Manager
831chapter.
832
833@section User Extensions Table
834
835The User Extensions Table is used to inform RTEMS of
836the optional user-supplied static extension set.  This table
837contains one entry for each possible extension.  The entries are
838called at critical times in the life of the system and
839individual tasks.  The application may create dynamic extensions
840in addition to this single static set.  The format of each entry
841in the User Extensions Table is defined in the following @value{LANGUAGE}
842@value{STRUCTURE}:
843
844@ifset is-C
845@example
846typedef User_extensions_routine                   rtems_extension;
847typedef User_extensions_thread_create_extension   rtems_task_create_extension;
848typedef User_extensions_thread_delete_extension   rtems_task_delete_extension;
849typedef User_extensions_thread_start_extension    rtems_task_start_extension;
850typedef User_extensions_thread_restart_extension  rtems_task_restart_extension;
851typedef User_extensions_thread_switch_extension   rtems_task_switch_extension;
852typedef User_extensions_thread_begin_extension    rtems_task_begin_extension;
853typedef User_extensions_thread_exitted_extension  rtems_task_exitted_extension;
854typedef User_extensions_fatal_extension           rtems_fatal_extension;
855
856typedef User_extensions_Table                     rtems_extensions_table;
857
858typedef struct @{
859  rtems_task_create_extension      thread_create;
860  rtems_task_start_extension       thread_start;
861  rtems_task_restart_extension     thread_restart;
862  rtems_task_delete_extension      thread_delete;
863  rtems_task_switch_extension      thread_switch;
864  rtems_task_begin_extension       thread_begin;
865  rtems_task_exitted_extension     thread_exitted;
866  rtems_fatal_extension            fatal;
867@} User_extensions_Table;
868@end example
869@end ifset
870
871@ifset is-Ada
872@example
873type Extensions_Table_Entry is
874   record
875      Thread_Create      : RTEMS.Thread_Create_Extension;
876      Thread_Start       : RTEMS.Thread_Start_Extension;
877      Thread_Restart     : RTEMS.Thread_Restart_Extension;
878      Thread_Delete      : RTEMS.Thread_Delete_Extension;
879      Thread_Switch      : RTEMS.Thread_Switch_Extension;
880      Thread_Post_Switch : RTEMS.Thread_Post_Switch_Extension;
881      Thread_Begin       : RTEMS.Thread_Begin_Extension;
882      Thread_Exitted     : RTEMS.Thread_Exitted_Extension;
883      Fatal            : RTEMS.Fatal_Error_Extension;
884   end record;
885@end example
886@end ifset
887
888@table @b
889
890@item thread_create
891is the address of the
892user-supplied subroutine for the TASK_CREATE extension.  If this
893extension for task creation is defined, it is called from the
894task_create directive.  A value of NULL indicates that no
895extension is provided.
896
897@item thread_start
898is the address of the user-supplied
899subroutine for the TASK_START extension.  If this extension for
900task initiation is defined, it is called from the task_start
901directive.  A value of NULL indicates that no extension is
902provided.
903
904@item thread_restart
905is the address of the user-supplied
906subroutine for the TASK_RESTART extension.  If this extension
907for task re-initiation is defined, it is called from the
908task_restart directive.  A value of NULL indicates that no
909extension is provided.
910
911@item thread_delete
912is the address of the user-supplied
913subroutine for the TASK_DELETE extension.  If this RTEMS
914extension for task deletion is defined, it is called from the
915task_delete directive.  A value of NULL indicates that no
916extension is provided.
917
918@item thread_switch
919is the address of the user-supplied
920subroutine for the task context switch extension.  This
921subroutine is called from RTEMS dispatcher after the current
922task has been swapped out but before the new task has been
923swapped in.  A value of NULL indicates that no extension is
924provided.  As this routine is invoked after saving the current
925task's context and before restoring the heir task's context, it
926is not necessary for this routine to save and restore any
927registers.
928
929@item thread_begin
930is the address of the user-supplied
931subroutine which is invoked immediately before a task begins
932execution.  It is invoked in the context of the beginning task.
933A value of NULL indicates that no extension is provided.
934
935@item thread_exitted
936is the address of the user-supplied
937subroutine which is invoked when a task exits.  This procedure
938is responsible for some action which will allow the system to
939continue execution (i.e. delete or restart the task) or to
940terminate with a fatal error.  If this field is set to NULL, the
941default RTEMS TASK_EXITTED handler will be invoked.
942
943@item fatal
944is the address of the user-supplied
945subroutine for the FATAL extension.  This RTEMS extension of
946fatal error handling is called from the
947@code{@value{DIRPREFIX}fatal_error_occurred}
948directive.  If the user's fatal error handler returns or if this
949entry is NULL then the default RTEMS fatal error handler will be
950executed.
951
952@end table
953
954A typical declaration for a User Extension Table
955which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and
956FATAL extension might appear as follows:
957
958@ifset is-C
959@example
960rtems_extensions_table User_extensions = @{
961   task_create_extension,
962   NULL,
963   NULL,
964   task_delete_extension,
965   task_switch_extension,
966   NULL,
967   NULL,
968   fatal_extension
969@};
970@end example
971@end ifset
972
973@ifset is-Ada
974User_Extensions : RTEMS.Extensions_Table := (
975   Task_Create_Extension'Access,
976   null,
977   null,
978   Task_Delete_Extension'Access,
979   Task_Switch_Extension'Access,
980   null,
981   null,
982   Fatal_Extension'Access
983);
984@example
985
986@end example
987@end ifset
988
989More information regarding the user extensions is
990provided in the User Extensions chapter.
991
992@section Multiprocessor Configuration Table
993
994The Multiprocessor Configuration Table contains
995information needed when using RTEMS in a multiprocessor
996configuration.  Many of the details associated with configuring
997a multiprocessor system are dependent on the multiprocessor
998communications layer provided by the user.  The address of the
999Multiprocessor Configuration Table should be placed in the
1000@code{User_multiprocessing_table} entry in the primary Configuration
1001Table.  Further details regarding many of the entries in the
1002Multiprocessor Configuration Table will be provided in the
1003Multiprocessing chapter. 
1004
1005
1006When using the @code{confdefs.h} mechanism for configuring
1007an RTEMS application, the macro @code{CONFIGURE_MPTEST} must
1008be defined to automatically generate the Multiprocessor Configuration Table.
1009If @code{CONFIGURE_MPTEST}, is not defined, then a NULL pointer
1010is configured as the address of this table.
1011
1012The format of the Multiprocessor Configuration Table is defined in
1013the following @value{LANGUAGE} @value{STRUCTURE}:
1014
1015@ifset is-C
1016@example
1017typedef struct @{
1018  rtems_unsigned32  node;
1019  rtems_unsigned32  maximum_nodes;
1020  rtems_unsigned32  maximum_global_objects;
1021  rtems_unsigned32  maximum_proxies;
1022  rtems_mpci_table *User_mpci_table;
1023@} rtems_multiprocessing_table;
1024@end example
1025@end ifset
1026
1027@ifset is-Ada
1028@example
1029type Multiprocessing_Table is
1030   record
1031      Node                   : RTEMS.Unsigned32;
1032      Maximum_Nodes          : RTEMS.Unsigned32;
1033      Maximum_Global_Objects : RTEMS.Unsigned32;
1034      Maximum_Proxies        : RTEMS.Unsigned32;
1035      User_MPCI_Table        : RTEMS.MPCI_Table_Pointer;
1036   end record;
1037
1038type Multiprocessing_Table_Pointer is access all Multiprocessing_Table;
1039@end example
1040@end ifset
1041
1042@table @b
1043@item node
1044is a unique processor identifier
1045and is used in routing messages between nodes in a
1046multiprocessor configuration.  Each processor must have a unique
1047node number.  RTEMS assumes that node numbers start at one and
1048increase sequentially.  This assumption can be used to advantage
1049by the user-supplied MPCI layer.  Typically, this requirement is
1050made when the node numbers are used to calculate the address of
1051inter-processor communication links.  Zero should be avoided as
1052a node number because some MPCI layers use node zero to
1053represent broadcasted packets.  Thus, it is recommended that
1054node numbers start at one and increase sequentially.
1055When using the @code{confdefs.h} mechanism for configuring
1056an RTEMS application, the value for this field corresponds
1057to the setting of the macro @code{CONFIGURE_MP_NODE_NUMBER}.
1058If not defined by the application, then the @code{CONFIGURE_MP_NODE_NUMBER}
1059macro defaults to the value of the @code{NODE_NUMBER} macro which is
1060set on the compiler command line by the RTEMS Multiprocessing Test Suites.
1061
1062
1063@item maximum_nodes
1064is the number of processor nodes in the system.
1065When using the @code{confdefs.h} mechanism for configuring
1066an RTEMS application, the value for this field corresponds
1067to the setting of the macro @code{CONFIGURE_MP_MAXIMUM_NODES}.
1068If not defined by the application, then the @code{CONFIGURE_MP_MAXIMUM_NODES}
1069macro defaults to the value 2.
1070
1071@item maximum_global_objects
1072is the maximum number of global objects which can exist at any
1073given moment in the entire system.  If this parameter is not the
1074same on all nodes in the system, then a fatal error is generated
1075to inform the user that the system is inconsistent.
1076When using the @code{confdefs.h} mechanism for configuring
1077an RTEMS application, the value for this field corresponds
1078to the setting of the macro @code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS}.
1079If not defined by the application, then the
1080@code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS} macro defaults to the value 32.
1081
1082
1083@item maximum_proxies
1084is the maximum number of proxies which can exist at any given moment
1085on this particular node.  A proxy is a substitute task control block
1086which represent a task residing on a remote node when that task blocks
1087on a remote object.  Proxies are used in situations in which delayed
1088interaction is required with a remote node.
1089When using the @code{confdefs.h} mechanism for configuring
1090an RTEMS application, the value for this field corresponds
1091to the setting of the macro @code{CONFIGURE_MP_MAXIMUM_PROXIES}.
1092If not defined by the application, then the @code{CONFIGURE_MP_MAXIMUM_PROXIES}
1093macro defaults to the value 32.
1094
1095
1096@item User_mpci_table
1097is the address of the Multiprocessor Communications Interface
1098Table.  This table contains the entry points of user-provided functions
1099which constitute the multiprocessor communications layer.  This table
1100must be provided in multiprocessor configurations with all
1101entries configured.  The format of this table and details
1102regarding its entries can be found in the next section.
1103When using the @code{confdefs.h} mechanism for configuring
1104an RTEMS application, the value for this field corresponds
1105to the setting of the macro @code{CONFIGURE_MP_MPCI_TABLE_POINTER}.
1106If not defined by the application, then the
1107@code{CONFIGURE_MP_MPCI_TABLE_POINTER} macro defaults to the
1108address of the table named @code{MPCI_table}.
1109
1110
1111@end table
1112
1113@section Multiprocessor Communications Interface Table
1114
1115This table defines the set of callouts that must be provided by
1116an Multiprocessor Communications Interface implementation. 
1117
1118When using the @code{confdefs.h} mechanism for configuring
1119an RTEMS application, the name of this table is assumed
1120to be @code{MPCI_table} unless the application sets
1121the @code{CONFIGURE_MP_MPCI_TABLE_POINTER} when configuring a
1122multiprocessing system.
1123
1124The format of this table is defined in
1125the following @value{LANGUAGE} @value{STRUCTURE}:
1126
1127@ifset is-C
1128@example
1129typedef struct @{
1130  rtems_unsigned32                 default_timeout; /* in ticks */
1131  rtems_unsigned32                 maximum_packet_size;
1132  rtems_mpci_initialization_entry initialization;
1133  rtems_mpci_get_packet_entry     get_packet;
1134  rtems_mpci_return_packet_entry  return_packet;
1135  rtems_mpci_send_entry           send;
1136  rtems_mpci_receive_entry        receive;
1137@} rtems_mpci_table;
1138@end example
1139@end ifset
1140
1141@ifset is-Ada
1142@example
1143type MPCI_Table is
1144   record
1145      Default_Timeout     : RTEMS.Unsigned32; -- in ticks
1146      Maximum_Packet_Size : RTEMS.Unsigned32;
1147      Initialization      : RTEMS.MPCI_Initialization_Entry;
1148      Get_Packet          : RTEMS.MPCI_Get_Packet_Entry;
1149      Return_Packet       : RTEMS.MPCI_Return_Packet_Entry;
1150      Send                : RTEMS.MPCI_Send_Entry;
1151      Receive             : RTEMS.MPCI_Receive_Entry;
1152   end record;
1153
1154type MPCI_Table_Pointer is access all MPCI_Table;
1155@end example
1156@end ifset
1157
1158@table @b
1159@item default_timeout
1160is the default maximum length of time a task should block waiting for
1161a response to a directive which results in communication with a remote node.
1162The maximum length of time is a function the user supplied
1163multiprocessor communications layer and the media used.  This
1164timeout only applies to directives which would not block if the
1165operation were performed locally.
1166
1167@item maximum_packet_size
1168is the size in bytes of the longest packet which the MPCI layer is capable
1169of sending.  This value should represent the total number of bytes available
1170for a RTEMS interprocessor messages.
1171
1172@item initialization
1173is the address of the entry point for the initialization procedure of the
1174user supplied multiprocessor communications layer.
1175
1176@item get_packet
1177is the address of the entry point for the procedure called by RTEMS to
1178obtain a packet from the user supplied multiprocessor communications layer.
1179
1180@item return_packet
1181is the address of the entry point for the procedure called by RTEMS to
1182return a packet to the user supplied multiprocessor communications layer.
1183
1184@item send
1185is the address of the entry point for the procedure called by RTEMS to
1186send an envelope to another node.  This procedure is part of the user
1187supplied multiprocessor communications layer.
1188
1189@item receive
1190is the address of the entry point for the
1191procedure called by RTEMS to retrieve an envelope containing a
1192message from another node.  This procedure is part of the user
1193supplied multiprocessor communications layer.
1194
1195@end table
1196
1197More information regarding the required functionality of these
1198entry points is provided in the Multiprocessor chapter.
1199
1200@section Determining Memory Requirements
1201
1202Since memory is a critical resource in many real-time
1203embedded systems, the RTEMS Classic API was specifically designed to allow
1204unused managers to be forcibly excluded from the run-time environment.
1205This allows the application designer the flexibility to tailor
1206RTEMS to most efficiently meet system requirements while still
1207satisfying even the most stringent memory constraints.  As
1208result, the size of the RTEMS executive is application
1209dependent.  A Memory Requirements worksheet is provided in the
1210Applications Supplement document for a specific target
1211processor.  This worksheet can be used to calculate the memory
1212requirements of a custom RTEMS run-time environment.  To insure
1213that enough memory is allocated for future versions of RTEMS,
1214the application designer should round these memory requirements
1215up.  The following Classic API managers may be optionally excluded:
1216
1217@itemize @bullet
1218@item signal
1219@item region
1220@item dual ported memory
1221@item event
1222@item multiprocessing
1223@item partition
1224@item timer
1225@item semaphore
1226@item message
1227@item rate monotonic
1228@end itemize
1229
1230RTEMS is designed to be built and installed as a library
1231that is linked into the application.  As such, much of
1232RTEMS is implemented in such a way that there is a single
1233entry point per source file.  This avoids having the
1234linker being forced to pull large object files in their
1235entirety into an application when the application references
1236a single symbol.
1237
1238RTEMS based applications must somehow provide memory
1239for RTEMS' code and data space.  Although RTEMS' data space must
1240be in RAM, its code space can be located in either ROM or RAM.
1241In addition, the user must allocate RAM for the RTEMS RAM
1242Workspace.  The size of this area is application dependent and
1243can be calculated using the formula provided in the Memory
1244Requirements chapter of the Applications Supplement document
1245for a specific target processor.
1246
1247All private RTEMS data variables and routine names used by
1248RTEMS begin with the underscore ( _ ) character followed by an
1249upper-case letter.  If RTEMS is linked with an application, then
1250the application code should NOT contain any symbols which begin
1251with the underscore character and followed by an upper-case
1252letter to avoid any naming conflicts.  All RTEMS directive names
1253should be treated as reserved words.
1254
1255@section Sizing the RTEMS RAM Workspace
1256
1257The RTEMS RAM Workspace is a user-specified block of
1258memory reserved for use by RTEMS.  The application should NOT
1259modify this memory.  This area consists primarily of the RTEMS
1260data structures whose exact size depends upon the values
1261specified in the Configuration Table.  In addition, task stacks
1262and floating point context areas are dynamically allocated from
1263the RTEMS RAM Workspace.
1264
1265The @code{confdefs.h} mechanism calcalutes the size
1266of the RTEMS RAM Workspace automatically.  It assumes that
1267all tasks are floating point and that all will be allocated
1268the miminum stack space.  This calculation also automatically
1269includes the memory that will be allocated for internal use
1270by RTEMS.  The following macros may be set
1271by the application to make the calculation
1272of memory required more accurate:
1273
1274@itemize @bullet
1275
1276CONFIGURE_MEMORY_OVERHEAD
1277CONFIGURE_EXTRA_TASK_STACKS
1278
1279@end itemize
1280
1281The starting address of the RTEMS RAM Workspace must
1282be aligned on a four-byte boundary.  Failure to properly align
1283the workspace area will result in the
1284@code{@value{DIRPREFIX}fatal_error_occurred}
1285directive being invoked with the
1286@code{@value{RPREFIX}INVALID_ADDRESS} error code.
1287
1288A worksheet is provided in the @b{Memory Requirements}
1289chapter of the Applications Supplement document for a specific
1290target processor to assist the user in calculating the minimum
1291size of the RTEMS RAM Workspace for each application.  The value
1292calculated with this worksheet is the minimum value that should
1293be specified as the @code{work_space_size} parameter of the
1294Configuration Table. 
1295
1296The allocation of objects can operate in two modes. The default mode
1297has an object number ceiling. No more than the specified number of
1298objects can be allocated from the RTEMS RAM Workspace. The number of objects
1299specified in the particular API Configuration table fields are
1300allocated at initialisation. The second mode allows the number of
1301objects to grow to use the available free memory in the RTEMS RAM Workspace.
1302
1303The auto-extending mode can be enabled individually for each object
1304type by using the macro @code{rtems_resource_unlimited}. This takes a value
1305as a parameter, and is used to set the object maximum number field in
1306an API Configuration table. The value is an allocation unit size. When
1307RTEMS is required to grow the object table it is grown by this
1308size. The kernel will return the object memory back to the RTEMS RAM Workspace
1309when an object is destroyed. The kernel will only return an allocated
1310block of objects to the RTEMS RAM Workspace if at least half the allocation
1311size of free objects remain allocated. RTEMS always keeps one
1312allocation block of objects allocated. Here is an example of using
1313@code{rtems_resource_unlimited}:
1314
1315@example
1316#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
1317@end example
1318
1319The user is cautioned that future versions of RTEMS may not have the
1320same memory requirements per object. Although the value calculated is
1321suficient for a particular target processor and release of RTEMS,
1322memory usage is subject to change across versions and target
1323processors.  The user is advised to allocate somewhat more memory than
1324the worksheet recommends to insure compatibility with future releases
1325for a specific target processor and other target processors. To avoid
1326problems, the user should recalculate the memory requirements each
1327time one of the following events occurs:
1328
1329@itemize @bullet
1330@item a configuration parameter is modified,
1331@item task or interrupt stack requirements change,
1332@item task floating point attribute is altered,
1333@item RTEMS is upgraded, or
1334@item the target processor is changed.
1335@end itemize
1336
1337Failure to provide enough space in the RTEMS RAM
1338Workspace will result in the
1339@code{@value{DIRPREFIX}fatal_error_occurred} directive
1340being invoked with the appropriate error code.
Note: See TracBrowser for help on using the repository browser.