source: rtems/doc/user/conf.t @ 4fa4ea65

4.104.114.84.95
Last change on this file since 4fa4ea65 was 4fa4ea65, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 27, 1998 at 1:24:21 PM

Added Hitachi SH

  • Property mode set to 100644
File size: 35.0 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@ifinfo
10@node Configuring a System, Configuring a System Configuration Table, EXTENSION_DELETE - Delete a extension set, Top
11@end ifinfo
12@chapter Configuring a System
13@ifinfo
14@menu
15* Configuring a System Configuration Table::
16* Configuring a System RTEMS API Configuration Table::
17* Configuring a System POSIX API Configuration Table::
18* Configuring a System CPU Dependent Information Table::
19* Configuring a System Initialization Task Table::
20* Configuring a System Driver Address Table::
21* Configuring a System User Extensions Table::
22* Configuring a System Multiprocessor Configuration Table::
23* Configuring a System Multiprocessor Communications Interface Table::
24* Configuring a System Determining Memory Requirements::
25* Configuring a System Sizing the RTEMS RAM Workspace::
26@end menu
27@end ifinfo
28
29@ifinfo
30@node Configuring a System Configuration Table, Configuring a System RTEMS API Configuration Table, Configuring a System, Configuring a System
31@end ifinfo
32@section Configuration Table
33
34The RTEMS Configuration Table is used to tailor an
35application for its specific needs.  For example, the user can
36configure the number of device drivers or which APIs may be used.
37THe address of the user-defined Configuration Table is passed as an
38argument to the initialize_executive directive, which MUST be
39the first RTEMS directive called.  The RTEMS Configuration Table
40is defined in the following @value{LANGUAGE} @value{STRUCTURE}:
41
42@ifset is-C
43@example
44@group
45typedef struct @{
46  void                             *work_space_start;
47  rtems_unsigned32                  work_space_size;
48  rtems_unsigned32                  maximum_extensions;
49  rtems_unsigned32                  microseconds_per_tick;
50  rtems_unsigned32                  ticks_per_timeslice;
51  rtems_unsigned32                  maximum_devices;
52  rtems_unsigned32                  number_of_device_drivers;
53  rtems_driver_address_table       *Device_driver_table;
54  rtems_extensions_table           *User_extension_table;
55  rtems_multiprocessing_table      *User_multiprocessing_table;
56  rtems_api_configuration_table    *RTEMS_api_configuration;
57  posix_api_configuration_table    *POSIX_api_configuration;
58@} rtems_configuration_table;
59@end group
60@end example
61@end ifset
62
63@ifset is-Ada
64@example
65type Configuration_Table is
66   record
67       Work_Space_Start           : RTEMS.Address;
68       Work_Space_Size            : RTEMS.Unsigned32;
69       Maximum_Extensions         : RTEMS.Unsigned32;
70       Microseconds_Per_Tick      : RTEMS.Unsigned32;
71       Ticks_Per_Timeslice        : RTEMS.Unsigned32;
72       Maximum_Devices            : RTEMS.Unsigned32;
73       Number_Of_Device_Drivers   : RTEMS.Unsigned32;
74       Device_Driver_Table        : RTEMS.Driver_Address_Table_Pointer;
75       User_Extension_Table       : RTEMS.Extensions_Table_Pointer;
76       User_Multiprocessing_Table : RTEMS.Multiprocessing_Table_Pointer;
77       RTEMS_API_Configuration    : RTEMS.API_Configuration_Table_Pointer;
78       POSIX_API_Configuration    :
79                       RTEMS.POSIX_API_Configuration_Table_Pointer;
80   end record;
81
82type Configuration_Table_Pointer is access all Configuration_Table;
83@end example
84@end ifset
85
86@table @b
87@item work_space_start
88is the address of the RTEMS RAM Workspace. 
89This area contains items such as the
90various object control blocks (TCBs, QCBs, ...) and task stacks.
91If the address is not aligned on a four-word boundary, then
92RTEMS will invoke the fatal error handler during
93initialize_executive.
94
95@item work_space_size
96is the calculated size of the
97RTEMS RAM Workspace.  The section Sizing the RTEMS RAM Workspace
98details how to arrive at this number.
99
100@item microseconds_per_tick
101is number of microseconds per clock tick.
102
103@item ticks_per_timeslice
104is the number of clock ticks for a timeslice.
105
106@item maximum_devices
107is the maximum number of devices that can be registered.
108
109@item number_of_device_drivers
110is the number of device drivers for the system.  There should be
111the same number of entries in the Device Driver Table.  If this field
112is zero, then the User_driver_address_table entry should be NULL.
113
114@item Device_driver_table
115is the address of the Device Driver Table.  This table contains the entry
116points for each device driver.  If the number_of_device_drivers field is zero,
117then this entry should be NULL. The format of this table will be
118discussed below.
119
120@item User_extension_table
121is the address of the User
122Extension Table.  This table contains the entry points for the
123static set of optional user extensions.  If no user extensions
124are configured, then this entry should be NULL.  The format of
125this table will be discussed below.
126
127@item User_multiprocessing_table
128is the address of the Multiprocessor Configuration Table.  This
129table contains information needed by RTEMS only when used in a multiprocessor
130configuration.  This field must be NULL when RTEMS is used in a
131single processor configuration.
132
133@item RTEMS_api_configuration
134is the address of the RTEMS API Configuration Table.  This table
135contains information needed by the RTEMS API.  This field should be
136NULL if the RTEMS API is not used.  [NOTE: Currently the RTEMS API
137is required to support support components such as BSPs and libraries
138which use this API.]
139
140@item POSIX_api_configuration
141is the address of the POSIX API Configuration Table.  This table
142contains information needed by the POSIX API.  This field should be
143NULL if the POSIX API is not used.
144
145@end table
146
147@ifinfo
148@node Configuring a System RTEMS API Configuration Table, Configuring a System POSIX API Configuration Table, Configuring a System Configuration Table, Configuring a System
149@end ifinfo
150@section RTEMS API Configuration Table
151
152The RTEMS API Configuration Table is used to configure the
153managers which constitute the RTEMS API for a particular application. 
154For example, the user can configure the maximum number of tasks for
155this application. The RTEMS API Configuration Table is defined in
156the following @value{LANGUAGE} @value{STRUCTURE}:
157
158@ifset is-C
159@example
160@group
161typedef struct @{
162  rtems_unsigned32                  maximum_tasks;
163  rtems_unsigned32                  maximum_timers;
164  rtems_unsigned32                  maximum_semaphores;
165  rtems_unsigned32                  maximum_message_queues;
166  rtems_unsigned32                  maximum_partitions;
167  rtems_unsigned32                  maximum_regions;
168  rtems_unsigned32                  maximum_ports;
169  rtems_unsigned32                  maximum_periods;
170  rtems_unsigned32                  number_of_initialization_tasks;
171  rtems_initialization_tasks_table *User_initialization_tasks_table;
172@} rtems_api_configuration_table;
173@end group
174@end example
175@end ifset
176
177@ifset is-Ada
178@example
179type API_Configuration_Table is
180   record
181      Maximum_Tasks                   : RTEMS.Unsigned32;
182      Maximum_Timers                  : RTEMS.Unsigned32;
183      Maximum_Semaphores              : RTEMS.Unsigned32;
184      Maximum_Message_queues          : RTEMS.Unsigned32;
185      Maximum_Partitions              : RTEMS.Unsigned32;
186      Maximum_Regions                 : RTEMS.Unsigned32;
187      Maximum_Ports                   : RTEMS.Unsigned32;
188      Maximum_Periods                 : RTEMS.Unsigned32;
189      Number_Of_Initialization_Tasks  : RTEMS.Unsigned32;
190      User_Initialization_Tasks_Table :
191                                RTEMS.Initialization_Tasks_Table_Pointer;
192   end record;
193
194type API_Configuration_Table_Pointer is access all API_Configuration_Table;
195@end example
196@end ifset
197
198@table @b
199@item maximum_tasks
200is the maximum number of tasks that
201can be concurrently active (created) in the system including
202initialization tasks.
203
204@item maximum_timers
205is the maximum number of timers
206that can be concurrently active in the system.
207
208@item maximum_semaphores
209is the maximum number of
210semaphores that can be concurrently active in the system.
211
212@item maximum_message_queues
213is the maximum number of
214message queues that can be concurrently active in the system.
215
216@item maximum_partitions
217is the maximum number of
218partitions that can be concurrently active in the system.
219
220@item maximum_regions
221is the maximum number of regions
222that can be concurrently active in the system.
223
224@item maximum_ports
225is the maximum number of ports into
226dual-port memory areas that can be concurrently active in the
227system.
228
229@item number_of_initialization_tasks
230is the number of initialization tasks configured.  At least one
231initialization task must be configured.
232
233@item User_initialization_tasks_table
234is the address of the Initialization Task Table. This table contains the
235information needed to create and start each of the
236initialization tasks.  The format of this table will be discussed below.
237
238@end table
239
240@ifinfo
241@node Configuring a System POSIX API Configuration Table, Configuring a System CPU Dependent Information Table, Configuring a System RTEMS API Configuration Table, Configuring a System
242@end ifinfo
243@section POSIX API Configuration Table
244
245The POSIX API Configuration Table is used to configure the
246managers which constitute the POSIX API for a particular application.
247For example, the user can configure the maximum number of threads for
248this application. The POSIX API Configuration Table is defined in
249the following @value{LANGUAGE} @value{STRUCTURE}:
250 
251@ifset is-C
252@example
253@group
254typedef struct @{
255  void       *(*thread_entry)(void *);
256@} posix_initialization_threads_table;
257 
258typedef struct @{
259  int                                 maximum_threads;
260  int                                 maximum_mutexes;
261  int                                 maximum_condition_variables;
262  int                                 maximum_keys;
263  int                                 maximum_queued_signals;
264  int                                 number_of_initialization_tasks;
265  posix_initialization_threads_table *User_initialization_tasks_table;
266@} posix_api_configuration_table;
267@end group
268@end example
269@end ifset
270
271@ifset is-Ada
272@example
273   type POSIX_Thread_Entry is access procedure (
274      Argument : in     RTEMS.Address
275   );
276
277   type POSIX_Initialization_Threads_Table_Entry is
278   record
279      Thread_Entry : RTEMS.POSIX_Thread_Entry;
280   end record;
281
282   type POSIX_Initialization_Threads_Table is array
283       ( RTEMS.Unsigned32 range <> ) of
284       RTEMS.POSIX_Initialization_Threads_Table_Entry;
285
286   type POSIX_Initialization_Threads_Table_Pointer is access all
287       POSIX_Initialization_Threads_Table;
288
289   type POSIX_API_Configuration_Table_Entry is
290      record
291         Maximum_Threads                 : Interfaces.C.Int;
292         Maximum_Mutexes                 : Interfaces.C.Int;
293         Maximum_Condition_Variables     : Interfaces.C.Int;
294         Maximum_Keys                    : Interfaces.C.Int;
295         Maximum_Queued_Signals          : Interfaces.C.Int;
296         Number_Of_Initialization_Tasks  : Interfaces.C.Int;
297         User_Initialization_Tasks_Table :
298            RTEMS.POSIX_Initialization_Threads_Table_Pointer;
299      end record;
300
301   type POSIX_API_Configuration_Table is array ( RTEMS.Unsigned32 range <> ) of
302      RTEMS.POSIX_API_Configuration_Table_Entry;
303
304   type POSIX_API_Configuration_Table_Pointer is access all
305          RTEMS.POSIX_API_Configuration_Table;
306@end example
307@end ifset
308 
309@table @b
310@item maximum_threads
311is the maximum number of threads that
312can be concurrently active (created) in the system including
313initialization threads.
314
315@item maximum_mutexes
316is the maximum number of mutexes that can be concurrently
317active in the system.
318
319@item maximum_condition_variables
320is the maximum number of condition variables that can be
321concurrently active in the system.
322
323@item maximum_keys
324is the maximum number of keys that can be concurrently active in the system.
325
326@item maximum_queued_signals
327is the maximum number of queued signals that can be concurrently
328pending in the system.
329
330@item number_of_initialization_threads
331is the number of initialization threads configured.  At least one
332initialization threads must be configured.
333 
334@item User_initialization_threads_table
335is the address of the Initialization Threads Table. This table contains the
336information needed to create and start each of the initialization threads. 
337The format of each entry in this table is defined in the
338posix_initialization_threads_table @value{STRUCTURE}.
339
340@end table
341
342@ifinfo
343@node Configuring a System CPU Dependent Information Table, Configuring a System Initialization Task Table, Configuring a System POSIX API Configuration Table, Configuring a System
344@end ifinfo
345@section CPU Dependent Information Table
346
347The CPU Dependent Information Table is used to
348describe processor dependent information required by RTEMS.
349This table is generally used to supply RTEMS with information
350only known by the Board Support Package.  The contents of this
351table are discussed in the CPU Dependent Information Table
352chapter of the Applications Supplement document for a specific
353target processor.
354
355@ifinfo
356@node Configuring a System Initialization Task Table, Configuring a System Driver Address Table, Configuring a System CPU Dependent Information Table, Configuring a System
357@end ifinfo
358@section Initialization Task Table
359
360The Initialization Task Table is used to describe
361each of the user initialization tasks to the Initialization
362Manager.  The table contains one entry for each initialization
363task the user wishes to create and start.  The fields of this
364data structure directly correspond to arguments to the
365task_create and task_start directives.  The number of entries is
366found in the number_of_initialization_tasks entry in the
367Configuration Table.  The format of each entry in the
368Initialization Task Table is defined in the following @value{LANGUAGE}
369@value{STRUCTURE}:
370
371@ifset is-C
372@example
373typedef struct @{
374  rtems_name           name;
375  rtems_unsigned32     stack_size;
376  rtems_task_priority  initial_priority;
377  rtems_attribute      attribute_set;
378  rtems_task_entry     entry_point;
379  rtems_mode           mode_set;
380  rtems_task_argument  argument;
381@} rtems_initialization_tasks_table;
382@end example
383@end ifset
384
385@ifset is-Ada
386@example
387type Initialization_Tasks_Table_Entry is
388   record
389      Name             : RTEMS.Name;          -- task name
390      Stack_Size       : RTEMS.Unsigned32;    -- task stack size
391      Initial_Priority : RTEMS.Task_priority; -- task priority
392      Attribute_Set    : RTEMS.Attribute;     -- task attributes
393      Entry_Point      : RTEMS.Task_Entry;    -- task entry point
394      Mode_Set         : RTEMS.Mode;          -- task initial mode
395      Argument         : RTEMS.Unsigned32;    -- task argument
396   end record;
397
398type Initialization_Tasks_Table is array ( RTEMS.Unsigned32 range <> ) of
399  RTEMS.Initialization_Tasks_Table_Entry;
400
401type Initialization_Tasks_Table_Pointer is access all
402     Initialization_Tasks_Table;
403@end example
404@end ifset
405
406@table @b
407@item name
408is the name of this initialization task.
409
410@item stack_size
411is the size of the stack for this initialization task.
412
413@item initial_priority
414is the priority of this initialization task.
415
416@item attribute_set
417is the attribute set used during creation of this initialization task.
418
419@item entry_point
420is the address of the entry point of this initialization task.
421
422@item mode_set
423is the initial execution mode of this initialization task.
424
425@item argument
426is the initial argument for this initialization task.
427
428@end table
429
430A typical declaration for an Initialization Task Table might appear as follows:
431
432@ifset is-C
433@example
434rtems_initialization_tasks_table
435Initialization_tasks[2] = @{
436   @{ INIT_1_NAME,
437     1024,
438     1,
439     DEFAULT_ATTRIBUTES,
440     Init_1,
441     DEFAULT_MODES,
442     1
443
444   @},
445   @{ INIT_2_NAME,
446     1024,
447     250,
448     FLOATING_POINT,
449     Init_2,
450     NO_PREEMPT,
451     2
452
453   @}
454@};
455@end example
456@end ifset
457
458@ifset is-Ada
459@example
460Initialization_Tasks : aliased RTEMS.Initialization_Tasks_Table( 1 .. 2 ) := (
461   (INIT_1_NAME,
462    1024,
463    1,
464    RTEMS.Default_Attributes,
465    Init_1'Access,
466    RTEMS.Default_Modes,
467    1),
468   (INIT_2_NAME,
469    1024,
470    250,
471    RTEMS.Floating_Point,
472    Init_2'Access,
473    RTEMS.No_Preempt,
474    2)
475);
476@end example
477@end ifset
478
479@ifinfo
480@node Configuring a System Driver Address Table, Configuring a System User Extensions Table, Configuring a System Initialization Task Table, Configuring a System
481@end ifinfo
482@section Driver Address Table
483
484The Device Driver Table is used to inform the I/O
485Manager of the set of entry points for each device driver
486configured in the system.  The table contains one entry for each
487device driver required by the application.  The number of
488entries is defined in the number_of_device_drivers entry in the
489Configuration Table.  The format of each entry in the Device
490Driver Table is defined in
491the following @value{LANGUAGE} @value{STRUCTURE}:
492
493@ifset is-C
494@example
495typedef struct @{
496  rtems_device_driver_entry initialization;
497  rtems_device_driver_entry open;
498  rtems_device_driver_entry close;
499  rtems_device_driver_entry read;
500  rtems_device_driver_entry write;
501  rtems_device_driver_entry control;
502@} rtems_driver_address_table;
503@end example
504@end ifset
505
506@ifset is-Ada
507@example
508type Driver_Address_Table_Entry is
509   record
510      Initialization : RTEMS.Device_Driver_Entry;
511      Open           : RTEMS.Device_Driver_Entry;
512      Close          : RTEMS.Device_Driver_Entry;
513      Read           : RTEMS.Device_Driver_Entry;
514      Write          : RTEMS.Device_Driver_Entry;
515      Control        : RTEMS.Device_Driver_Entry;
516   end record;
517
518type Driver_Address_Table is array ( RTEMS.Unsigned32 range <> ) of
519  RTEMS.Driver_Address_Table_Entry;
520
521type Driver_Address_Table_Pointer is access all Driver_Address_Table;
522@end example
523@end ifset
524
525@table @b
526@item initialization
527is the address of the entry point called by io_initialize
528to initialize a device driver and its associated devices.
529
530@item open
531is the address of the entry point called by io_open.
532
533@item close
534is the address of the entry point called by io_close.
535
536@item read
537is the address of the entry point called by io_read.
538
539@item write
540is the address of the entry point called by io_write.
541
542@item control
543is the address of the entry point called by io_control.
544
545@end table
546
547Driver entry points configured as NULL will always
548return a status code of @code{@value{RPREFIX}SUCCESSFUL}.  No user code will be
549executed in this situation.
550
551A typical declaration for a Device Driver Table might appear as follows:
552
553@ifset is-C
554@example
555rtems_driver_address_table Driver_table[2] = @{
556   @{ tty_initialize, tty_open,  tty_close,  /* major = 0 */
557     tty_read,       tty_write, tty_control
558   @},
559   @{ lp_initialize, lp_open,    lp_close,   /* major = 1 */
560     NULL,          lp_write,   lp_control
561   @}
562@};
563@end example
564@end ifset
565
566@ifset is-Ada
567@example
568@end example
569@end ifset
570
571More information regarding the construction and
572operation of device drivers is provided in the I/O Manager
573chapter.
574
575@ifinfo
576@node Configuring a System User Extensions Table, Configuring a System Multiprocessor Configuration Table, Configuring a System Driver Address Table, Configuring a System
577@end ifinfo
578@section User Extensions Table
579
580The User Extensions Table is used to inform RTEMS of
581the optional user-supplied static extension set.  This table
582contains one entry for each possible extension.  The entries are
583called at critical times in the life of the system and
584individual tasks.  The application may create dynamic extensions
585in addition to this single static set.  The format of each entry
586in the User Extensions Table is defined in the following @value{LANGUAGE}
587@value{STRUCTURE}:
588
589@ifset is-C
590@example
591typedef User_extensions_routine                   rtems_extension;
592typedef User_extensions_thread_create_extension   rtems_task_create_extension;
593typedef User_extensions_thread_delete_extension   rtems_task_delete_extension;
594typedef User_extensions_thread_start_extension    rtems_task_start_extension;
595typedef User_extensions_thread_restart_extension  rtems_task_restart_extension;
596typedef User_extensions_thread_switch_extension   rtems_task_switch_extension;
597typedef User_extensions_thread_begin_extension    rtems_task_begin_extension;
598typedef User_extensions_thread_exitted_extension  rtems_task_exitted_extension;
599typedef User_extensions_fatal_extension           rtems_fatal_extension;
600
601typedef User_extensions_Table                     rtems_extensions_table;
602
603typedef struct @{
604  rtems_task_create_extension      thread_create;
605  rtems_task_start_extension       thread_start;
606  rtems_task_restart_extension     thread_restart;
607  rtems_task_delete_extension      thread_delete;
608  rtems_task_switch_extension      thread_switch;
609  rtems_task_post_switch_extension thread_post_switch;
610  rtems_task_begin_extension       thread_begin;
611  rtems_task_exitted_extension     thread_exitted;
612  rtems_fatal_extension            fatal;
613@} User_extensions_Table;
614@end example
615@end ifset
616
617@ifset is-Ada
618@example
619type Extensions_Table_Entry is
620   record
621      Thread_Create      : RTEMS.Thread_Create_Extension;
622      Thread_Start       : RTEMS.Thread_Start_Extension;
623      Thread_Restart     : RTEMS.Thread_Restart_Extension;
624      Thread_Delete      : RTEMS.Thread_Delete_Extension;
625      Thread_Switch      : RTEMS.Thread_Switch_Extension;
626      Thread_Post_Switch : RTEMS.Thread_Post_Switch_Extension;
627      Thread_Begin       : RTEMS.Thread_Begin_Extension;
628      Thread_Exitted     : RTEMS.Thread_Exitted_Extension;
629      Fatal            : RTEMS.Fatal_Error_Extension;
630   end record;
631@end example
632@end ifset
633
634@table @b
635
636@item thread_create
637is the address of the
638user-supplied subroutine for the TASK_CREATE extension.  If this
639extension for task creation is defined, it is called from the
640task_create directive.  A value of NULL indicates that no
641extension is provided.
642
643@item thread_start
644is the address of the user-supplied
645subroutine for the TASK_START extension.  If this extension for
646task initiation is defined, it is called from the task_start
647directive.  A value of NULL indicates that no extension is
648provided.
649
650@item thread_restart
651is the address of the user-supplied
652subroutine for the TASK_RESTART extension.  If this extension
653for task re-initiation is defined, it is called from the
654task_restart directive.  A value of NULL indicates that no
655extension is provided.
656
657@item thread_delete
658is the address of the user-supplied
659subroutine for the TASK_DELETE extension.  If this RTEMS
660extension for task deletion is defined, it is called from the
661task_delete directive.  A value of NULL indicates that no
662extension is provided.
663
664@item thread_switch
665is the address of the user-supplied
666subroutine for the task context switch extension.  This
667subroutine is called from RTEMS dispatcher after the current
668task has been swapped out but before the new task has been
669swapped in.  A value of NULL indicates that no extension is
670provided.  As this routine is invoked after saving the current
671task's context and before restoring the heir task's context, it
672is not necessary for this routine to save and restore any
673registers.
674
675@item thread_post_switch
676is the address of the
677user-supplied subroutine for the post task context switch
678extension.  This subroutine is called from RTEMS dispatcher in
679the context of the task which has just been swapped in.
680
681@item thread_begin
682is the address of the user-supplied
683subroutine which is invoked immediately before a task begins
684execution.  It is invoked in the context of the beginning task.
685A value of NULL indicates that no extension is provided.
686
687@item thread_exitted
688is the address of the user-supplied
689subroutine which is invoked when a task exits.  This procedure
690is responsible for some action which will allow the system to
691continue execution (i.e. delete or restart the task) or to
692terminate with a fatal error.  If this field is set to NULL, the
693default RTEMS task_exitted handler will be invoked.
694
695@item fatal
696is the address of the user-supplied
697subroutine for the FATAL extension.  This RTEMS extension of
698fatal error handling is called from the fatal_error_occurred
699directive.  If the user's fatal error handler returns or if this
700entry is NULL then the default RTEMS fatal error handler will be
701executed.
702
703@end table
704
705A typical declaration for a User Extension Table
706which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and
707FATAL extension might appear as follows:
708
709@ifset is-C
710@example
711rtems_extensions_table User_extensions = @{
712   task_create_extension,
713   NULL,
714   NULL,
715   task_delete_extension,
716   task_switch_extension,
717   NULL,
718   NULL,
719   fatal_extension
720@};
721@end example
722@end ifset
723
724@ifset is-Ada
725User_Extensions : RTEMS.Extensions_Table := (
726   Task_Create_Extension'Access,
727   null,
728   null,
729   Task_Delete_Extension'Access,
730   Task_Switch_Extension'Access,
731   null,
732   null,
733   Fatal_Extension'Access
734);
735@example
736
737@end example
738@end ifset
739
740More information regarding the user extensions is
741provided in the User Extensions chapter.
742
743@ifinfo
744@node Configuring a System Multiprocessor Configuration Table, Configuring a System Multiprocessor Communications Interface Table, Configuring a System User Extensions Table, Configuring a System
745@end ifinfo
746@section Multiprocessor Configuration Table
747
748The Multiprocessor Configuration Table contains
749information needed when using RTEMS in a multiprocessor
750configuration.  Many of the details associated with configuring
751a multiprocessor system are dependent on the multiprocessor
752communications layer provided by the user.  The address of the
753Multiprocessor Configuration Table should be placed in the
754User_multiprocessing_table entry in the primary Configuration
755Table.  Further details regarding many of the entries in the
756Multiprocessor Configuration Table will be provided in the
757Multiprocessing chapter.  The format of the Multiprocessor
758Configuration Table is defined in
759the following @value{LANGUAGE} @value{STRUCTURE}:
760
761@ifset is-C
762@example
763typedef struct @{
764  rtems_unsigned32  node;
765  rtems_unsigned32  maximum_nodes;
766  rtems_unsigned32  maximum_global_objects;
767  rtems_unsigned32  maximum_proxies;
768  rtems_mpci_table *User_mpci_table;
769@} rtems_multiprocessing_table;
770@end example
771@end ifset
772
773@ifset is-Ada
774@example
775type Multiprocessing_Table is
776   record
777      Node                   : RTEMS.Unsigned32;
778      Maximum_Nodes          : RTEMS.Unsigned32;
779      Maximum_Global_Objects : RTEMS.Unsigned32;
780      Maximum_Proxies        : RTEMS.Unsigned32;
781      User_MPCI_Table        : RTEMS.MPCI_Table_Pointer;
782   end record;
783
784type Multiprocessing_Table_Pointer is access all Multiprocessing_Table;
785@end example
786@end ifset
787
788@table @b
789@item node
790is a unique processor identifier
791and is used in routing messages between nodes in a
792multiprocessor configuration.  Each processor must have a unique
793node number.  RTEMS assumes that node numbers start at one and
794increase sequentially.  This assumption can be used to advantage
795by the user-supplied MPCI layer.  Typically, this requirement is
796made when the node numbers are used to calculate the address of
797inter-processor communication links.  Zero should be avoided as
798a node number because some MPCI layers use node zero to
799represent broadcasted packets.  Thus, it is recommended that
800node numbers start at one and increase sequentially.
801
802@item maximum_nodes
803is the number of processor nodes in the system.
804
805@item maximum_global_objects
806is the maximum number of global objects which can exist at any
807given moment in the entire system.  If this parameter is not the
808same on all nodes in the system, then a fatal error is generated
809to inform the user that the system is inconsistent.
810
811@item maximum_proxies
812is the maximum number of proxies which can exist at any given moment
813on this particular node.  A proxy is a substitute task control block
814which represent a task residing on a remote node when that task blocks
815on a remote object.  Proxies are used in situations in which delayed
816interaction is required with a remote node.
817
818@item User_mpci_table
819is the address of the Multiprocessor Communications Interface
820Table.  This table contains the entry points of user-provided functions
821which constitute the multiprocessor communications layer.  This table
822must be provided in multiprocessor configurations with all
823entries configured.  The format of this table and details
824regarding its entries can be found in the next section.
825
826@end table
827
828@ifinfo
829@node Configuring a System Multiprocessor Communications Interface Table, Configuring a System Determining Memory Requirements, Configuring a System Multiprocessor Configuration Table, Configuring a System
830@end ifinfo
831@section Multiprocessor Communications Interface Table
832
833The format of this table is defined in
834the following @value{LANGUAGE} @value{STRUCTURE}:
835
836@ifset is-C
837@example
838typedef struct @{
839  rtems_unsigned32                 default_timeout; /* in ticks */
840  rtems_unsigned32                 maximum_packet_size;
841  rtems_mpci_initialization_entry initialization;
842  rtems_mpci_get_packet_entry     get_packet;
843  rtems_mpci_return_packet_entry  return_packet;
844  rtems_mpci_send_entry           send;
845  rtems_mpci_receive_entry        receive;
846@} rtems_mpci_table;
847@end example
848@end ifset
849
850@ifset is-Ada
851@example
852type MPCI_Table is
853   record
854      Default_Timeout     : RTEMS.Unsigned32; -- in ticks
855      Maximum_Packet_Size : RTEMS.Unsigned32;
856      Initialization      : RTEMS.MPCI_Initialization_Entry;
857      Get_Packet          : RTEMS.MPCI_Get_Packet_Entry;
858      Return_Packet       : RTEMS.MPCI_Return_Packet_Entry;
859      Send                : RTEMS.MPCI_Send_Entry;
860      Receive             : RTEMS.MPCI_Receive_Entry;
861   end record;
862
863type MPCI_Table_Pointer is access all MPCI_Table;
864@end example
865@end ifset
866
867@table @b
868@item default_timeout
869is the default maximum length of time a task should block waiting for
870a response to a directive which results in communication with a remote node.
871The maximum length of time is a function the user supplied
872multiprocessor communications layer and the media used.  This
873timeout only applies to directives which would not block if the
874operation were performed locally.
875
876@item maximum_packet_size
877is the size in bytes of the longest packet which the MPCI layer is capable
878of sending.  This value should represent the total number of bytes available
879for a RTEMS interprocessor messages.
880
881@item initialization
882is the address of the entry point for the initialization procedure of the
883user supplied multiprocessor communications layer.
884
885@item get_packet
886is the address of the entry point for the procedure called by RTEMS to
887obtain a packet from the user supplied multiprocessor communications layer.
888
889@item return_packet
890is the address of the entry point for the procedure called by RTEMS to
891return a packet to the user supplied multiprocessor communications layer.
892
893@item send
894is the address of the entry point for the procedure called by RTEMS to
895send an envelope to another node.  This procedure is part of the user
896supplied multiprocessor communications layer.
897
898@item receive
899is the address of the entry point for the
900procedure called by RTEMS to retrieve an envelope containing a
901message from another node.  This procedure is part of the user
902supplied multiprocessor communications layer.
903
904@end table
905
906More information regarding the required functionality of these
907entry points is provided in the Multiprocessor chapter.
908
909@ifinfo
910@node Configuring a System Determining Memory Requirements, Configuring a System Sizing the RTEMS RAM Workspace, Configuring a System Multiprocessor Communications Interface Table, Configuring a System
911@end ifinfo
912@section Determining Memory Requirements
913
914Since memory is a critical resource in many real-time
915embedded systems, RTEMS was specifically designed to allow
916unused managers to be excluded from the run-time environment.
917This allows the application designer the flexibility to tailor
918RTEMS to most efficiently meet system requirements while still
919satisfying even the most stringent memory constraints.  As
920result, the size of the RTEMS executive is application
921dependent.  A Memory Requirements worksheet is provided in the
922Applications Supplement document for a specific target
923processor.  This worksheet can be used to calculate the memory
924requirements of a custom RTEMS run-time environment.  To insure
925that enough memory is allocated for future versions of RTEMS,
926the application designer should round these memory requirements
927up.  The following managers may be optionally excluded:
928
929@itemize @bullet
930@item signal
931@item region
932@item dual ported memory
933@item event
934@item multiprocessing
935@item partition
936@item timer
937@item semaphore
938@item message
939@item rate monotonic
940@end itemize
941
942RTEMS based applications must somehow provide memory
943for RTEMS' code and data space.  Although RTEMS' data space must
944be in RAM, its code space can be located in either ROM or RAM.
945In addition, the user must allocate RAM for the RTEMS RAM
946Workspace.  The size of this area is application dependent and
947can be calculated using the formula provided in the Memory
948Requirements chapter of the Applications Supplement document
949for a specific target processor.
950
951All RTEMS data variables and routine names used by
952RTEMS begin with the underscore ( _ ) character followed by an
953upper-case letter.  If RTEMS is linked with an application, then
954the application code should NOT contain any symbols which begin
955with the underscore character and followed by an upper-case
956letter to avoid any naming conflicts.  All RTEMS directive names
957should be treated as reserved words.
958
959@ifinfo
960@node Configuring a System Sizing the RTEMS RAM Workspace, Multiprocessing Manager, Configuring a System Determining Memory Requirements, Configuring a System
961@end ifinfo
962@section Sizing the RTEMS RAM Workspace
963
964The RTEMS RAM Workspace is a user-specified block of
965memory reserved for use by RTEMS.  The application should NOT
966modify this memory.  This area consists primarily of the RTEMS
967data structures whose exact size depends upon the values
968specified in the Configuration Table.  In addition, task stacks
969and floating point context areas are dynamically allocated from
970the RTEMS RAM Workspace.
971
972The starting address of the RTEMS RAM Workspace must
973be aligned on a four-byte boundary.  Failure to properly align
974the workspace area will result in the fatal_error_occurred
975directive being invoked with the @code{@value{RPREFIX}INVALID_ADDRESS} error code.
976
977A worksheet is provided in the Memory Requirements
978chapter of the Applications Supplement document for a specific
979target processor to assist the user in calculating the minimum
980size of the RTEMS RAM Workspace for each application.  The value
981calculated with this worksheet is the minimum value that should
982be specified as the work_space_size parameter of the
983Configuration Table.  The user is cautioned that future versions
984of RTEMS may not have the same memory requirements per object.
985Although the value calculated is sufficient for a particular
986target processor and release of RTEMS, memory usage is subject
987to change across versions and target processors.  The user is
988advised to allocate somewhat more memory than the worksheet
989recommends to insure compatibility with future releases for a
990specific target processor and other target processors.  To avoid
991problems, the user should recalculate the memory requirements
992each time one of the following events occurs:
993
994@itemize @bullet
995@item a configuration parameter is modified,
996@item task or interrupt stack requirements change,
997@item task floating point attribute is altered,
998@item RTEMS is upgraded, or
999@item the target processor is changed.
1000@end itemize
1001
1002Failure to provide enough space in the RTEMS RAM
1003Workspace will result in the fatal_error_occurred directive
1004being invoked with the appropriate error code.
Note: See TracBrowser for help on using the repository browser.