source: rtems/doc/user/conf.t @ 94c0943

4.104.114.84.95
Last change on this file since 94c0943 was 94c0943, checked in by Joel Sherrill <joel.sherrill@…>, on 12/17/98 at 18:21:39

Corrected information about the post_switch extension.

  • Property mode set to 100644
File size: 32.5 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_unsigned32                  number_of_initial_extensions;
35  rtems_extensions_table           *User_extension_table;
36  rtems_multiprocessing_table      *User_multiprocessing_table;
37  rtems_api_configuration_table    *RTEMS_api_configuration;
38  posix_api_configuration_table    *POSIX_api_configuration;
39@} rtems_configuration_table;
40@end group
41@end example
42@end ifset
43
44@ifset is-Ada
45@example
46type Configuration_Table is
47   record
48       Work_Space_Start             : RTEMS.Address;
49       Work_Space_Size              : RTEMS.Unsigned32;
50       Maximum_Extensions           : RTEMS.Unsigned32;
51       Microseconds_Per_Tick        : RTEMS.Unsigned32;
52       Ticks_Per_Timeslice          : RTEMS.Unsigned32;
53       Maximum_Devices              : RTEMS.Unsigned32;
54       Number_Of_Device_Drivers     : RTEMS.Unsigned32;
55       Device_Driver_Table          : RTEMS.Driver_Address_Table_Pointer;
56       Number_Of_Initial_Extensions : RTEMS.Unsigned32;
57       User_Extension_Table         : RTEMS.Extensions_Table_Pointer;
58       User_Multiprocessing_Table   : RTEMS.Multiprocessing_Table_Pointer;
59       RTEMS_API_Configuration      : RTEMS.API_Configuration_Table_Pointer;
60       POSIX_API_Configuration      :
61                       RTEMS.POSIX_API_Configuration_Table_Pointer;
62   end record;
63
64type Configuration_Table_Pointer is access all Configuration_Table;
65@end example
66@end ifset
67
68@table @b
69@item work_space_start
70is the address of the RTEMS RAM Workspace. 
71This area contains items such as the
72various object control blocks (TCBs, QCBs, ...) and task stacks.
73If the address is not aligned on a four-word boundary, then
74RTEMS will invoke the fatal error handler during
75@code{@value{DIRPREFIX}initialize_executive}.
76
77@item work_space_size
78is the calculated size of the
79RTEMS RAM Workspace.  The section Sizing the RTEMS RAM Workspace
80details how to arrive at this number.
81
82@item microseconds_per_tick
83is number of microseconds per clock tick.
84
85@item ticks_per_timeslice
86is the number of clock ticks for a timeslice.
87
88@item maximum_devices
89is the maximum number of devices that can be registered.
90
91@item number_of_device_drivers
92is the number of device drivers for the system.  There should be
93the same number of entries in the Device Driver Table.  If this field
94is zero, then the User_driver_address_table entry should be NULL.
95
96@item Device_driver_table
97is the address of the Device Driver Table.  This table contains the entry
98points for each device driver.  If the number_of_device_drivers field is zero,
99then this entry should be NULL. The format of this table will be
100discussed below.
101
102@item number_of_initial_extensions
103is the number of initial user extensions.  There should be
104the same number of entries as in the User_extension_table.  If this field
105is zero, then the User_driver_address_table entry should be NULL.
106
107@item User_extension_table
108is the address of the User
109Extension Table.  This table contains the entry points for the
110static set of optional user extensions.  If no user extensions
111are configured, then this entry should be NULL.  The format of
112this table will be discussed below.
113
114@item User_multiprocessing_table
115is the address of the Multiprocessor Configuration Table.  This
116table contains information needed by RTEMS only when used in a multiprocessor
117configuration.  This field must be NULL when RTEMS is used in a
118single processor configuration.
119
120@item RTEMS_api_configuration
121is the address of the RTEMS API Configuration Table.  This table
122contains information needed by the RTEMS API.  This field should be
123NULL if the RTEMS API is not used.  [NOTE: Currently the RTEMS API
124is required to support support components such as BSPs and libraries
125which use this API.]
126
127@item POSIX_api_configuration
128is the address of the POSIX API Configuration Table.  This table
129contains information needed by the POSIX API.  This field should be
130NULL if the POSIX API is not used.
131
132@end table
133
134@section RTEMS API Configuration Table
135
136The RTEMS API Configuration Table is used to configure the
137managers which constitute the RTEMS API for a particular application. 
138For example, the user can configure the maximum number of tasks for
139this application. The RTEMS API Configuration Table is defined in
140the following @value{LANGUAGE} @value{STRUCTURE}:
141
142@ifset is-C
143@example
144@group
145typedef struct @{
146  rtems_unsigned32                  maximum_tasks;
147  rtems_unsigned32                  maximum_timers;
148  rtems_unsigned32                  maximum_semaphores;
149  rtems_unsigned32                  maximum_message_queues;
150  rtems_unsigned32                  maximum_partitions;
151  rtems_unsigned32                  maximum_regions;
152  rtems_unsigned32                  maximum_ports;
153  rtems_unsigned32                  maximum_periods;
154  rtems_unsigned32                  number_of_initialization_tasks;
155  rtems_initialization_tasks_table *User_initialization_tasks_table;
156@} rtems_api_configuration_table;
157@end group
158@end example
159@end ifset
160
161@ifset is-Ada
162@example
163type API_Configuration_Table is
164   record
165      Maximum_Tasks                   : RTEMS.Unsigned32;
166      Maximum_Timers                  : RTEMS.Unsigned32;
167      Maximum_Semaphores              : RTEMS.Unsigned32;
168      Maximum_Message_queues          : RTEMS.Unsigned32;
169      Maximum_Partitions              : RTEMS.Unsigned32;
170      Maximum_Regions                 : RTEMS.Unsigned32;
171      Maximum_Ports                   : RTEMS.Unsigned32;
172      Maximum_Periods                 : RTEMS.Unsigned32;
173      Number_Of_Initialization_Tasks  : RTEMS.Unsigned32;
174      User_Initialization_Tasks_Table :
175                                RTEMS.Initialization_Tasks_Table_Pointer;
176   end record;
177
178type API_Configuration_Table_Pointer is access all API_Configuration_Table;
179@end example
180@end ifset
181
182@table @b
183@item maximum_tasks
184is the maximum number of tasks that
185can be concurrently active (created) in the system including
186initialization tasks.
187
188@item maximum_timers
189is the maximum number of timers
190that can be concurrently active in the system.
191
192@item maximum_semaphores
193is the maximum number of
194semaphores that can be concurrently active in the system.
195
196@item maximum_message_queues
197is the maximum number of
198message queues that can be concurrently active in the system.
199
200@item maximum_partitions
201is the maximum number of
202partitions that can be concurrently active in the system.
203
204@item maximum_regions
205is the maximum number of regions
206that can be concurrently active in the system.
207
208@item maximum_ports
209is the maximum number of ports into
210dual-port memory areas that can be concurrently active in the
211system.
212
213@item number_of_initialization_tasks
214is the number of initialization tasks configured.  At least one
215initialization task must be configured.
216
217@item User_initialization_tasks_table
218is the address of the Initialization Task Table. This table contains the
219information needed to create and start each of the
220initialization tasks.  The format of this table will be discussed below.
221
222@end table
223
224@section POSIX API Configuration Table
225
226The POSIX API Configuration Table is used to configure the
227managers which constitute the POSIX API for a particular application.
228For example, the user can configure the maximum number of threads for
229this application. The POSIX API Configuration Table is defined in
230the following @value{LANGUAGE} @value{STRUCTURE}:
231 
232@ifset is-C
233@example
234@group
235typedef struct @{
236  void       *(*thread_entry)(void *);
237@} posix_initialization_threads_table;
238 
239typedef struct @{
240  int                                 maximum_threads;
241  int                                 maximum_mutexes;
242  int                                 maximum_condition_variables;
243  int                                 maximum_keys;
244  int                                 maximum_queued_signals;
245  int                                 number_of_initialization_tasks;
246  posix_initialization_threads_table *User_initialization_tasks_table;
247@} posix_api_configuration_table;
248@end group
249@end example
250@end ifset
251
252@ifset is-Ada
253@example
254   type POSIX_Thread_Entry is access procedure (
255      Argument : in     RTEMS.Address
256   );
257
258   type POSIX_Initialization_Threads_Table_Entry is
259   record
260      Thread_Entry : RTEMS.POSIX_Thread_Entry;
261   end record;
262
263   type POSIX_Initialization_Threads_Table is array
264       ( RTEMS.Unsigned32 range <> ) of
265       RTEMS.POSIX_Initialization_Threads_Table_Entry;
266
267   type POSIX_Initialization_Threads_Table_Pointer is access all
268       POSIX_Initialization_Threads_Table;
269
270   type POSIX_API_Configuration_Table_Entry is
271      record
272         Maximum_Threads                 : Interfaces.C.Int;
273         Maximum_Mutexes                 : Interfaces.C.Int;
274         Maximum_Condition_Variables     : Interfaces.C.Int;
275         Maximum_Keys                    : Interfaces.C.Int;
276         Maximum_Queued_Signals          : Interfaces.C.Int;
277         Number_Of_Initialization_Tasks  : Interfaces.C.Int;
278         User_Initialization_Tasks_Table :
279            RTEMS.POSIX_Initialization_Threads_Table_Pointer;
280      end record;
281
282   type POSIX_API_Configuration_Table is array ( RTEMS.Unsigned32 range <> ) of
283      RTEMS.POSIX_API_Configuration_Table_Entry;
284
285   type POSIX_API_Configuration_Table_Pointer is access all
286          RTEMS.POSIX_API_Configuration_Table;
287@end example
288@end ifset
289 
290@table @b
291@item maximum_threads
292is the maximum number of threads that
293can be concurrently active (created) in the system including
294initialization threads.
295
296@item maximum_mutexes
297is the maximum number of mutexes that can be concurrently
298active in the system.
299
300@item maximum_condition_variables
301is the maximum number of condition variables that can be
302concurrently active in the system.
303
304@item maximum_keys
305is the maximum number of keys that can be concurrently active in the system.
306
307@item maximum_queued_signals
308is the maximum number of queued signals that can be concurrently
309pending in the system.
310
311@item number_of_initialization_threads
312is the number of initialization threads configured.  At least one
313initialization threads must be configured.
314 
315@item User_initialization_threads_table
316is the address of the Initialization Threads Table. This table contains the
317information needed to create and start each of the initialization threads. 
318The format of each entry in this table is defined in the
319posix_initialization_threads_table @value{STRUCTURE}.
320
321@end table
322
323@section CPU Dependent Information Table
324
325The CPU Dependent Information Table is used to
326describe processor dependent information required by RTEMS.
327This table is generally used to supply RTEMS with information
328only known by the Board Support Package.  The contents of this
329table are discussed in the CPU Dependent Information Table
330chapter of the Applications Supplement document for a specific
331target processor.
332
333@section Initialization Task Table
334
335The Initialization Task Table is used to describe
336each of the user initialization tasks to the Initialization
337Manager.  The table contains one entry for each initialization
338task the user wishes to create and start.  The fields of this
339data structure directly correspond to arguments to the
340task_create and task_start directives.  The number of entries is
341found in the number_of_initialization_tasks entry in the
342Configuration Table.  The format of each entry in the
343Initialization Task Table is defined in the following @value{LANGUAGE}
344@value{STRUCTURE}:
345
346@ifset is-C
347@example
348typedef struct @{
349  rtems_name           name;
350  rtems_unsigned32     stack_size;
351  rtems_task_priority  initial_priority;
352  rtems_attribute      attribute_set;
353  rtems_task_entry     entry_point;
354  rtems_mode           mode_set;
355  rtems_task_argument  argument;
356@} rtems_initialization_tasks_table;
357@end example
358@end ifset
359
360@ifset is-Ada
361@example
362type Initialization_Tasks_Table_Entry is
363   record
364      Name             : RTEMS.Name;          -- task name
365      Stack_Size       : RTEMS.Unsigned32;    -- task stack size
366      Initial_Priority : RTEMS.Task_priority; -- task priority
367      Attribute_Set    : RTEMS.Attribute;     -- task attributes
368      Entry_Point      : RTEMS.Task_Entry;    -- task entry point
369      Mode_Set         : RTEMS.Mode;          -- task initial mode
370      Argument         : RTEMS.Unsigned32;    -- task argument
371   end record;
372
373type Initialization_Tasks_Table is array ( RTEMS.Unsigned32 range <> ) of
374  RTEMS.Initialization_Tasks_Table_Entry;
375
376type Initialization_Tasks_Table_Pointer is access all
377     Initialization_Tasks_Table;
378@end example
379@end ifset
380
381@table @b
382@item name
383is the name of this initialization task.
384
385@item stack_size
386is the size of the stack for this initialization task.
387
388@item initial_priority
389is the priority of this initialization task.
390
391@item attribute_set
392is the attribute set used during creation of this initialization task.
393
394@item entry_point
395is the address of the entry point of this initialization task.
396
397@item mode_set
398is the initial execution mode of this initialization task.
399
400@item argument
401is the initial argument for this initialization task.
402
403@end table
404
405A typical declaration for an Initialization Task Table might appear as follows:
406
407@ifset is-C
408@example
409rtems_initialization_tasks_table
410Initialization_tasks[2] = @{
411   @{ INIT_1_NAME,
412     1024,
413     1,
414     DEFAULT_ATTRIBUTES,
415     Init_1,
416     DEFAULT_MODES,
417     1
418
419   @},
420   @{ INIT_2_NAME,
421     1024,
422     250,
423     FLOATING_POINT,
424     Init_2,
425     NO_PREEMPT,
426     2
427
428   @}
429@};
430@end example
431@end ifset
432
433@ifset is-Ada
434@example
435Initialization_Tasks : aliased RTEMS.Initialization_Tasks_Table( 1 .. 2 ) := (
436   (INIT_1_NAME,
437    1024,
438    1,
439    RTEMS.Default_Attributes,
440    Init_1'Access,
441    RTEMS.Default_Modes,
442    1),
443   (INIT_2_NAME,
444    1024,
445    250,
446    RTEMS.Floating_Point,
447    Init_2'Access,
448    RTEMS.No_Preempt,
449    2)
450);
451@end example
452@end ifset
453
454@section Driver Address Table
455
456The Device Driver Table is used to inform the I/O
457Manager of the set of entry points for each device driver
458configured in the system.  The table contains one entry for each
459device driver required by the application.  The number of
460entries is defined in the number_of_device_drivers entry in the
461Configuration Table.  The format of each entry in the Device
462Driver Table is defined in
463the following @value{LANGUAGE} @value{STRUCTURE}:
464
465@ifset is-C
466@example
467typedef struct @{
468  rtems_device_driver_entry initialization;
469  rtems_device_driver_entry open;
470  rtems_device_driver_entry close;
471  rtems_device_driver_entry read;
472  rtems_device_driver_entry write;
473  rtems_device_driver_entry control;
474@} rtems_driver_address_table;
475@end example
476@end ifset
477
478@ifset is-Ada
479@example
480type Driver_Address_Table_Entry is
481   record
482      Initialization : RTEMS.Device_Driver_Entry;
483      Open           : RTEMS.Device_Driver_Entry;
484      Close          : RTEMS.Device_Driver_Entry;
485      Read           : RTEMS.Device_Driver_Entry;
486      Write          : RTEMS.Device_Driver_Entry;
487      Control        : RTEMS.Device_Driver_Entry;
488   end record;
489
490type Driver_Address_Table is array ( RTEMS.Unsigned32 range <> ) of
491  RTEMS.Driver_Address_Table_Entry;
492
493type Driver_Address_Table_Pointer is access all Driver_Address_Table;
494@end example
495@end ifset
496
497@table @b
498@item initialization
499is the address of the entry point called by
500@code{@value{DIRPREFIX}io_initialize}
501to initialize a device driver and its associated devices.
502
503@item open
504is the address of the entry point called by @code{@value{DIRPREFIX}io_open}.
505
506@item close
507is the address of the entry point called by @code{@value{DIRPREFIX}io_close}.
508
509@item read
510is the address of the entry point called by @code{@value{DIRPREFIX}io_read}.
511
512@item write
513is the address of the entry point called by @code{@value{DIRPREFIX}io_write}.
514
515@item control
516is the address of the entry point called by @code{@value{DIRPREFIX}io_control}.
517
518@end table
519
520Driver entry points configured as NULL will always
521return a status code of @code{@value{RPREFIX}SUCCESSFUL}.  No user code will be
522executed in this situation.
523
524A typical declaration for a Device Driver Table might appear as follows:
525
526@ifset is-C
527@example
528rtems_driver_address_table Driver_table[2] = @{
529   @{ tty_initialize, tty_open,  tty_close,  /* major = 0 */
530     tty_read,       tty_write, tty_control
531   @},
532   @{ lp_initialize, lp_open,    lp_close,   /* major = 1 */
533     NULL,          lp_write,   lp_control
534   @}
535@};
536@end example
537@end ifset
538
539@ifset is-Ada
540@example
541@end example
542@end ifset
543
544More information regarding the construction and
545operation of device drivers is provided in the I/O Manager
546chapter.
547
548@section User Extensions Table
549
550The User Extensions Table is used to inform RTEMS of
551the optional user-supplied static extension set.  This table
552contains one entry for each possible extension.  The entries are
553called at critical times in the life of the system and
554individual tasks.  The application may create dynamic extensions
555in addition to this single static set.  The format of each entry
556in the User Extensions Table is defined in the following @value{LANGUAGE}
557@value{STRUCTURE}:
558
559@ifset is-C
560@example
561typedef User_extensions_routine                   rtems_extension;
562typedef User_extensions_thread_create_extension   rtems_task_create_extension;
563typedef User_extensions_thread_delete_extension   rtems_task_delete_extension;
564typedef User_extensions_thread_start_extension    rtems_task_start_extension;
565typedef User_extensions_thread_restart_extension  rtems_task_restart_extension;
566typedef User_extensions_thread_switch_extension   rtems_task_switch_extension;
567typedef User_extensions_thread_begin_extension    rtems_task_begin_extension;
568typedef User_extensions_thread_exitted_extension  rtems_task_exitted_extension;
569typedef User_extensions_fatal_extension           rtems_fatal_extension;
570
571typedef User_extensions_Table                     rtems_extensions_table;
572
573typedef struct @{
574  rtems_task_create_extension      thread_create;
575  rtems_task_start_extension       thread_start;
576  rtems_task_restart_extension     thread_restart;
577  rtems_task_delete_extension      thread_delete;
578  rtems_task_switch_extension      thread_switch;
579  rtems_task_begin_extension       thread_begin;
580  rtems_task_exitted_extension     thread_exitted;
581  rtems_fatal_extension            fatal;
582@} User_extensions_Table;
583@end example
584@end ifset
585
586@ifset is-Ada
587@example
588type Extensions_Table_Entry is
589   record
590      Thread_Create      : RTEMS.Thread_Create_Extension;
591      Thread_Start       : RTEMS.Thread_Start_Extension;
592      Thread_Restart     : RTEMS.Thread_Restart_Extension;
593      Thread_Delete      : RTEMS.Thread_Delete_Extension;
594      Thread_Switch      : RTEMS.Thread_Switch_Extension;
595      Thread_Post_Switch : RTEMS.Thread_Post_Switch_Extension;
596      Thread_Begin       : RTEMS.Thread_Begin_Extension;
597      Thread_Exitted     : RTEMS.Thread_Exitted_Extension;
598      Fatal            : RTEMS.Fatal_Error_Extension;
599   end record;
600@end example
601@end ifset
602
603@table @b
604
605@item thread_create
606is the address of the
607user-supplied subroutine for the TASK_CREATE extension.  If this
608extension for task creation is defined, it is called from the
609task_create directive.  A value of NULL indicates that no
610extension is provided.
611
612@item thread_start
613is the address of the user-supplied
614subroutine for the TASK_START extension.  If this extension for
615task initiation is defined, it is called from the task_start
616directive.  A value of NULL indicates that no extension is
617provided.
618
619@item thread_restart
620is the address of the user-supplied
621subroutine for the TASK_RESTART extension.  If this extension
622for task re-initiation is defined, it is called from the
623task_restart directive.  A value of NULL indicates that no
624extension is provided.
625
626@item thread_delete
627is the address of the user-supplied
628subroutine for the TASK_DELETE extension.  If this RTEMS
629extension for task deletion is defined, it is called from the
630task_delete directive.  A value of NULL indicates that no
631extension is provided.
632
633@item thread_switch
634is the address of the user-supplied
635subroutine for the task context switch extension.  This
636subroutine is called from RTEMS dispatcher after the current
637task has been swapped out but before the new task has been
638swapped in.  A value of NULL indicates that no extension is
639provided.  As this routine is invoked after saving the current
640task's context and before restoring the heir task's context, it
641is not necessary for this routine to save and restore any
642registers.
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.