source: rtems/doc/user/conf.t @ 20515fc

4.104.114.84.9
Last change on this file since 20515fc was 20515fc, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 27, 1998 at 6:53:17 PM

Nodes, menus, etc are automatically generated now

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