source: rtems/doc/user/conf.t @ 9b64c2d5

4.104.114.84.9
Last change on this file since 9b64c2d5 was 9b64c2d5, checked in by Joel Sherrill <joel.sherrill@…>, on Apr 15, 1998 at 12:10:03 AM

Per suggestion from Eric Norum, went from one initial extension set
to multiple. This lets the stack check extension be installed
at system initialization time and avoids the BSP having to
even know about its existence.

  • Property mode set to 100644
File size: 32.7 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_post_switch_extension thread_post_switch;
580  rtems_task_begin_extension       thread_begin;
581  rtems_task_exitted_extension     thread_exitted;
582  rtems_fatal_extension            fatal;
583@} User_extensions_Table;
584@end example
585@end ifset
586
587@ifset is-Ada
588@example
589type Extensions_Table_Entry is
590   record
591      Thread_Create      : RTEMS.Thread_Create_Extension;
592      Thread_Start       : RTEMS.Thread_Start_Extension;
593      Thread_Restart     : RTEMS.Thread_Restart_Extension;
594      Thread_Delete      : RTEMS.Thread_Delete_Extension;
595      Thread_Switch      : RTEMS.Thread_Switch_Extension;
596      Thread_Post_Switch : RTEMS.Thread_Post_Switch_Extension;
597      Thread_Begin       : RTEMS.Thread_Begin_Extension;
598      Thread_Exitted     : RTEMS.Thread_Exitted_Extension;
599      Fatal            : RTEMS.Fatal_Error_Extension;
600   end record;
601@end example
602@end ifset
603
604@table @b
605
606@item thread_create
607is the address of the
608user-supplied subroutine for the TASK_CREATE extension.  If this
609extension for task creation is defined, it is called from the
610task_create directive.  A value of NULL indicates that no
611extension is provided.
612
613@item thread_start
614is the address of the user-supplied
615subroutine for the TASK_START extension.  If this extension for
616task initiation is defined, it is called from the task_start
617directive.  A value of NULL indicates that no extension is
618provided.
619
620@item thread_restart
621is the address of the user-supplied
622subroutine for the TASK_RESTART extension.  If this extension
623for task re-initiation is defined, it is called from the
624task_restart directive.  A value of NULL indicates that no
625extension is provided.
626
627@item thread_delete
628is the address of the user-supplied
629subroutine for the TASK_DELETE extension.  If this RTEMS
630extension for task deletion is defined, it is called from the
631task_delete directive.  A value of NULL indicates that no
632extension is provided.
633
634@item thread_switch
635is the address of the user-supplied
636subroutine for the task context switch extension.  This
637subroutine is called from RTEMS dispatcher after the current
638task has been swapped out but before the new task has been
639swapped in.  A value of NULL indicates that no extension is
640provided.  As this routine is invoked after saving the current
641task's context and before restoring the heir task's context, it
642is not necessary for this routine to save and restore any
643registers.
644
645@item thread_post_switch
646is the address of the
647user-supplied subroutine for the post task context switch
648extension.  This subroutine is called from RTEMS dispatcher in
649the context of the task which has just been swapped in.
650
651@item thread_begin
652is the address of the user-supplied
653subroutine which is invoked immediately before a task begins
654execution.  It is invoked in the context of the beginning task.
655A value of NULL indicates that no extension is provided.
656
657@item thread_exitted
658is the address of the user-supplied
659subroutine which is invoked when a task exits.  This procedure
660is responsible for some action which will allow the system to
661continue execution (i.e. delete or restart the task) or to
662terminate with a fatal error.  If this field is set to NULL, the
663default RTEMS TASK_EXITTED handler will be invoked.
664
665@item fatal
666is the address of the user-supplied
667subroutine for the FATAL extension.  This RTEMS extension of
668fatal error handling is called from the
669@code{@value{DIRPREFIX}fatal_error_occurred}
670directive.  If the user's fatal error handler returns or if this
671entry is NULL then the default RTEMS fatal error handler will be
672executed.
673
674@end table
675
676A typical declaration for a User Extension Table
677which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and
678FATAL extension might appear as follows:
679
680@ifset is-C
681@example
682rtems_extensions_table User_extensions = @{
683   task_create_extension,
684   NULL,
685   NULL,
686   task_delete_extension,
687   task_switch_extension,
688   NULL,
689   NULL,
690   fatal_extension
691@};
692@end example
693@end ifset
694
695@ifset is-Ada
696User_Extensions : RTEMS.Extensions_Table := (
697   Task_Create_Extension'Access,
698   null,
699   null,
700   Task_Delete_Extension'Access,
701   Task_Switch_Extension'Access,
702   null,
703   null,
704   Fatal_Extension'Access
705);
706@example
707
708@end example
709@end ifset
710
711More information regarding the user extensions is
712provided in the User Extensions chapter.
713
714@section Multiprocessor Configuration Table
715
716The Multiprocessor Configuration Table contains
717information needed when using RTEMS in a multiprocessor
718configuration.  Many of the details associated with configuring
719a multiprocessor system are dependent on the multiprocessor
720communications layer provided by the user.  The address of the
721Multiprocessor Configuration Table should be placed in the
722User_multiprocessing_table entry in the primary Configuration
723Table.  Further details regarding many of the entries in the
724Multiprocessor Configuration Table will be provided in the
725Multiprocessing chapter.  The format of the Multiprocessor
726Configuration Table is defined in
727the following @value{LANGUAGE} @value{STRUCTURE}:
728
729@ifset is-C
730@example
731typedef struct @{
732  rtems_unsigned32  node;
733  rtems_unsigned32  maximum_nodes;
734  rtems_unsigned32  maximum_global_objects;
735  rtems_unsigned32  maximum_proxies;
736  rtems_mpci_table *User_mpci_table;
737@} rtems_multiprocessing_table;
738@end example
739@end ifset
740
741@ifset is-Ada
742@example
743type Multiprocessing_Table is
744   record
745      Node                   : RTEMS.Unsigned32;
746      Maximum_Nodes          : RTEMS.Unsigned32;
747      Maximum_Global_Objects : RTEMS.Unsigned32;
748      Maximum_Proxies        : RTEMS.Unsigned32;
749      User_MPCI_Table        : RTEMS.MPCI_Table_Pointer;
750   end record;
751
752type Multiprocessing_Table_Pointer is access all Multiprocessing_Table;
753@end example
754@end ifset
755
756@table @b
757@item node
758is a unique processor identifier
759and is used in routing messages between nodes in a
760multiprocessor configuration.  Each processor must have a unique
761node number.  RTEMS assumes that node numbers start at one and
762increase sequentially.  This assumption can be used to advantage
763by the user-supplied MPCI layer.  Typically, this requirement is
764made when the node numbers are used to calculate the address of
765inter-processor communication links.  Zero should be avoided as
766a node number because some MPCI layers use node zero to
767represent broadcasted packets.  Thus, it is recommended that
768node numbers start at one and increase sequentially.
769
770@item maximum_nodes
771is the number of processor nodes in the system.
772
773@item maximum_global_objects
774is the maximum number of global objects which can exist at any
775given moment in the entire system.  If this parameter is not the
776same on all nodes in the system, then a fatal error is generated
777to inform the user that the system is inconsistent.
778
779@item maximum_proxies
780is the maximum number of proxies which can exist at any given moment
781on this particular node.  A proxy is a substitute task control block
782which represent a task residing on a remote node when that task blocks
783on a remote object.  Proxies are used in situations in which delayed
784interaction is required with a remote node.
785
786@item User_mpci_table
787is the address of the Multiprocessor Communications Interface
788Table.  This table contains the entry points of user-provided functions
789which constitute the multiprocessor communications layer.  This table
790must be provided in multiprocessor configurations with all
791entries configured.  The format of this table and details
792regarding its entries can be found in the next section.
793
794@end table
795
796@section Multiprocessor Communications Interface Table
797
798The format of this table is defined in
799the following @value{LANGUAGE} @value{STRUCTURE}:
800
801@ifset is-C
802@example
803typedef struct @{
804  rtems_unsigned32                 default_timeout; /* in ticks */
805  rtems_unsigned32                 maximum_packet_size;
806  rtems_mpci_initialization_entry initialization;
807  rtems_mpci_get_packet_entry     get_packet;
808  rtems_mpci_return_packet_entry  return_packet;
809  rtems_mpci_send_entry           send;
810  rtems_mpci_receive_entry        receive;
811@} rtems_mpci_table;
812@end example
813@end ifset
814
815@ifset is-Ada
816@example
817type MPCI_Table is
818   record
819      Default_Timeout     : RTEMS.Unsigned32; -- in ticks
820      Maximum_Packet_Size : RTEMS.Unsigned32;
821      Initialization      : RTEMS.MPCI_Initialization_Entry;
822      Get_Packet          : RTEMS.MPCI_Get_Packet_Entry;
823      Return_Packet       : RTEMS.MPCI_Return_Packet_Entry;
824      Send                : RTEMS.MPCI_Send_Entry;
825      Receive             : RTEMS.MPCI_Receive_Entry;
826   end record;
827
828type MPCI_Table_Pointer is access all MPCI_Table;
829@end example
830@end ifset
831
832@table @b
833@item default_timeout
834is the default maximum length of time a task should block waiting for
835a response to a directive which results in communication with a remote node.
836The maximum length of time is a function the user supplied
837multiprocessor communications layer and the media used.  This
838timeout only applies to directives which would not block if the
839operation were performed locally.
840
841@item maximum_packet_size
842is the size in bytes of the longest packet which the MPCI layer is capable
843of sending.  This value should represent the total number of bytes available
844for a RTEMS interprocessor messages.
845
846@item initialization
847is the address of the entry point for the initialization procedure of the
848user supplied multiprocessor communications layer.
849
850@item get_packet
851is the address of the entry point for the procedure called by RTEMS to
852obtain a packet from the user supplied multiprocessor communications layer.
853
854@item return_packet
855is the address of the entry point for the procedure called by RTEMS to
856return a packet to the user supplied multiprocessor communications layer.
857
858@item send
859is the address of the entry point for the procedure called by RTEMS to
860send an envelope to another node.  This procedure is part of the user
861supplied multiprocessor communications layer.
862
863@item receive
864is the address of the entry point for the
865procedure called by RTEMS to retrieve an envelope containing a
866message from another node.  This procedure is part of the user
867supplied multiprocessor communications layer.
868
869@end table
870
871More information regarding the required functionality of these
872entry points is provided in the Multiprocessor chapter.
873
874@section Determining Memory Requirements
875
876Since memory is a critical resource in many real-time
877embedded systems, RTEMS was specifically designed to allow
878unused managers to be excluded from the run-time environment.
879This allows the application designer the flexibility to tailor
880RTEMS to most efficiently meet system requirements while still
881satisfying even the most stringent memory constraints.  As
882result, the size of the RTEMS executive is application
883dependent.  A Memory Requirements worksheet is provided in the
884Applications Supplement document for a specific target
885processor.  This worksheet can be used to calculate the memory
886requirements of a custom RTEMS run-time environment.  To insure
887that enough memory is allocated for future versions of RTEMS,
888the application designer should round these memory requirements
889up.  The following managers may be optionally excluded:
890
891@itemize @bullet
892@item signal
893@item region
894@item dual ported memory
895@item event
896@item multiprocessing
897@item partition
898@item timer
899@item semaphore
900@item message
901@item rate monotonic
902@end itemize
903
904RTEMS based applications must somehow provide memory
905for RTEMS' code and data space.  Although RTEMS' data space must
906be in RAM, its code space can be located in either ROM or RAM.
907In addition, the user must allocate RAM for the RTEMS RAM
908Workspace.  The size of this area is application dependent and
909can be calculated using the formula provided in the Memory
910Requirements chapter of the Applications Supplement document
911for a specific target processor.
912
913All RTEMS data variables and routine names used by
914RTEMS begin with the underscore ( _ ) character followed by an
915upper-case letter.  If RTEMS is linked with an application, then
916the application code should NOT contain any symbols which begin
917with the underscore character and followed by an upper-case
918letter to avoid any naming conflicts.  All RTEMS directive names
919should be treated as reserved words.
920
921@section Sizing the RTEMS RAM Workspace
922
923The RTEMS RAM Workspace is a user-specified block of
924memory reserved for use by RTEMS.  The application should NOT
925modify this memory.  This area consists primarily of the RTEMS
926data structures whose exact size depends upon the values
927specified in the Configuration Table.  In addition, task stacks
928and floating point context areas are dynamically allocated from
929the RTEMS RAM Workspace.
930
931The starting address of the RTEMS RAM Workspace must
932be aligned on a four-byte boundary.  Failure to properly align
933the workspace area will result in the
934@code{@value{DIRPREFIX}fatal_error_occurred}
935directive being invoked with the
936@code{@value{RPREFIX}INVALID_ADDRESS} error code.
937
938A worksheet is provided in the Memory Requirements
939chapter of the Applications Supplement document for a specific
940target processor to assist the user in calculating the minimum
941size of the RTEMS RAM Workspace for each application.  The value
942calculated with this worksheet is the minimum value that should
943be specified as the work_space_size parameter of the
944Configuration Table.  The user is cautioned that future versions
945of RTEMS may not have the same memory requirements per object.
946Although the value calculated is sufficient for a particular
947target processor and release of RTEMS, memory usage is subject
948to change across versions and target processors.  The user is
949advised to allocate somewhat more memory than the worksheet
950recommends to insure compatibility with future releases for a
951specific target processor and other target processors.  To avoid
952problems, the user should recalculate the memory requirements
953each time one of the following events occurs:
954
955@itemize @bullet
956@item a configuration parameter is modified,
957@item task or interrupt stack requirements change,
958@item task floating point attribute is altered,
959@item RTEMS is upgraded, or
960@item the target processor is changed.
961@end itemize
962
963Failure to provide enough space in the RTEMS RAM
964Workspace will result in the
965@code{@value{DIRPREFIX}fatal_error_occurred} directive
966being invoked with the appropriate error code.
Note: See TracBrowser for help on using the repository browser.