source: rtems/doc/user/conf.t @ 022fbf3e

4.104.114.84.95
Last change on this file since 022fbf3e was 022fbf3e, checked in by Joel Sherrill <joel.sherrill@…>, on Jun 4, 1997 at 3:15:28 PM

Fixed formatting problem where @example did not start early enough.

  • Property mode set to 100644
File size: 34.9 KB
Line 
1@c
2@c  COPYRIGHT (c) 1996.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6
7@ifinfo
8@node Configuring a System, Configuring a System Configuration Table, EXTENSION_DELETE - Delete a extension set, Top
9@end ifinfo
10@chapter Configuring a System
11@ifinfo
12@menu
13* Configuring a System Configuration Table::
14* Configuring a System RTEMS API Configuration Table::
15* Configuring a System POSIX API Configuration Table::
16* Configuring a System CPU Dependent Information Table::
17* Configuring a System Initialization Task Table::
18* Configuring a System Driver Address Table::
19* Configuring a System User Extensions Table::
20* Configuring a System Multiprocessor Configuration Table::
21* Configuring a System Multiprocessor Communications Interface Table::
22* Configuring a System Determining Memory Requirements::
23* Configuring a System Sizing the RTEMS RAM Workspace::
24@end menu
25@end ifinfo
26
27@ifinfo
28@node Configuring a System Configuration Table, Configuring a System RTEMS API Configuration Table, Configuring a System, Configuring a System
29@end ifinfo
30@section Configuration Table
31
32The RTEMS Configuration Table is used to tailor an
33application for its specific needs.  For example, the user can
34configure the number of device drivers or which APIs may be used.
35THe address of the user-defined Configuration Table is passed as an
36argument to the initialize_executive directive, which MUST be
37the first RTEMS directive called.  The RTEMS Configuration Table
38is defined in the following @value{LANGUAGE} @value{STRUCTURE}:
39
40@ifset is-C
41@example
42@group
43typedef struct @{
44  void                             *work_space_start;
45  rtems_unsigned32                  work_space_size;
46  rtems_unsigned32                  maximum_extensions;
47  rtems_unsigned32                  microseconds_per_tick;
48  rtems_unsigned32                  ticks_per_timeslice;
49  rtems_unsigned32                  maximum_devices;
50  rtems_unsigned32                  number_of_device_drivers;
51  rtems_driver_address_table       *Device_driver_table;
52  rtems_extensions_table           *User_extension_table;
53  rtems_multiprocessing_table      *User_multiprocessing_table;
54  rtems_api_configuration_table    *RTEMS_api_configuration;
55  posix_api_configuration_table    *POSIX_api_configuration;
56@} rtems_configuration_table;
57@end group
58@end example
59@end ifset
60
61@ifset is-Ada
62@example
63type Configuration_Table is
64   record
65       Work_Space_Start           : RTEMS.Address;
66       Work_Space_Size            : RTEMS.Unsigned32;
67       Maximum_Extensions         : RTEMS.Unsigned32;
68       Microseconds_Per_Tick      : RTEMS.Unsigned32;
69       Ticks_Per_Timeslice        : RTEMS.Unsigned32;
70       Maximum_Devices            : RTEMS.Unsigned32;
71       Number_Of_Device_Drivers   : RTEMS.Unsigned32;
72       Device_Driver_Table        : RTEMS.Driver_Address_Table_Pointer;
73       User_Extension_Table       : RTEMS.Extensions_Table_Pointer;
74       User_Multiprocessing_Table : RTEMS.Multiprocessing_Table_Pointer;
75       RTEMS_API_Configuration    : RTEMS.API_Configuration_Table_Pointer;
76       POSIX_API_Configuration    :
77                       RTEMS.POSIX_API_Configuration_Table_Pointer;
78   end record;
79
80type Configuration_Table_Pointer is access all Configuration_Table;
81@end example
82@end ifset
83
84@table @b
85@item work_space_start
86is the address of the RTEMS RAM Workspace. 
87This area contains items such as the
88various object control blocks (TCBs, QCBs, ...) and task stacks.
89If the address is not aligned on a four-word boundary, then
90RTEMS will invoke the fatal error handler during
91initialize_executive.
92
93@item work_space_size
94is the calculated size of the
95RTEMS RAM Workspace.  The section Sizing the RTEMS RAM Workspace
96details how to arrive at this number.
97
98@item microseconds_per_tick
99is number of microseconds per clock tick.
100
101@item ticks_per_timeslice
102is the number of clock ticks for a timeslice.
103
104@item maximum_devices
105is the maximum number of devices that can be registered.
106
107@item number_of_device_drivers
108is the number of device drivers for the system.  There should be
109the same number of entries in the Device Driver Table.  If this field
110is zero, then the User_driver_address_table entry should be NULL.
111
112@item Device_driver_table
113is the address of the Device Driver Table.  This table contains the entry
114points for each device driver.  If the number_of_device_drivers field is zero,
115then this entry should be NULL. The format of this table will be
116discussed below.
117
118@item User_extension_table
119is the address of the User
120Extension Table.  This table contains the entry points for the
121static set of optional user extensions.  If no user extensions
122are configured, then this entry should be NULL.  The format of
123this table will be discussed below.
124
125@item User_multiprocessing_table
126is the address of the Multiprocessor Configuration Table.  This
127table contains information needed by RTEMS only when used in a multiprocessor
128configuration.  This field must be NULL when RTEMS is used in a
129single processor configuration.
130
131@item RTEMS_api_configuration
132is the address of the RTEMS API Configuration Table.  This table
133contains information needed by the RTEMS API.  This field should be
134NULL if the RTEMS API is not used.  [NOTE: Currently the RTEMS API
135is required to support support components such as BSPs and libraries
136which use this API.]
137
138@item POSIX_api_configuration
139is the address of the POSIX API Configuration Table.  This table
140contains information needed by the POSIX API.  This field should be
141NULL if the POSIX API is not used.
142
143@end table
144
145@ifinfo
146@node Configuring a System RTEMS API Configuration Table, Configuring a System POSIX API Configuration Table, Configuring a System Configuration Table, Configuring a System
147@end ifinfo
148@section RTEMS API Configuration Table
149
150The RTEMS API Configuration Table is used to configure the
151managers which constitute the RTEMS API for a particular application. 
152For example, the user can configure the maximum number of tasks for
153this application. The RTEMS API Configuration Table is defined in
154the following @value{LANGUAGE} @value{STRUCTURE}:
155
156@ifset is-C
157@example
158@group
159typedef struct @{
160  rtems_unsigned32                  maximum_tasks;
161  rtems_unsigned32                  maximum_timers;
162  rtems_unsigned32                  maximum_semaphores;
163  rtems_unsigned32                  maximum_message_queues;
164  rtems_unsigned32                  maximum_partitions;
165  rtems_unsigned32                  maximum_regions;
166  rtems_unsigned32                  maximum_ports;
167  rtems_unsigned32                  maximum_periods;
168  rtems_unsigned32                  number_of_initialization_tasks;
169  rtems_initialization_tasks_table *User_initialization_tasks_table;
170@} rtems_api_configuration_table;
171@end group
172@end example
173@end ifset
174
175@ifset is-Ada
176@example
177type API_Configuration_Table is
178   record
179      Maximum_Tasks                   : RTEMS.Unsigned32;
180      Maximum_Timers                  : RTEMS.Unsigned32;
181      Maximum_Semaphores              : RTEMS.Unsigned32;
182      Maximum_Message_queues          : RTEMS.Unsigned32;
183      Maximum_Partitions              : RTEMS.Unsigned32;
184      Maximum_Regions                 : RTEMS.Unsigned32;
185      Maximum_Ports                   : RTEMS.Unsigned32;
186      Maximum_Periods                 : RTEMS.Unsigned32;
187      Number_Of_Initialization_Tasks  : RTEMS.Unsigned32;
188      User_Initialization_Tasks_Table :
189                                RTEMS.Initialization_Tasks_Table_Pointer;
190   end record;
191
192type API_Configuration_Table_Pointer is access all API_Configuration_Table;
193@end example
194@end ifset
195
196@table @b
197@item maximum_tasks
198is the maximum number of tasks that
199can be concurrently active (created) in the system including
200initialization tasks.
201
202@item maximum_timers
203is the maximum number of timers
204that can be concurrently active in the system.
205
206@item maximum_semaphores
207is the maximum number of
208semaphores that can be concurrently active in the system.
209
210@item maximum_message_queues
211is the maximum number of
212message queues that can be concurrently active in the system.
213
214@item maximum_partitions
215is the maximum number of
216partitions that can be concurrently active in the system.
217
218@item maximum_regions
219is the maximum number of regions
220that can be concurrently active in the system.
221
222@item maximum_ports
223is the maximum number of ports into
224dual-port memory areas that can be concurrently active in the
225system.
226
227@item number_of_initialization_tasks
228is the number of initialization tasks configured.  At least one
229initialization task must be configured.
230
231@item User_initialization_tasks_table
232is the address of the Initialization Task Table. This table contains the
233information needed to create and start each of the
234initialization tasks.  The format of this table will be discussed below.
235
236@end table
237
238@ifinfo
239@node Configuring a System POSIX API Configuration Table, Configuring a System CPU Dependent Information Table, Configuring a System RTEMS API Configuration Table, Configuring a System
240@end ifinfo
241@section POSIX API Configuration Table
242
243The POSIX API Configuration Table is used to configure the
244managers which constitute the POSIX API for a particular application.
245For example, the user can configure the maximum number of threads for
246this application. The POSIX API Configuration Table is defined in
247the following @value{LANGUAGE} @value{STRUCTURE}:
248 
249@ifset is-C
250@example
251@group
252typedef struct @{
253  void       *(*thread_entry)(void *);
254@} posix_initialization_threads_table;
255 
256typedef struct @{
257  int                                 maximum_threads;
258  int                                 maximum_mutexes;
259  int                                 maximum_condition_variables;
260  int                                 maximum_keys;
261  int                                 maximum_queued_signals;
262  int                                 number_of_initialization_tasks;
263  posix_initialization_threads_table *User_initialization_tasks_table;
264@} posix_api_configuration_table;
265@end group
266@end example
267@end ifset
268
269@ifset is-Ada
270@example
271   type POSIX_Thread_Entry is access procedure (
272      Argument : in     RTEMS.Address
273   );
274
275   type POSIX_Initialization_Threads_Table_Entry is
276   record
277      Thread_Entry : RTEMS.POSIX_Thread_Entry;
278   end record;
279
280   type POSIX_Initialization_Threads_Table is array
281       ( RTEMS.Unsigned32 range <> ) of
282       RTEMS.POSIX_Initialization_Threads_Table_Entry;
283
284   type POSIX_Initialization_Threads_Table_Pointer is access all
285       POSIX_Initialization_Threads_Table;
286
287   type POSIX_API_Configuration_Table_Entry is
288      record
289         Maximum_Threads                 : Interfaces.C.Int;
290         Maximum_Mutexes                 : Interfaces.C.Int;
291         Maximum_Condition_Variables     : Interfaces.C.Int;
292         Maximum_Keys                    : Interfaces.C.Int;
293         Maximum_Queued_Signals          : Interfaces.C.Int;
294         Number_Of_Initialization_Tasks  : Interfaces.C.Int;
295         User_Initialization_Tasks_Table :
296            RTEMS.POSIX_Initialization_Threads_Table_Pointer;
297      end record;
298
299   type POSIX_API_Configuration_Table is array ( RTEMS.Unsigned32 range <> ) of
300      RTEMS.POSIX_API_Configuration_Table_Entry;
301
302   type POSIX_API_Configuration_Table_Pointer is access all
303          RTEMS.POSIX_API_Configuration_Table;
304@end example
305@end ifset
306 
307@table @b
308@item maximum_threads
309is the maximum number of threads that
310can be concurrently active (created) in the system including
311initialization threads.
312
313@item maximum_mutexes
314is the maximum number of mutexes that can be concurrently
315active in the system.
316
317@item maximum_condition_variables
318is the maximum number of condition variables that can be
319concurrently active in the system.
320
321@item maximum_keys
322is the maximum number of keys that can be concurrently active in the system.
323
324@item maximum_queued_signals
325is the maximum number of queued signals that can be concurrently
326pending in the system.
327
328@item number_of_initialization_threads
329is the number of initialization threads configured.  At least one
330initialization threads must be configured.
331 
332@item User_initialization_threads_table
333is the address of the Initialization Threads Table. This table contains the
334information needed to create and start each of the initialization threads. 
335The format of each entry in this table is defined in the
336posix_initialization_threads_table @value{STRUCTURE}.
337
338@end table
339
340@ifinfo
341@node Configuring a System CPU Dependent Information Table, Configuring a System Initialization Task Table, Configuring a System POSIX API Configuration Table, Configuring a System
342@end ifinfo
343@section CPU Dependent Information Table
344
345The CPU Dependent Information Table is used to
346describe processor dependent information required by RTEMS.
347This table is generally used to supply RTEMS with information
348only known by the Board Support Package.  The contents of this
349table are discussed in the CPU Dependent Information Table
350chapter of the Applications Supplement document for a specific
351target processor.
352
353@ifinfo
354@node Configuring a System Initialization Task Table, Configuring a System Driver Address Table, Configuring a System CPU Dependent Information Table, Configuring a System
355@end ifinfo
356@section Initialization Task Table
357
358The Initialization Task Table is used to describe
359each of the user initialization tasks to the Initialization
360Manager.  The table contains one entry for each initialization
361task the user wishes to create and start.  The fields of this
362data structure directly correspond to arguments to the
363task_create and task_start directives.  The number of entries is
364found in the number_of_initialization_tasks entry in the
365Configuration Table.  The format of each entry in the
366Initialization Task Table is defined in the following @value{LANGUAGE}
367@value{STRUCTURE}:
368
369@ifset is-C
370@example
371typedef struct @{
372  rtems_name           name;
373  rtems_unsigned32     stack_size;
374  rtems_task_priority  initial_priority;
375  rtems_attribute      attribute_set;
376  rtems_task_entry     entry_point;
377  rtems_mode           mode_set;
378  rtems_task_argument  argument;
379@} rtems_initialization_tasks_table;
380@end example
381@end ifset
382
383@ifset is-Ada
384@example
385type Initialization_Tasks_Table_Entry is
386   record
387      Name             : RTEMS.Name;          -- task name
388      Stack_Size       : RTEMS.Unsigned32;    -- task stack size
389      Initial_Priority : RTEMS.Task_priority; -- task priority
390      Attribute_Set    : RTEMS.Attribute;     -- task attributes
391      Entry_Point      : RTEMS.Task_Entry;    -- task entry point
392      Mode_Set         : RTEMS.Mode;          -- task initial mode
393      Argument         : RTEMS.Unsigned32;    -- task argument
394   end record;
395
396type Initialization_Tasks_Table is array ( RTEMS.Unsigned32 range <> ) of
397  RTEMS.Initialization_Tasks_Table_Entry;
398
399type Initialization_Tasks_Table_Pointer is access all
400     Initialization_Tasks_Table;
401@end example
402@end ifset
403
404@table @b
405@item name
406is the name of this initialization task.
407
408@item stack_size
409is the size of the stack for this initialization task.
410
411@item initial_priority
412is the priority of this initialization task.
413
414@item attribute_set
415is the attribute set used during creation of this initialization task.
416
417@item entry_point
418is the address of the entry point of this initialization task.
419
420@item mode_set
421is the initial execution mode of this initialization task.
422
423@item argument
424is the initial argument for this initialization task.
425
426@end table
427
428A typical declaration for an Initialization Task Table might appear as follows:
429
430@ifset is-C
431@example
432rtems_initialization_tasks_table
433Initialization_tasks[2] = @{
434   @{ INIT_1_NAME,
435     1024,
436     1,
437     DEFAULT_ATTRIBUTES,
438     Init_1,
439     DEFAULT_MODES,
440     1
441
442   @},
443   @{ INIT_2_NAME,
444     1024,
445     250,
446     FLOATING_POINT,
447     Init_2,
448     NO_PREEMPT,
449     2
450
451   @}
452@};
453@end example
454@end ifset
455
456@ifset is-Ada
457@example
458Initialization_Tasks : aliased RTEMS.Initialization_Tasks_Table( 1 .. 2 ) := (
459   (INIT_1_NAME,
460    1024,
461    1,
462    RTEMS.Default_Attributes,
463    Init_1'Access,
464    RTEMS.Default_Modes,
465    1),
466   (INIT_2_NAME,
467    1024,
468    250,
469    RTEMS.Floating_Point,
470    Init_2'Access,
471    RTEMS.No_Preempt,
472    2)
473);
474@end example
475@end ifset
476
477@ifinfo
478@node Configuring a System Driver Address Table, Configuring a System User Extensions Table, Configuring a System Initialization Task Table, Configuring a System
479@end ifinfo
480@section Driver Address Table
481
482The Device Driver Table is used to inform the I/O
483Manager of the set of entry points for each device driver
484configured in the system.  The table contains one entry for each
485device driver required by the application.  The number of
486entries is defined in the number_of_device_drivers entry in the
487Configuration Table.  The format of each entry in the Device
488Driver Table is defined in
489the following @value{LANGUAGE} @value{STRUCTURE}:
490
491@ifset is-C
492@example
493typedef struct @{
494  rtems_device_driver_entry initialization;
495  rtems_device_driver_entry open;
496  rtems_device_driver_entry close;
497  rtems_device_driver_entry read;
498  rtems_device_driver_entry write;
499  rtems_device_driver_entry control;
500@} rtems_driver_address_table;
501@end example
502@end ifset
503
504@ifset is-Ada
505@example
506type Driver_Address_Table_Entry is
507   record
508      Initialization : RTEMS.Device_Driver_Entry;
509      Open           : RTEMS.Device_Driver_Entry;
510      Close          : RTEMS.Device_Driver_Entry;
511      Read           : RTEMS.Device_Driver_Entry;
512      Write          : RTEMS.Device_Driver_Entry;
513      Control        : RTEMS.Device_Driver_Entry;
514   end record;
515
516type Driver_Address_Table is array ( RTEMS.Unsigned32 range <> ) of
517  RTEMS.Driver_Address_Table_Entry;
518
519type Driver_Address_Table_Pointer is access all Driver_Address_Table;
520@end example
521@end ifset
522
523@table @b
524@item initialization
525is the address of the entry point called by io_initialize
526to initialize a device driver and its associated devices.
527
528@item open
529is the address of the entry point called by io_open.
530
531@item close
532is the address of the entry point called by io_close.
533
534@item read
535is the address of the entry point called by io_read.
536
537@item write
538is the address of the entry point called by io_write.
539
540@item control
541is the address of the entry point called by io_control.
542
543@end table
544
545Driver entry points configured as NULL will always
546return a status code of @code{SUCCESSFUL}.  No user code will be
547executed in this situation.
548
549A typical declaration for a Device Driver Table might appear as follows:
550
551@ifset is-C
552@example
553rtems_driver_address_table Driver_table[2] = @{
554   @{ tty_initialize, tty_open,  tty_close,  /* major = 0 */
555     tty_read,       tty_write, tty_control
556   @},
557   @{ lp_initialize, lp_open,    lp_close,   /* major = 1 */
558     NULL,          lp_write,   lp_control
559   @}
560@};
561@end example
562@end ifset
563
564@ifset is-Ada
565@example
566@end example
567@end ifset
568
569More information regarding the construction and
570operation of device drivers is provided in the I/O Manager
571chapter.
572
573@ifinfo
574@node Configuring a System User Extensions Table, Configuring a System Multiprocessor Configuration Table, Configuring a System Driver Address Table, Configuring a System
575@end ifinfo
576@section User Extensions Table
577
578The User Extensions Table is used to inform RTEMS of
579the optional user-supplied static extension set.  This table
580contains one entry for each possible extension.  The entries are
581called at critical times in the life of the system and
582individual tasks.  The application may create dynamic extensions
583in addition to this single static set.  The format of each entry
584in the User Extensions Table is defined in the following @value{LANGUAGE}
585@value{STRUCTURE}:
586
587@ifset is-C
588@example
589typedef User_extensions_routine                   rtems_extension;
590typedef User_extensions_thread_create_extension   rtems_task_create_extension;
591typedef User_extensions_thread_delete_extension   rtems_task_delete_extension;
592typedef User_extensions_thread_start_extension    rtems_task_start_extension;
593typedef User_extensions_thread_restart_extension  rtems_task_restart_extension;
594typedef User_extensions_thread_switch_extension   rtems_task_switch_extension;
595typedef User_extensions_thread_begin_extension    rtems_task_begin_extension;
596typedef User_extensions_thread_exitted_extension  rtems_task_exitted_extension;
597typedef User_extensions_fatal_extension           rtems_fatal_extension;
598
599typedef User_extensions_Table                     rtems_extensions_table;
600
601typedef struct @{
602  rtems_task_create_extension      thread_create;
603  rtems_task_start_extension       thread_start;
604  rtems_task_restart_extension     thread_restart;
605  rtems_task_delete_extension      thread_delete;
606  rtems_task_switch_extension      thread_switch;
607  rtems_task_post_switch_extension thread_post_switch;
608  rtems_task_begin_extension       thread_begin;
609  rtems_task_exitted_extension     thread_exitted;
610  rtems_fatal_extension            fatal;
611@} User_extensions_Table;
612@end example
613@end ifset
614
615@ifset is-Ada
616@example
617type Extensions_Table_Entry is
618   record
619      Thread_Create      : RTEMS.Thread_Create_Extension;
620      Thread_Start       : RTEMS.Thread_Start_Extension;
621      Thread_Restart     : RTEMS.Thread_Restart_Extension;
622      Thread_Delete      : RTEMS.Thread_Delete_Extension;
623      Thread_Switch      : RTEMS.Thread_Switch_Extension;
624      Thread_Post_Switch : RTEMS.Thread_Post_Switch_Extension;
625      Thread_Begin       : RTEMS.Thread_Begin_Extension;
626      Thread_Exitted     : RTEMS.Thread_Exitted_Extension;
627      Fatal            : RTEMS.Fatal_Error_Extension;
628   end record;
629@end example
630@end ifset
631
632@table @b
633
634@item thread_create
635is the address of the
636user-supplied subroutine for the TASK_CREATE extension.  If this
637extension for task creation is defined, it is called from the
638task_create directive.  A value of NULL indicates that no
639extension is provided.
640
641@item thread_start
642is the address of the user-supplied
643subroutine for the TASK_START extension.  If this extension for
644task initiation is defined, it is called from the task_start
645directive.  A value of NULL indicates that no extension is
646provided.
647
648@item thread_restart
649is the address of the user-supplied
650subroutine for the TASK_RESTART extension.  If this extension
651for task re-initiation is defined, it is called from the
652task_restart directive.  A value of NULL indicates that no
653extension is provided.
654
655@item thread_delete
656is the address of the user-supplied
657subroutine for the TASK_DELETE extension.  If this RTEMS
658extension for task deletion is defined, it is called from the
659task_delete directive.  A value of NULL indicates that no
660extension is provided.
661
662@item thread_switch
663is the address of the user-supplied
664subroutine for the task context switch extension.  This
665subroutine is called from RTEMS dispatcher after the current
666task has been swapped out but before the new task has been
667swapped in.  A value of NULL indicates that no extension is
668provided.  As this routine is invoked after saving the current
669task's context and before restoring the heir task's context, it
670is not necessary for this routine to save and restore any
671registers.
672
673@item thread_post_switch
674is the address of the
675user-supplied subroutine for the post task context switch
676extension.  This subroutine is called from RTEMS dispatcher in
677the context of the task which has just been swapped in.
678
679@item thread_begin
680is the address of the user-supplied
681subroutine which is invoked immediately before a task begins
682execution.  It is invoked in the context of the beginning task.
683A value of NULL indicates that no extension is provided.
684
685@item thread_exitted
686is the address of the user-supplied
687subroutine which is invoked when a task exits.  This procedure
688is responsible for some action which will allow the system to
689continue execution (i.e. delete or restart the task) or to
690terminate with a fatal error.  If this field is set to NULL, the
691default RTEMS task_exitted handler will be invoked.
692
693@item fatal
694is the address of the user-supplied
695subroutine for the FATAL extension.  This RTEMS extension of
696fatal error handling is called from the fatal_error_occurred
697directive.  If the user's fatal error handler returns or if this
698entry is NULL then the default RTEMS fatal error handler will be
699executed.
700
701@end table
702
703A typical declaration for a User Extension Table
704which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and
705FATAL extension might appear as follows:
706
707@ifset is-C
708@example
709rtems_extensions_table User_extensions = @{
710   task_create_extension,
711   NULL,
712   NULL,
713   task_delete_extension,
714   task_switch_extension,
715   NULL,
716   NULL,
717   fatal_extension
718@};
719@end example
720@end ifset
721
722@ifset is-Ada
723User_Extensions : RTEMS.Extensions_Table := (
724   Task_Create_Extension'Access,
725   null,
726   null,
727   Task_Delete_Extension'Access,
728   Task_Switch_Extension'Access,
729   null,
730   null,
731   Fatal_Extension'Access
732);
733@example
734
735@end example
736@end ifset
737
738More information regarding the user extensions is
739provided in the User Extensions chapter.
740
741@ifinfo
742@node Configuring a System Multiprocessor Configuration Table, Configuring a System Multiprocessor Communications Interface Table, Configuring a System User Extensions Table, Configuring a System
743@end ifinfo
744@section Multiprocessor Configuration Table
745
746The Multiprocessor Configuration Table contains
747information needed when using RTEMS in a multiprocessor
748configuration.  Many of the details associated with configuring
749a multiprocessor system are dependent on the multiprocessor
750communications layer provided by the user.  The address of the
751Multiprocessor Configuration Table should be placed in the
752User_multiprocessing_table entry in the primary Configuration
753Table.  Further details regarding many of the entries in the
754Multiprocessor Configuration Table will be provided in the
755Multiprocessing chapter.  The format of the Multiprocessor
756Configuration Table is defined in
757the following @value{LANGUAGE} @value{STRUCTURE}:
758
759@ifset is-C
760@example
761typedef struct @{
762  rtems_unsigned32  node;
763  rtems_unsigned32  maximum_nodes;
764  rtems_unsigned32  maximum_global_objects;
765  rtems_unsigned32  maximum_proxies;
766  rtems_mpci_table *User_mpci_table;
767@} rtems_multiprocessing_table;
768@end example
769@end ifset
770
771@ifset is-Ada
772@example
773type Multiprocessing_Table is
774   record
775      Node                   : RTEMS.Unsigned32;
776      Maximum_Nodes          : RTEMS.Unsigned32;
777      Maximum_Global_Objects : RTEMS.Unsigned32;
778      Maximum_Proxies        : RTEMS.Unsigned32;
779      User_MPCI_Table        : RTEMS.MPCI_Table_Pointer;
780   end record;
781
782type Multiprocessing_Table_Pointer is access all Multiprocessing_Table;
783@end example
784@end ifset
785
786@table @b
787@item node
788is a unique processor identifier
789and is used in routing messages between nodes in a
790multiprocessor configuration.  Each processor must have a unique
791node number.  RTEMS assumes that node numbers start at one and
792increase sequentially.  This assumption can be used to advantage
793by the user-supplied MPCI layer.  Typically, this requirement is
794made when the node numbers are used to calculate the address of
795inter-processor communication links.  Zero should be avoided as
796a node number because some MPCI layers use node zero to
797represent broadcasted packets.  Thus, it is recommended that
798node numbers start at one and increase sequentially.
799
800@item maximum_nodes
801is the number of processor nodes in the system.
802
803@item maximum_global_objects
804is the maximum number of global objects which can exist at any
805given moment in the entire system.  If this parameter is not the
806same on all nodes in the system, then a fatal error is generated
807to inform the user that the system is inconsistent.
808
809@item maximum_proxies
810is the maximum number of proxies which can exist at any given moment
811on this particular node.  A proxy is a substitute task control block
812which represent a task residing on a remote node when that task blocks
813on a remote object.  Proxies are used in situations in which delayed
814interaction is required with a remote node.
815
816@item User_mpci_table
817is the address of the Multiprocessor Communications Interface
818Table.  This table contains the entry points of user-provided functions
819which constitute the multiprocessor communications layer.  This table
820must be provided in multiprocessor configurations with all
821entries configured.  The format of this table and details
822regarding its entries can be found in the next section.
823
824@end table
825
826@ifinfo
827@node Configuring a System Multiprocessor Communications Interface Table, Configuring a System Determining Memory Requirements, Configuring a System Multiprocessor Configuration Table, Configuring a System
828@end ifinfo
829@section Multiprocessor Communications Interface Table
830
831The format of this table is defined in
832the following @value{LANGUAGE} @value{STRUCTURE}:
833
834@ifset is-C
835@example
836typedef struct @{
837  rtems_unsigned32                 default_timeout; /* in ticks */
838  rtems_unsigned32                 maximum_packet_size;
839  rtems_mpci_initialization_entry initialization;
840  rtems_mpci_get_packet_entry     get_packet;
841  rtems_mpci_return_packet_entry  return_packet;
842  rtems_mpci_send_entry           send;
843  rtems_mpci_receive_entry        receive;
844@} rtems_mpci_table;
845@end example
846@end ifset
847
848@ifset is-Ada
849@example
850type MPCI_Table is
851   record
852      Default_Timeout     : RTEMS.Unsigned32; -- in ticks
853      Maximum_Packet_Size : RTEMS.Unsigned32;
854      Initialization      : RTEMS.MPCI_Initialization_Entry;
855      Get_Packet          : RTEMS.MPCI_Get_Packet_Entry;
856      Return_Packet       : RTEMS.MPCI_Return_Packet_Entry;
857      Send                : RTEMS.MPCI_Send_Entry;
858      Receive             : RTEMS.MPCI_Receive_Entry;
859   end record;
860
861type MPCI_Table_Pointer is access all MPCI_Table;
862@end example
863@end ifset
864
865@table @b
866@item default_timeout
867is the default maximum length of time a task should block waiting for
868a response to a directive which results in communication with a remote node.
869The maximum length of time is a function the user supplied
870multiprocessor communications layer and the media used.  This
871timeout only applies to directives which would not block if the
872operation were performed locally.
873
874@item maximum_packet_size
875is the size in bytes of the longest packet which the MPCI layer is capable
876of sending.  This value should represent the total number of bytes available
877for a RTEMS interprocessor messages.
878
879@item initialization
880is the address of the entry point for the initialization procedure of the
881user supplied multiprocessor communications layer.
882
883@item get_packet
884is the address of the entry point for the procedure called by RTEMS to
885obtain a packet from the user supplied multiprocessor communications layer.
886
887@item return_packet
888is the address of the entry point for the procedure called by RTEMS to
889return a packet to the user supplied multiprocessor communications layer.
890
891@item send
892is the address of the entry point for the procedure called by RTEMS to
893send an envelope to another node.  This procedure is part of the user
894supplied multiprocessor communications layer.
895
896@item receive
897is the address of the entry point for the
898procedure called by RTEMS to retrieve an envelope containing a
899message from another node.  This procedure is part of the user
900supplied multiprocessor communications layer.
901
902@end table
903
904More information regarding the required functionality of these
905entry points is provided in the Multiprocessor chapter.
906
907@ifinfo
908@node Configuring a System Determining Memory Requirements, Configuring a System Sizing the RTEMS RAM Workspace, Configuring a System Multiprocessor Communications Interface Table, Configuring a System
909@end ifinfo
910@section Determining Memory Requirements
911
912Since memory is a critical resource in many real-time
913embedded systems, RTEMS was specifically designed to allow
914unused managers to be excluded from the run-time environment.
915This allows the application designer the flexibility to tailor
916RTEMS to most efficiently meet system requirements while still
917satisfying even the most stringent memory constraints.  As
918result, the size of the RTEMS executive is application
919dependent.  A Memory Requirements worksheet is provided in the
920Applications Supplement document for a specific target
921processor.  This worksheet can be used to calculate the memory
922requirements of a custom RTEMS run-time environment.  To insure
923that enough memory is allocated for future versions of RTEMS,
924the application designer should round these memory requirements
925up.  The following managers may be optionally excluded:
926
927@itemize @bullet
928@item signal
929@item region
930@item dual ported memory
931@item event
932@item multiprocessing
933@item partition
934@item timer
935@item semaphore
936@item message
937@item rate monotonic
938@end itemize
939
940RTEMS based applications must somehow provide memory
941for RTEMS' code and data space.  Although RTEMS' data space must
942be in RAM, its code space can be located in either ROM or RAM.
943In addition, the user must allocate RAM for the RTEMS RAM
944Workspace.  The size of this area is application dependent and
945can be calculated using the formula provided in the Memory
946Requirements chapter of the Applications Supplement document
947for a specific target processor.
948
949All RTEMS data variables and routine names used by
950RTEMS begin with the underscore ( _ ) character followed by an
951upper-case letter.  If RTEMS is linked with an application, then
952the application code should NOT contain any symbols which begin
953with the underscore character and followed by an upper-case
954letter to avoid any naming conflicts.  All RTEMS directive names
955should be treated as reserved words.
956
957@ifinfo
958@node Configuring a System Sizing the RTEMS RAM Workspace, Multiprocessing Manager, Configuring a System Determining Memory Requirements, Configuring a System
959@end ifinfo
960@section Sizing the RTEMS RAM Workspace
961
962The RTEMS RAM Workspace is a user-specified block of
963memory reserved for use by RTEMS.  The application should NOT
964modify this memory.  This area consists primarily of the RTEMS
965data structures whose exact size depends upon the values
966specified in the Configuration Table.  In addition, task stacks
967and floating point context areas are dynamically allocated from
968the RTEMS RAM Workspace.
969
970The starting address of the RTEMS RAM Workspace must
971be aligned on a four-byte boundary.  Failure to properly align
972the workspace area will result in the fatal_error_occurred
973directive being invoked with the @code{INVALID_ADDRESS} error code.
974
975A worksheet is provided in the Memory Requirements
976chapter of the Applications Supplement document for a specific
977target processor to assist the user in calculating the minimum
978size of the RTEMS RAM Workspace for each application.  The value
979calculated with this worksheet is the minimum value that should
980be specified as the work_space_size parameter of the
981Configuration Table.  The user is cautioned that future versions
982of RTEMS may not have the same memory requirements per object.
983Although the value calculated is sufficient for a particular
984target processor and release of RTEMS, memory usage is subject
985to change across versions and target processors.  The user is
986advised to allocate somewhat more memory than the worksheet
987recommends to insure compatibility with future releases for a
988specific target processor and other target processors.  To avoid
989problems, the user should recalculate the memory requirements
990each time one of the following events occurs:
991
992@itemize @bullet
993@item a configuration parameter is modified,
994@item task or interrupt stack requirements change,
995@item task floating point attribute is altered,
996@item RTEMS is upgraded, or
997@item the target processor is changed.
998@end itemize
999
1000Failure to provide enough space in the RTEMS RAM
1001Workspace will result in the fatal_error_occurred directive
1002being invoked with the appropriate error code.
Note: See TracBrowser for help on using the repository browser.