source: rtems/doc/user/conf.t @ 338502f

4.104.114.84.9
Last change on this file since 338502f was 338502f, checked in by Joel Sherrill <joel.sherrill@…>, on Apr 19, 1999 at 5:40:20 PM

Unlimited objects information from Chris Johns (ccj@…).

  • Property mode set to 100644
File size: 33.9 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_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
252
253@ifset is-Ada
254@example
255   type POSIX_Thread_Entry is access procedure (
256      Argument : in     RTEMS.Address
257   );
258
259   type POSIX_Initialization_Threads_Table_Entry is
260   record
261      Thread_Entry : RTEMS.POSIX_Thread_Entry;
262   end record;
263
264   type POSIX_Initialization_Threads_Table is array
265       ( RTEMS.Unsigned32 range <> ) of
266       RTEMS.POSIX_Initialization_Threads_Table_Entry;
267
268   type POSIX_Initialization_Threads_Table_Pointer is access all
269       POSIX_Initialization_Threads_Table;
270
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;
283
284   type POSIX_API_Configuration_Table is array ( RTEMS.Unsigned32 range <> ) of
285      RTEMS.POSIX_API_Configuration_Table_Entry;
286
287   type POSIX_API_Configuration_Table_Pointer is access all
288          RTEMS.POSIX_API_Configuration_Table;
289@end example
290@end ifset
291 
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.
297
298@item maximum_mutexes
299is the maximum number of mutexes that can be concurrently
300active in the system.
301
302@item maximum_condition_variables
303is the maximum number of condition variables that can be
304concurrently active in the system.
305
306@item maximum_keys
307is the maximum number of keys that can be concurrently active in the system.
308
309@item maximum_timers
310is the maximum number of POSIX timers that can be concurrently active
311in the system.
312
313@item maximum_queued_signals
314is the maximum number of queued signals that can be concurrently
315pending in the system.
316
317@item number_of_initialization_threads
318is the number of initialization threads configured.  At least one
319initialization threads must be configured.
320 
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}.
326
327@end table
328
329@section CPU Dependent Information Table
330
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.
338
339@section Initialization Task Table
340
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}
350@value{STRUCTURE}:
351
352@ifset is-C
353@example
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
365
366@ifset is-Ada
367@example
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;
378
379type Initialization_Tasks_Table is array ( RTEMS.Unsigned32 range <> ) of
380  RTEMS.Initialization_Tasks_Table_Entry;
381
382type Initialization_Tasks_Table_Pointer is access all
383     Initialization_Tasks_Table;
384@end example
385@end ifset
386
387@table @b
388@item name
389is the name of this initialization task.
390
391@item stack_size
392is the size of the stack for this initialization task.
393
394@item initial_priority
395is the priority of this initialization task.
396
397@item attribute_set
398is the attribute set used during creation of this initialization task.
399
400@item entry_point
401is the address of the entry point of this initialization task.
402
403@item mode_set
404is the initial execution mode of this initialization task.
405
406@item argument
407is the initial argument for this initialization task.
408
409@end table
410
411A typical declaration for an Initialization Task Table might appear as follows:
412
413@ifset is-C
414@example
415rtems_initialization_tasks_table
416Initialization_tasks[2] = @{
417   @{ INIT_1_NAME,
418     1024,
419     1,
420     DEFAULT_ATTRIBUTES,
421     Init_1,
422     DEFAULT_MODES,
423     1
424
425   @},
426   @{ INIT_2_NAME,
427     1024,
428     250,
429     FLOATING_POINT,
430     Init_2,
431     NO_PREEMPT,
432     2
433
434   @}
435@};
436@end example
437@end ifset
438
439@ifset is-Ada
440@example
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)
456);
457@end example
458@end ifset
459
460@section Driver Address Table
461
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}:
470
471@ifset is-C
472@example
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
483
484@ifset is-Ada
485@example
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;
495
496type Driver_Address_Table is array ( RTEMS.Unsigned32 range <> ) of
497  RTEMS.Driver_Address_Table_Entry;
498
499type Driver_Address_Table_Pointer is access all Driver_Address_Table;
500@end example
501@end ifset
502
503@table @b
504@item initialization
505is the address of the entry point called by
506@code{@value{DIRPREFIX}io_initialize}
507to initialize a device driver and its associated devices.
508
509@item open
510is the address of the entry point called by @code{@value{DIRPREFIX}io_open}.
511
512@item close
513is the address of the entry point called by @code{@value{DIRPREFIX}io_close}.
514
515@item read
516is the address of the entry point called by @code{@value{DIRPREFIX}io_read}.
517
518@item write
519is the address of the entry point called by @code{@value{DIRPREFIX}io_write}.
520
521@item control
522is the address of the entry point called by @code{@value{DIRPREFIX}io_control}.
523
524@end table
525
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.
529
530A typical declaration for a Device Driver Table might appear as follows:
531
532@ifset is-C
533@example
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   @}
541@};
542@end example
543@end ifset
544
545@ifset is-Ada
546@example
547@end example
548@end ifset
549
550More information regarding the construction and
551operation of device drivers is provided in the I/O Manager
552chapter.
553
554@section User Extensions Table
555
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}
563@value{STRUCTURE}:
564
565@ifset is-C
566@example
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;
576
577typedef User_extensions_Table                     rtems_extensions_table;
578
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
591
592@ifset is-Ada
593@example
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
608
609@table @b
610
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.
617
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
623provided.
624
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.
631
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.
638
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
648registers.
649
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.
655
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.
663
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
668@code{@value{DIRPREFIX}fatal_error_occurred}
669directive.  If the user's fatal error handler returns or if this
670entry is NULL then the default RTEMS fatal error handler will be
671executed.
672
673@end table
674
675A typical declaration for a User Extension Table
676which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and
677FATAL extension might appear as follows:
678
679@ifset is-C
680@example
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
690@};
691@end example
692@end ifset
693
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
704);
705@example
706
707@end example
708@end ifset
709
710More information regarding the user extensions is
711provided in the User Extensions chapter.
712
713@section Multiprocessor Configuration Table
714
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}:
727
728@ifset is-C
729@example
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
739
740@ifset is-Ada
741@example
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;
750
751type Multiprocessing_Table_Pointer is access all Multiprocessing_Table;
752@end example
753@end ifset
754
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.
768
769@item maximum_nodes
770is the number of processor nodes in the system.
771
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.
777
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.
784
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.
792
793@end table
794
795@section Multiprocessor Communications Interface Table
796
797The format of this table is defined in
798the following @value{LANGUAGE} @value{STRUCTURE}:
799
800@ifset is-C
801@example
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
813
814@ifset is-Ada
815@example
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;
826
827type MPCI_Table_Pointer is access all MPCI_Table;
828@end example
829@end ifset
830
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.
839
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.
844
845@item initialization
846is the address of the entry point for the initialization procedure of the
847user supplied multiprocessor communications layer.
848
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.
852
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.
856
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.
861
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.
867
868@end table
869
870More information regarding the required functionality of these
871entry points is provided in the Multiprocessor chapter.
872
873@section Determining Memory Requirements
874
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:
889
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
902
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.
911
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.
919
920@section Sizing the RTEMS RAM Workspace
921
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.
929
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
933@code{@value{DIRPREFIX}fatal_error_occurred}
934directive being invoked with the
935@code{@value{RPREFIX}INVALID_ADDRESS} error code.
936
937A worksheet is provided in the @b{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 @code{work_space_size} parameter of the
943Configuration Table. 
944
945The allocation of objects can operate in two modes. The default mode
946has an object number ceiling. No more than the specified number of
947objects can be allocated from the RTEMS RAM Workspace. The number of objects
948specified in the particular API Configuration table fields are
949allocated at initialisation. The second mode allows the number of
950objects to grow to use the available free memory in the RTEMS RAM Workspace.
951
952The auto-extending mode can be enabled individually for each object
953type by using the macro @code{rtems_resource_unlimited}. This takes a value
954as a parameter, and is used to set the object maximum number field in
955an API Configuration table. The value is an allocation unit size. When
956RTEMS is required to grow the object table it is grown by this
957size. The kernel will return the object memory back to the RTEMS RAM Workspace
958when an object is destroyed. The kernel will only return an allocated
959block of objects to the RTEMS RAM Workspace if at least half the allocation
960size of free objects remain allocated. RTEMS always keeps one
961allocation block of objects allocated. Here is an example of using
962@code{rtems_resource_unlimited}:
963
964@example
965#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
966@end example
967
968The user is cautioned that future versions of RTEMS may not have the
969same memory requirements per object. Although the value calculated is
970suficient for a particular target processor and release of RTEMS,
971memory usage is subject to change across versions and target
972processors.  The user is advised to allocate somewhat more memory than
973the worksheet recommends to insure compatibility with future releases
974for a specific target processor and other target processors. To avoid
975problems, the user should recalculate the memory requirements each
976time one of the following events occurs:
977
978@itemize @bullet
979@item a configuration parameter is modified,
980@item task or interrupt stack requirements change,
981@item task floating point attribute is altered,
982@item RTEMS is upgraded, or
983@item the target processor is changed.
984@end itemize
985
986Failure to provide enough space in the RTEMS RAM
987Workspace will result in the
988@code{@value{DIRPREFIX}fatal_error_occurred} directive
989being invoked with the appropriate error code.
Note: See TracBrowser for help on using the repository browser.