source: rtems/doc/user/conf.t @ 94c0943
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
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
6@c  $Id$
9@chapter Configuring a System
11@section Configuration Table
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}:
22@ifset is-C
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
44@ifset is-Ada
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;
64type Configuration_Table_Pointer is access all Configuration_Table;
65@end example
66@end ifset
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
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.
82@item microseconds_per_tick
83is number of microseconds per clock tick.
85@item ticks_per_timeslice
86is the number of clock ticks for a timeslice.
88@item maximum_devices
89is the maximum number of devices that can be registered.
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.
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.
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.
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.
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.
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.]
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.
132@end table
134@section RTEMS API Configuration Table
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}:
142@ifset is-C
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
161@ifset is-Ada
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;
178type API_Configuration_Table_Pointer is access all API_Configuration_Table;
179@end example
180@end ifset
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.
188@item maximum_timers
189is the maximum number of timers
190that can be concurrently active in the system.
192@item maximum_semaphores
193is the maximum number of
194semaphores that can be concurrently active in the system.
196@item maximum_message_queues
197is the maximum number of
198message queues that can be concurrently active in the system.
200@item maximum_partitions
201is the maximum number of
202partitions that can be concurrently active in the system.
204@item maximum_regions
205is the maximum number of regions
206that can be concurrently active in the system.
208@item maximum_ports
209is the maximum number of ports into
210dual-port memory areas that can be concurrently active in the
213@item number_of_initialization_tasks
214is the number of initialization tasks configured.  At least one
215initialization task must be configured.
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.
222@end table
224@section POSIX API Configuration Table
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}:
232@ifset is-C
235typedef struct @{
236  void       *(*thread_entry)(void *);
237@} posix_initialization_threads_table;
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
252@ifset is-Ada
254   type POSIX_Thread_Entry is access procedure (
255      Argument : in     RTEMS.Address
256   );
258   type POSIX_Initialization_Threads_Table_Entry is
259   record
260      Thread_Entry : RTEMS.POSIX_Thread_Entry;
261   end record;
263   type POSIX_Initialization_Threads_Table is array
264       ( RTEMS.Unsigned32 range <> ) of
265       RTEMS.POSIX_Initialization_Threads_Table_Entry;
267   type POSIX_Initialization_Threads_Table_Pointer is access all
268       POSIX_Initialization_Threads_Table;
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;
282   type POSIX_API_Configuration_Table is array ( RTEMS.Unsigned32 range <> ) of
283      RTEMS.POSIX_API_Configuration_Table_Entry;
285   type POSIX_API_Configuration_Table_Pointer is access all
286          RTEMS.POSIX_API_Configuration_Table;
287@end example
288@end ifset
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.
296@item maximum_mutexes
297is the maximum number of mutexes that can be concurrently
298active in the system.
300@item maximum_condition_variables
301is the maximum number of condition variables that can be
302concurrently active in the system.
304@item maximum_keys
305is the maximum number of keys that can be concurrently active in the system.
307@item maximum_queued_signals
308is the maximum number of queued signals that can be concurrently
309pending in the system.
311@item number_of_initialization_threads
312is the number of initialization threads configured.  At least one
313initialization threads must be configured.
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}.
321@end table
323@section CPU Dependent Information Table
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.
333@section Initialization Task Table
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}
346@ifset is-C
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
360@ifset is-Ada
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;
373type Initialization_Tasks_Table is array ( RTEMS.Unsigned32 range <> ) of
374  RTEMS.Initialization_Tasks_Table_Entry;
376type Initialization_Tasks_Table_Pointer is access all
377     Initialization_Tasks_Table;
378@end example
379@end ifset
381@table @b
382@item name
383is the name of this initialization task.
385@item stack_size
386is the size of the stack for this initialization task.
388@item initial_priority
389is the priority of this initialization task.
391@item attribute_set
392is the attribute set used during creation of this initialization task.
394@item entry_point
395is the address of the entry point of this initialization task.
397@item mode_set
398is the initial execution mode of this initialization task.
400@item argument
401is the initial argument for this initialization task.
403@end table
405A typical declaration for an Initialization Task Table might appear as follows:
407@ifset is-C
410Initialization_tasks[2] = @{
411   @{ INIT_1_NAME,
412     1024,
413     1,
415     Init_1,
417     1
419   @},
420   @{ INIT_2_NAME,
421     1024,
422     250,
424     Init_2,
425     NO_PREEMPT,
426     2
428   @}
430@end example
431@end ifset
433@ifset is-Ada
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)
451@end example
452@end ifset
454@section Driver Address Table
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}:
465@ifset is-C
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
478@ifset is-Ada
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;
490type Driver_Address_Table is array ( RTEMS.Unsigned32 range <> ) of
491  RTEMS.Driver_Address_Table_Entry;
493type Driver_Address_Table_Pointer is access all Driver_Address_Table;
494@end example
495@end ifset
497@table @b
498@item initialization
499is the address of the entry point called by
501to initialize a device driver and its associated devices.
503@item open
504is the address of the entry point called by @code{@value{DIRPREFIX}io_open}.
506@item close
507is the address of the entry point called by @code{@value{DIRPREFIX}io_close}.
509@item read
510is the address of the entry point called by @code{@value{DIRPREFIX}io_read}.
512@item write
513is the address of the entry point called by @code{@value{DIRPREFIX}io_write}.
515@item control
516is the address of the entry point called by @code{@value{DIRPREFIX}io_control}.
518@end table
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.
524A typical declaration for a Device Driver Table might appear as follows:
526@ifset is-C
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   @}
536@end example
537@end ifset
539@ifset is-Ada
541@end example
542@end ifset
544More information regarding the construction and
545operation of device drivers is provided in the I/O Manager
548@section User Extensions Table
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}
559@ifset is-C
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;
571typedef User_extensions_Table                     rtems_extensions_table;
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
586@ifset is-Ada
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
603@table @b
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.
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
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.
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.
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
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.
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.
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
663directive.  If the user's fatal error handler returns or if this
664entry is NULL then the default RTEMS fatal error handler will be
667@end table
669A typical declaration for a User Extension Table
670which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and
671FATAL extension might appear as follows:
673@ifset is-C
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
685@end example
686@end ifset
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
701@end example
702@end ifset
704More information regarding the user extensions is
705provided in the User Extensions chapter.
707@section Multiprocessor Configuration Table
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}:
722@ifset is-C
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
734@ifset is-Ada
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;
745type Multiprocessing_Table_Pointer is access all Multiprocessing_Table;
746@end example
747@end ifset
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.
763@item maximum_nodes
764is the number of processor nodes in the system.
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.
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.
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.
787@end table
789@section Multiprocessor Communications Interface Table
791The format of this table is defined in
792the following @value{LANGUAGE} @value{STRUCTURE}:
794@ifset is-C
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
808@ifset is-Ada
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;
821type MPCI_Table_Pointer is access all MPCI_Table;
822@end example
823@end ifset
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.
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.
839@item initialization
840is the address of the entry point for the initialization procedure of the
841user supplied multiprocessor communications layer.
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.
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.
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.
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.
862@end table
864More information regarding the required functionality of these
865entry points is provided in the Multiprocessor chapter.
867@section Determining Memory Requirements
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:
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
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.
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.
914@section Sizing the RTEMS RAM Workspace
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.
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
928directive being invoked with the
929@code{@value{RPREFIX}INVALID_ADDRESS} error code.
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:
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
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.