source: rtems/doc/user/conf.t @ 2a766a0
Last change on this file since 2a766a0 was 2a766a0, checked in by Joel Sherrill <joel.sherrill@…>, on 02/03/99 at 13:46:12

Added POSIX timers.

  • Property mode set to 100644
File size: 32.7 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_timers;
245  int                                 maximum_queued_signals;
246  int                                 number_of_initialization_tasks;
247  posix_initialization_threads_table *User_initialization_tasks_table;
248@} posix_api_configuration_table;
249@end group
250@end example
251@end ifset
253@ifset is-Ada
255   type POSIX_Thread_Entry is access procedure (
256      Argument : in     RTEMS.Address
257   );
259   type POSIX_Initialization_Threads_Table_Entry is
260   record
261      Thread_Entry : RTEMS.POSIX_Thread_Entry;
262   end record;
264   type POSIX_Initialization_Threads_Table is array
265       ( RTEMS.Unsigned32 range <> ) of
266       RTEMS.POSIX_Initialization_Threads_Table_Entry;
268   type POSIX_Initialization_Threads_Table_Pointer is access all
269       POSIX_Initialization_Threads_Table;
271   type POSIX_API_Configuration_Table_Entry is
272      record
273         Maximum_Threads                 : Interfaces.C.Int;
274         Maximum_Mutexes                 : Interfaces.C.Int;
275         Maximum_Condition_Variables     : Interfaces.C.Int;
276         Maximum_Keys                    : Interfaces.C.Int;
277         Maximum_Timers                  : Interfaces.C.Int;
278         Maximum_Queued_Signals          : Interfaces.C.Int;
279         Number_Of_Initialization_Tasks  : Interfaces.C.Int;
280         User_Initialization_Tasks_Table :
281            RTEMS.POSIX_Initialization_Threads_Table_Pointer;
282      end record;
284   type POSIX_API_Configuration_Table is array ( RTEMS.Unsigned32 range <> ) of
285      RTEMS.POSIX_API_Configuration_Table_Entry;
287   type POSIX_API_Configuration_Table_Pointer is access all
288          RTEMS.POSIX_API_Configuration_Table;
289@end example
290@end ifset
292@table @b
293@item maximum_threads
294is the maximum number of threads that
295can be concurrently active (created) in the system including
296initialization threads.
298@item maximum_mutexes
299is the maximum number of mutexes that can be concurrently
300active in the system.
302@item maximum_condition_variables
303is the maximum number of condition variables that can be
304concurrently active in the system.
306@item maximum_keys
307is the maximum number of keys that can be concurrently active in the system.
309@item maximum_keys
310is the maximum number of POSIX timers that can be concurrently active
311in the system.
313@item maximum_queued_signals
314is the maximum number of queued signals that can be concurrently
315pending in the system.
317@item number_of_initialization_threads
318is the number of initialization threads configured.  At least one
319initialization threads must be configured.
321@item User_initialization_threads_table
322is the address of the Initialization Threads Table. This table contains the
323information needed to create and start each of the initialization threads. 
324The format of each entry in this table is defined in the
325posix_initialization_threads_table @value{STRUCTURE}.
327@end table
329@section CPU Dependent Information Table
331The CPU Dependent Information Table is used to
332describe processor dependent information required by RTEMS.
333This table is generally used to supply RTEMS with information
334only known by the Board Support Package.  The contents of this
335table are discussed in the CPU Dependent Information Table
336chapter of the Applications Supplement document for a specific
337target processor.
339@section Initialization Task Table
341The Initialization Task Table is used to describe
342each of the user initialization tasks to the Initialization
343Manager.  The table contains one entry for each initialization
344task the user wishes to create and start.  The fields of this
345data structure directly correspond to arguments to the
346task_create and task_start directives.  The number of entries is
347found in the number_of_initialization_tasks entry in the
348Configuration Table.  The format of each entry in the
349Initialization Task Table is defined in the following @value{LANGUAGE}
352@ifset is-C
354typedef struct @{
355  rtems_name           name;
356  rtems_unsigned32     stack_size;
357  rtems_task_priority  initial_priority;
358  rtems_attribute      attribute_set;
359  rtems_task_entry     entry_point;
360  rtems_mode           mode_set;
361  rtems_task_argument  argument;
362@} rtems_initialization_tasks_table;
363@end example
364@end ifset
366@ifset is-Ada
368type Initialization_Tasks_Table_Entry is
369   record
370      Name             : RTEMS.Name;          -- task name
371      Stack_Size       : RTEMS.Unsigned32;    -- task stack size
372      Initial_Priority : RTEMS.Task_priority; -- task priority
373      Attribute_Set    : RTEMS.Attribute;     -- task attributes
374      Entry_Point      : RTEMS.Task_Entry;    -- task entry point
375      Mode_Set         : RTEMS.Mode;          -- task initial mode
376      Argument         : RTEMS.Unsigned32;    -- task argument
377   end record;
379type Initialization_Tasks_Table is array ( RTEMS.Unsigned32 range <> ) of
380  RTEMS.Initialization_Tasks_Table_Entry;
382type Initialization_Tasks_Table_Pointer is access all
383     Initialization_Tasks_Table;
384@end example
385@end ifset
387@table @b
388@item name
389is the name of this initialization task.
391@item stack_size
392is the size of the stack for this initialization task.
394@item initial_priority
395is the priority of this initialization task.
397@item attribute_set
398is the attribute set used during creation of this initialization task.
400@item entry_point
401is the address of the entry point of this initialization task.
403@item mode_set
404is the initial execution mode of this initialization task.
406@item argument
407is the initial argument for this initialization task.
409@end table
411A typical declaration for an Initialization Task Table might appear as follows:
413@ifset is-C
416Initialization_tasks[2] = @{
417   @{ INIT_1_NAME,
418     1024,
419     1,
421     Init_1,
423     1
425   @},
426   @{ INIT_2_NAME,
427     1024,
428     250,
430     Init_2,
431     NO_PREEMPT,
432     2
434   @}
436@end example
437@end ifset
439@ifset is-Ada
441Initialization_Tasks : aliased RTEMS.Initialization_Tasks_Table( 1 .. 2 ) := (
442   (INIT_1_NAME,
443    1024,
444    1,
445    RTEMS.Default_Attributes,
446    Init_1'Access,
447    RTEMS.Default_Modes,
448    1),
449   (INIT_2_NAME,
450    1024,
451    250,
452    RTEMS.Floating_Point,
453    Init_2'Access,
454    RTEMS.No_Preempt,
455    2)
457@end example
458@end ifset
460@section Driver Address Table
462The Device Driver Table is used to inform the I/O
463Manager of the set of entry points for each device driver
464configured in the system.  The table contains one entry for each
465device driver required by the application.  The number of
466entries is defined in the number_of_device_drivers entry in the
467Configuration Table.  The format of each entry in the Device
468Driver Table is defined in
469the following @value{LANGUAGE} @value{STRUCTURE}:
471@ifset is-C
473typedef struct @{
474  rtems_device_driver_entry initialization;
475  rtems_device_driver_entry open;
476  rtems_device_driver_entry close;
477  rtems_device_driver_entry read;
478  rtems_device_driver_entry write;
479  rtems_device_driver_entry control;
480@} rtems_driver_address_table;
481@end example
482@end ifset
484@ifset is-Ada
486type Driver_Address_Table_Entry is
487   record
488      Initialization : RTEMS.Device_Driver_Entry;
489      Open           : RTEMS.Device_Driver_Entry;
490      Close          : RTEMS.Device_Driver_Entry;
491      Read           : RTEMS.Device_Driver_Entry;
492      Write          : RTEMS.Device_Driver_Entry;
493      Control        : RTEMS.Device_Driver_Entry;
494   end record;
496type Driver_Address_Table is array ( RTEMS.Unsigned32 range <> ) of
497  RTEMS.Driver_Address_Table_Entry;
499type Driver_Address_Table_Pointer is access all Driver_Address_Table;
500@end example
501@end ifset
503@table @b
504@item initialization
505is the address of the entry point called by
507to initialize a device driver and its associated devices.
509@item open
510is the address of the entry point called by @code{@value{DIRPREFIX}io_open}.
512@item close
513is the address of the entry point called by @code{@value{DIRPREFIX}io_close}.
515@item read
516is the address of the entry point called by @code{@value{DIRPREFIX}io_read}.
518@item write
519is the address of the entry point called by @code{@value{DIRPREFIX}io_write}.
521@item control
522is the address of the entry point called by @code{@value{DIRPREFIX}io_control}.
524@end table
526Driver entry points configured as NULL will always
527return a status code of @code{@value{RPREFIX}SUCCESSFUL}.  No user code will be
528executed in this situation.
530A typical declaration for a Device Driver Table might appear as follows:
532@ifset is-C
534rtems_driver_address_table Driver_table[2] = @{
535   @{ tty_initialize, tty_open,  tty_close,  /* major = 0 */
536     tty_read,       tty_write, tty_control
537   @},
538   @{ lp_initialize, lp_open,    lp_close,   /* major = 1 */
539     NULL,          lp_write,   lp_control
540   @}
542@end example
543@end ifset
545@ifset is-Ada
547@end example
548@end ifset
550More information regarding the construction and
551operation of device drivers is provided in the I/O Manager
554@section User Extensions Table
556The User Extensions Table is used to inform RTEMS of
557the optional user-supplied static extension set.  This table
558contains one entry for each possible extension.  The entries are
559called at critical times in the life of the system and
560individual tasks.  The application may create dynamic extensions
561in addition to this single static set.  The format of each entry
562in the User Extensions Table is defined in the following @value{LANGUAGE}
565@ifset is-C
567typedef User_extensions_routine                   rtems_extension;
568typedef User_extensions_thread_create_extension   rtems_task_create_extension;
569typedef User_extensions_thread_delete_extension   rtems_task_delete_extension;
570typedef User_extensions_thread_start_extension    rtems_task_start_extension;
571typedef User_extensions_thread_restart_extension  rtems_task_restart_extension;
572typedef User_extensions_thread_switch_extension   rtems_task_switch_extension;
573typedef User_extensions_thread_begin_extension    rtems_task_begin_extension;
574typedef User_extensions_thread_exitted_extension  rtems_task_exitted_extension;
575typedef User_extensions_fatal_extension           rtems_fatal_extension;
577typedef User_extensions_Table                     rtems_extensions_table;
579typedef struct @{
580  rtems_task_create_extension      thread_create;
581  rtems_task_start_extension       thread_start;
582  rtems_task_restart_extension     thread_restart;
583  rtems_task_delete_extension      thread_delete;
584  rtems_task_switch_extension      thread_switch;
585  rtems_task_begin_extension       thread_begin;
586  rtems_task_exitted_extension     thread_exitted;
587  rtems_fatal_extension            fatal;
588@} User_extensions_Table;
589@end example
590@end ifset
592@ifset is-Ada
594type Extensions_Table_Entry is
595   record
596      Thread_Create      : RTEMS.Thread_Create_Extension;
597      Thread_Start       : RTEMS.Thread_Start_Extension;
598      Thread_Restart     : RTEMS.Thread_Restart_Extension;
599      Thread_Delete      : RTEMS.Thread_Delete_Extension;
600      Thread_Switch      : RTEMS.Thread_Switch_Extension;
601      Thread_Post_Switch : RTEMS.Thread_Post_Switch_Extension;
602      Thread_Begin       : RTEMS.Thread_Begin_Extension;
603      Thread_Exitted     : RTEMS.Thread_Exitted_Extension;
604      Fatal            : RTEMS.Fatal_Error_Extension;
605   end record;
606@end example
607@end ifset
609@table @b
611@item thread_create
612is the address of the
613user-supplied subroutine for the TASK_CREATE extension.  If this
614extension for task creation is defined, it is called from the
615task_create directive.  A value of NULL indicates that no
616extension is provided.
618@item thread_start
619is the address of the user-supplied
620subroutine for the TASK_START extension.  If this extension for
621task initiation is defined, it is called from the task_start
622directive.  A value of NULL indicates that no extension is
625@item thread_restart
626is the address of the user-supplied
627subroutine for the TASK_RESTART extension.  If this extension
628for task re-initiation is defined, it is called from the
629task_restart directive.  A value of NULL indicates that no
630extension is provided.
632@item thread_delete
633is the address of the user-supplied
634subroutine for the TASK_DELETE extension.  If this RTEMS
635extension for task deletion is defined, it is called from the
636task_delete directive.  A value of NULL indicates that no
637extension is provided.
639@item thread_switch
640is the address of the user-supplied
641subroutine for the task context switch extension.  This
642subroutine is called from RTEMS dispatcher after the current
643task has been swapped out but before the new task has been
644swapped in.  A value of NULL indicates that no extension is
645provided.  As this routine is invoked after saving the current
646task's context and before restoring the heir task's context, it
647is not necessary for this routine to save and restore any
650@item thread_begin
651is the address of the user-supplied
652subroutine which is invoked immediately before a task begins
653execution.  It is invoked in the context of the beginning task.
654A value of NULL indicates that no extension is provided.
656@item thread_exitted
657is the address of the user-supplied
658subroutine which is invoked when a task exits.  This procedure
659is responsible for some action which will allow the system to
660continue execution (i.e. delete or restart the task) or to
661terminate with a fatal error.  If this field is set to NULL, the
662default RTEMS TASK_EXITTED handler will be invoked.
664@item fatal
665is the address of the user-supplied
666subroutine for the FATAL extension.  This RTEMS extension of
667fatal error handling is called from the
669directive.  If the user's fatal error handler returns or if this
670entry is NULL then the default RTEMS fatal error handler will be
673@end table
675A typical declaration for a User Extension Table
676which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and
677FATAL extension might appear as follows:
679@ifset is-C
681rtems_extensions_table User_extensions = @{
682   task_create_extension,
683   NULL,
684   NULL,
685   task_delete_extension,
686   task_switch_extension,
687   NULL,
688   NULL,
689   fatal_extension
691@end example
692@end ifset
694@ifset is-Ada
695User_Extensions : RTEMS.Extensions_Table := (
696   Task_Create_Extension'Access,
697   null,
698   null,
699   Task_Delete_Extension'Access,
700   Task_Switch_Extension'Access,
701   null,
702   null,
703   Fatal_Extension'Access
707@end example
708@end ifset
710More information regarding the user extensions is
711provided in the User Extensions chapter.
713@section Multiprocessor Configuration Table
715The Multiprocessor Configuration Table contains
716information needed when using RTEMS in a multiprocessor
717configuration.  Many of the details associated with configuring
718a multiprocessor system are dependent on the multiprocessor
719communications layer provided by the user.  The address of the
720Multiprocessor Configuration Table should be placed in the
721User_multiprocessing_table entry in the primary Configuration
722Table.  Further details regarding many of the entries in the
723Multiprocessor Configuration Table will be provided in the
724Multiprocessing chapter.  The format of the Multiprocessor
725Configuration Table is defined in
726the following @value{LANGUAGE} @value{STRUCTURE}:
728@ifset is-C
730typedef struct @{
731  rtems_unsigned32  node;
732  rtems_unsigned32  maximum_nodes;
733  rtems_unsigned32  maximum_global_objects;
734  rtems_unsigned32  maximum_proxies;
735  rtems_mpci_table *User_mpci_table;
736@} rtems_multiprocessing_table;
737@end example
738@end ifset
740@ifset is-Ada
742type Multiprocessing_Table is
743   record
744      Node                   : RTEMS.Unsigned32;
745      Maximum_Nodes          : RTEMS.Unsigned32;
746      Maximum_Global_Objects : RTEMS.Unsigned32;
747      Maximum_Proxies        : RTEMS.Unsigned32;
748      User_MPCI_Table        : RTEMS.MPCI_Table_Pointer;
749   end record;
751type Multiprocessing_Table_Pointer is access all Multiprocessing_Table;
752@end example
753@end ifset
755@table @b
756@item node
757is a unique processor identifier
758and is used in routing messages between nodes in a
759multiprocessor configuration.  Each processor must have a unique
760node number.  RTEMS assumes that node numbers start at one and
761increase sequentially.  This assumption can be used to advantage
762by the user-supplied MPCI layer.  Typically, this requirement is
763made when the node numbers are used to calculate the address of
764inter-processor communication links.  Zero should be avoided as
765a node number because some MPCI layers use node zero to
766represent broadcasted packets.  Thus, it is recommended that
767node numbers start at one and increase sequentially.
769@item maximum_nodes
770is the number of processor nodes in the system.
772@item maximum_global_objects
773is the maximum number of global objects which can exist at any
774given moment in the entire system.  If this parameter is not the
775same on all nodes in the system, then a fatal error is generated
776to inform the user that the system is inconsistent.
778@item maximum_proxies
779is the maximum number of proxies which can exist at any given moment
780on this particular node.  A proxy is a substitute task control block
781which represent a task residing on a remote node when that task blocks
782on a remote object.  Proxies are used in situations in which delayed
783interaction is required with a remote node.
785@item User_mpci_table
786is the address of the Multiprocessor Communications Interface
787Table.  This table contains the entry points of user-provided functions
788which constitute the multiprocessor communications layer.  This table
789must be provided in multiprocessor configurations with all
790entries configured.  The format of this table and details
791regarding its entries can be found in the next section.
793@end table
795@section Multiprocessor Communications Interface Table
797The format of this table is defined in
798the following @value{LANGUAGE} @value{STRUCTURE}:
800@ifset is-C
802typedef struct @{
803  rtems_unsigned32                 default_timeout; /* in ticks */
804  rtems_unsigned32                 maximum_packet_size;
805  rtems_mpci_initialization_entry initialization;
806  rtems_mpci_get_packet_entry     get_packet;
807  rtems_mpci_return_packet_entry  return_packet;
808  rtems_mpci_send_entry           send;
809  rtems_mpci_receive_entry        receive;
810@} rtems_mpci_table;
811@end example
812@end ifset
814@ifset is-Ada
816type MPCI_Table is
817   record
818      Default_Timeout     : RTEMS.Unsigned32; -- in ticks
819      Maximum_Packet_Size : RTEMS.Unsigned32;
820      Initialization      : RTEMS.MPCI_Initialization_Entry;
821      Get_Packet          : RTEMS.MPCI_Get_Packet_Entry;
822      Return_Packet       : RTEMS.MPCI_Return_Packet_Entry;
823      Send                : RTEMS.MPCI_Send_Entry;
824      Receive             : RTEMS.MPCI_Receive_Entry;
825   end record;
827type MPCI_Table_Pointer is access all MPCI_Table;
828@end example
829@end ifset
831@table @b
832@item default_timeout
833is the default maximum length of time a task should block waiting for
834a response to a directive which results in communication with a remote node.
835The maximum length of time is a function the user supplied
836multiprocessor communications layer and the media used.  This
837timeout only applies to directives which would not block if the
838operation were performed locally.
840@item maximum_packet_size
841is the size in bytes of the longest packet which the MPCI layer is capable
842of sending.  This value should represent the total number of bytes available
843for a RTEMS interprocessor messages.
845@item initialization
846is the address of the entry point for the initialization procedure of the
847user supplied multiprocessor communications layer.
849@item get_packet
850is the address of the entry point for the procedure called by RTEMS to
851obtain a packet from the user supplied multiprocessor communications layer.
853@item return_packet
854is the address of the entry point for the procedure called by RTEMS to
855return a packet to the user supplied multiprocessor communications layer.
857@item send
858is the address of the entry point for the procedure called by RTEMS to
859send an envelope to another node.  This procedure is part of the user
860supplied multiprocessor communications layer.
862@item receive
863is the address of the entry point for the
864procedure called by RTEMS to retrieve an envelope containing a
865message from another node.  This procedure is part of the user
866supplied multiprocessor communications layer.
868@end table
870More information regarding the required functionality of these
871entry points is provided in the Multiprocessor chapter.
873@section Determining Memory Requirements
875Since memory is a critical resource in many real-time
876embedded systems, RTEMS was specifically designed to allow
877unused managers to be excluded from the run-time environment.
878This allows the application designer the flexibility to tailor
879RTEMS to most efficiently meet system requirements while still
880satisfying even the most stringent memory constraints.  As
881result, the size of the RTEMS executive is application
882dependent.  A Memory Requirements worksheet is provided in the
883Applications Supplement document for a specific target
884processor.  This worksheet can be used to calculate the memory
885requirements of a custom RTEMS run-time environment.  To insure
886that enough memory is allocated for future versions of RTEMS,
887the application designer should round these memory requirements
888up.  The following managers may be optionally excluded:
890@itemize @bullet
891@item signal
892@item region
893@item dual ported memory
894@item event
895@item multiprocessing
896@item partition
897@item timer
898@item semaphore
899@item message
900@item rate monotonic
901@end itemize
903RTEMS based applications must somehow provide memory
904for RTEMS' code and data space.  Although RTEMS' data space must
905be in RAM, its code space can be located in either ROM or RAM.
906In addition, the user must allocate RAM for the RTEMS RAM
907Workspace.  The size of this area is application dependent and
908can be calculated using the formula provided in the Memory
909Requirements chapter of the Applications Supplement document
910for a specific target processor.
912All RTEMS data variables and routine names used by
913RTEMS begin with the underscore ( _ ) character followed by an
914upper-case letter.  If RTEMS is linked with an application, then
915the application code should NOT contain any symbols which begin
916with the underscore character and followed by an upper-case
917letter to avoid any naming conflicts.  All RTEMS directive names
918should be treated as reserved words.
920@section Sizing the RTEMS RAM Workspace
922The RTEMS RAM Workspace is a user-specified block of
923memory reserved for use by RTEMS.  The application should NOT
924modify this memory.  This area consists primarily of the RTEMS
925data structures whose exact size depends upon the values
926specified in the Configuration Table.  In addition, task stacks
927and floating point context areas are dynamically allocated from
928the RTEMS RAM Workspace.
930The starting address of the RTEMS RAM Workspace must
931be aligned on a four-byte boundary.  Failure to properly align
932the workspace area will result in the
934directive being invoked with the
935@code{@value{RPREFIX}INVALID_ADDRESS} error code.
937A worksheet is provided in the Memory Requirements
938chapter of the Applications Supplement document for a specific
939target processor to assist the user in calculating the minimum
940size of the RTEMS RAM Workspace for each application.  The value
941calculated with this worksheet is the minimum value that should
942be specified as the work_space_size parameter of the
943Configuration Table.  The user is cautioned that future versions
944of RTEMS may not have the same memory requirements per object.
945Although the value calculated is sufficient for a particular
946target processor and release of RTEMS, memory usage is subject
947to change across versions and target processors.  The user is
948advised to allocate somewhat more memory than the worksheet
949recommends to insure compatibility with future releases for a
950specific target processor and other target processors.  To avoid
951problems, the user should recalculate the memory requirements
952each time one of the following events occurs:
954@itemize @bullet
955@item a configuration parameter is modified,
956@item task or interrupt stack requirements change,
957@item task floating point attribute is altered,
958@item RTEMS is upgraded, or
959@item the target processor is changed.
960@end itemize
962Failure to provide enough space in the RTEMS RAM
963Workspace will result in the
964@code{@value{DIRPREFIX}fatal_error_occurred} directive
965being invoked with the appropriate error code.
Note: See TracBrowser for help on using the repository browser.