forked from Imagelibrary/rtems
960 lines
32 KiB
Perl
960 lines
32 KiB
Perl
@c
|
|
@c COPYRIGHT (c) 1988-1998.
|
|
@c On-Line Applications Research Corporation (OAR).
|
|
@c All rights reserved.
|
|
@c
|
|
@c $Id$
|
|
@c
|
|
|
|
@chapter Configuring a System
|
|
|
|
@section Configuration Table
|
|
|
|
The RTEMS Configuration Table is used to tailor an
|
|
application for its specific needs. For example, the user can
|
|
configure the number of device drivers or which APIs may be used.
|
|
THe address of the user-defined Configuration Table is passed as an
|
|
argument to the @code{@value{DIRPREFIX}initialize_executive}
|
|
directive, which MUST be the first RTEMS directive called.
|
|
The RTEMS Configuration Table
|
|
is defined in the following @value{LANGUAGE} @value{STRUCTURE}:
|
|
|
|
@ifset is-C
|
|
@example
|
|
@group
|
|
typedef struct @{
|
|
void *work_space_start;
|
|
rtems_unsigned32 work_space_size;
|
|
rtems_unsigned32 maximum_extensions;
|
|
rtems_unsigned32 microseconds_per_tick;
|
|
rtems_unsigned32 ticks_per_timeslice;
|
|
rtems_unsigned32 maximum_devices;
|
|
rtems_unsigned32 number_of_device_drivers;
|
|
rtems_driver_address_table *Device_driver_table;
|
|
rtems_extensions_table *User_extension_table;
|
|
rtems_multiprocessing_table *User_multiprocessing_table;
|
|
rtems_api_configuration_table *RTEMS_api_configuration;
|
|
posix_api_configuration_table *POSIX_api_configuration;
|
|
@} rtems_configuration_table;
|
|
@end group
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
type Configuration_Table is
|
|
record
|
|
Work_Space_Start : RTEMS.Address;
|
|
Work_Space_Size : RTEMS.Unsigned32;
|
|
Maximum_Extensions : RTEMS.Unsigned32;
|
|
Microseconds_Per_Tick : RTEMS.Unsigned32;
|
|
Ticks_Per_Timeslice : RTEMS.Unsigned32;
|
|
Maximum_Devices : RTEMS.Unsigned32;
|
|
Number_Of_Device_Drivers : RTEMS.Unsigned32;
|
|
Device_Driver_Table : RTEMS.Driver_Address_Table_Pointer;
|
|
User_Extension_Table : RTEMS.Extensions_Table_Pointer;
|
|
User_Multiprocessing_Table : RTEMS.Multiprocessing_Table_Pointer;
|
|
RTEMS_API_Configuration : RTEMS.API_Configuration_Table_Pointer;
|
|
POSIX_API_Configuration :
|
|
RTEMS.POSIX_API_Configuration_Table_Pointer;
|
|
end record;
|
|
|
|
type Configuration_Table_Pointer is access all Configuration_Table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@table @b
|
|
@item work_space_start
|
|
is the address of the RTEMS RAM Workspace.
|
|
This area contains items such as the
|
|
various object control blocks (TCBs, QCBs, ...) and task stacks.
|
|
If the address is not aligned on a four-word boundary, then
|
|
RTEMS will invoke the fatal error handler during
|
|
@code{@value{DIRPREFIX}initialize_executive}.
|
|
|
|
@item work_space_size
|
|
is the calculated size of the
|
|
RTEMS RAM Workspace. The section Sizing the RTEMS RAM Workspace
|
|
details how to arrive at this number.
|
|
|
|
@item microseconds_per_tick
|
|
is number of microseconds per clock tick.
|
|
|
|
@item ticks_per_timeslice
|
|
is the number of clock ticks for a timeslice.
|
|
|
|
@item maximum_devices
|
|
is the maximum number of devices that can be registered.
|
|
|
|
@item number_of_device_drivers
|
|
is the number of device drivers for the system. There should be
|
|
the same number of entries in the Device Driver Table. If this field
|
|
is zero, then the User_driver_address_table entry should be NULL.
|
|
|
|
@item Device_driver_table
|
|
is the address of the Device Driver Table. This table contains the entry
|
|
points for each device driver. If the number_of_device_drivers field is zero,
|
|
then this entry should be NULL. The format of this table will be
|
|
discussed below.
|
|
|
|
@item User_extension_table
|
|
is the address of the User
|
|
Extension Table. This table contains the entry points for the
|
|
static set of optional user extensions. If no user extensions
|
|
are configured, then this entry should be NULL. The format of
|
|
this table will be discussed below.
|
|
|
|
@item User_multiprocessing_table
|
|
is the address of the Multiprocessor Configuration Table. This
|
|
table contains information needed by RTEMS only when used in a multiprocessor
|
|
configuration. This field must be NULL when RTEMS is used in a
|
|
single processor configuration.
|
|
|
|
@item RTEMS_api_configuration
|
|
is the address of the RTEMS API Configuration Table. This table
|
|
contains information needed by the RTEMS API. This field should be
|
|
NULL if the RTEMS API is not used. [NOTE: Currently the RTEMS API
|
|
is required to support support components such as BSPs and libraries
|
|
which use this API.]
|
|
|
|
@item POSIX_api_configuration
|
|
is the address of the POSIX API Configuration Table. This table
|
|
contains information needed by the POSIX API. This field should be
|
|
NULL if the POSIX API is not used.
|
|
|
|
@end table
|
|
|
|
@section RTEMS API Configuration Table
|
|
|
|
The RTEMS API Configuration Table is used to configure the
|
|
managers which constitute the RTEMS API for a particular application.
|
|
For example, the user can configure the maximum number of tasks for
|
|
this application. The RTEMS API Configuration Table is defined in
|
|
the following @value{LANGUAGE} @value{STRUCTURE}:
|
|
|
|
@ifset is-C
|
|
@example
|
|
@group
|
|
typedef struct @{
|
|
rtems_unsigned32 maximum_tasks;
|
|
rtems_unsigned32 maximum_timers;
|
|
rtems_unsigned32 maximum_semaphores;
|
|
rtems_unsigned32 maximum_message_queues;
|
|
rtems_unsigned32 maximum_partitions;
|
|
rtems_unsigned32 maximum_regions;
|
|
rtems_unsigned32 maximum_ports;
|
|
rtems_unsigned32 maximum_periods;
|
|
rtems_unsigned32 number_of_initialization_tasks;
|
|
rtems_initialization_tasks_table *User_initialization_tasks_table;
|
|
@} rtems_api_configuration_table;
|
|
@end group
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
type API_Configuration_Table is
|
|
record
|
|
Maximum_Tasks : RTEMS.Unsigned32;
|
|
Maximum_Timers : RTEMS.Unsigned32;
|
|
Maximum_Semaphores : RTEMS.Unsigned32;
|
|
Maximum_Message_queues : RTEMS.Unsigned32;
|
|
Maximum_Partitions : RTEMS.Unsigned32;
|
|
Maximum_Regions : RTEMS.Unsigned32;
|
|
Maximum_Ports : RTEMS.Unsigned32;
|
|
Maximum_Periods : RTEMS.Unsigned32;
|
|
Number_Of_Initialization_Tasks : RTEMS.Unsigned32;
|
|
User_Initialization_Tasks_Table :
|
|
RTEMS.Initialization_Tasks_Table_Pointer;
|
|
end record;
|
|
|
|
type API_Configuration_Table_Pointer is access all API_Configuration_Table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@table @b
|
|
@item maximum_tasks
|
|
is the maximum number of tasks that
|
|
can be concurrently active (created) in the system including
|
|
initialization tasks.
|
|
|
|
@item maximum_timers
|
|
is the maximum number of timers
|
|
that can be concurrently active in the system.
|
|
|
|
@item maximum_semaphores
|
|
is the maximum number of
|
|
semaphores that can be concurrently active in the system.
|
|
|
|
@item maximum_message_queues
|
|
is the maximum number of
|
|
message queues that can be concurrently active in the system.
|
|
|
|
@item maximum_partitions
|
|
is the maximum number of
|
|
partitions that can be concurrently active in the system.
|
|
|
|
@item maximum_regions
|
|
is the maximum number of regions
|
|
that can be concurrently active in the system.
|
|
|
|
@item maximum_ports
|
|
is the maximum number of ports into
|
|
dual-port memory areas that can be concurrently active in the
|
|
system.
|
|
|
|
@item number_of_initialization_tasks
|
|
is the number of initialization tasks configured. At least one
|
|
initialization task must be configured.
|
|
|
|
@item User_initialization_tasks_table
|
|
is the address of the Initialization Task Table. This table contains the
|
|
information needed to create and start each of the
|
|
initialization tasks. The format of this table will be discussed below.
|
|
|
|
@end table
|
|
|
|
@section POSIX API Configuration Table
|
|
|
|
The POSIX API Configuration Table is used to configure the
|
|
managers which constitute the POSIX API for a particular application.
|
|
For example, the user can configure the maximum number of threads for
|
|
this application. The POSIX API Configuration Table is defined in
|
|
the following @value{LANGUAGE} @value{STRUCTURE}:
|
|
|
|
@ifset is-C
|
|
@example
|
|
@group
|
|
typedef struct @{
|
|
void *(*thread_entry)(void *);
|
|
@} posix_initialization_threads_table;
|
|
|
|
typedef struct @{
|
|
int maximum_threads;
|
|
int maximum_mutexes;
|
|
int maximum_condition_variables;
|
|
int maximum_keys;
|
|
int maximum_queued_signals;
|
|
int number_of_initialization_tasks;
|
|
posix_initialization_threads_table *User_initialization_tasks_table;
|
|
@} posix_api_configuration_table;
|
|
@end group
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
type POSIX_Thread_Entry is access procedure (
|
|
Argument : in RTEMS.Address
|
|
);
|
|
|
|
type POSIX_Initialization_Threads_Table_Entry is
|
|
record
|
|
Thread_Entry : RTEMS.POSIX_Thread_Entry;
|
|
end record;
|
|
|
|
type POSIX_Initialization_Threads_Table is array
|
|
( RTEMS.Unsigned32 range <> ) of
|
|
RTEMS.POSIX_Initialization_Threads_Table_Entry;
|
|
|
|
type POSIX_Initialization_Threads_Table_Pointer is access all
|
|
POSIX_Initialization_Threads_Table;
|
|
|
|
type POSIX_API_Configuration_Table_Entry is
|
|
record
|
|
Maximum_Threads : Interfaces.C.Int;
|
|
Maximum_Mutexes : Interfaces.C.Int;
|
|
Maximum_Condition_Variables : Interfaces.C.Int;
|
|
Maximum_Keys : Interfaces.C.Int;
|
|
Maximum_Queued_Signals : Interfaces.C.Int;
|
|
Number_Of_Initialization_Tasks : Interfaces.C.Int;
|
|
User_Initialization_Tasks_Table :
|
|
RTEMS.POSIX_Initialization_Threads_Table_Pointer;
|
|
end record;
|
|
|
|
type POSIX_API_Configuration_Table is array ( RTEMS.Unsigned32 range <> ) of
|
|
RTEMS.POSIX_API_Configuration_Table_Entry;
|
|
|
|
type POSIX_API_Configuration_Table_Pointer is access all
|
|
RTEMS.POSIX_API_Configuration_Table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@table @b
|
|
@item maximum_threads
|
|
is the maximum number of threads that
|
|
can be concurrently active (created) in the system including
|
|
initialization threads.
|
|
|
|
@item maximum_mutexes
|
|
is the maximum number of mutexes that can be concurrently
|
|
active in the system.
|
|
|
|
@item maximum_condition_variables
|
|
is the maximum number of condition variables that can be
|
|
concurrently active in the system.
|
|
|
|
@item maximum_keys
|
|
is the maximum number of keys that can be concurrently active in the system.
|
|
|
|
@item maximum_queued_signals
|
|
is the maximum number of queued signals that can be concurrently
|
|
pending in the system.
|
|
|
|
@item number_of_initialization_threads
|
|
is the number of initialization threads configured. At least one
|
|
initialization threads must be configured.
|
|
|
|
@item User_initialization_threads_table
|
|
is the address of the Initialization Threads Table. This table contains the
|
|
information needed to create and start each of the initialization threads.
|
|
The format of each entry in this table is defined in the
|
|
posix_initialization_threads_table @value{STRUCTURE}.
|
|
|
|
@end table
|
|
|
|
@section CPU Dependent Information Table
|
|
|
|
The CPU Dependent Information Table is used to
|
|
describe processor dependent information required by RTEMS.
|
|
This table is generally used to supply RTEMS with information
|
|
only known by the Board Support Package. The contents of this
|
|
table are discussed in the CPU Dependent Information Table
|
|
chapter of the Applications Supplement document for a specific
|
|
target processor.
|
|
|
|
@section Initialization Task Table
|
|
|
|
The Initialization Task Table is used to describe
|
|
each of the user initialization tasks to the Initialization
|
|
Manager. The table contains one entry for each initialization
|
|
task the user wishes to create and start. The fields of this
|
|
data structure directly correspond to arguments to the
|
|
task_create and task_start directives. The number of entries is
|
|
found in the number_of_initialization_tasks entry in the
|
|
Configuration Table. The format of each entry in the
|
|
Initialization Task Table is defined in the following @value{LANGUAGE}
|
|
@value{STRUCTURE}:
|
|
|
|
@ifset is-C
|
|
@example
|
|
typedef struct @{
|
|
rtems_name name;
|
|
rtems_unsigned32 stack_size;
|
|
rtems_task_priority initial_priority;
|
|
rtems_attribute attribute_set;
|
|
rtems_task_entry entry_point;
|
|
rtems_mode mode_set;
|
|
rtems_task_argument argument;
|
|
@} rtems_initialization_tasks_table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
type Initialization_Tasks_Table_Entry is
|
|
record
|
|
Name : RTEMS.Name; -- task name
|
|
Stack_Size : RTEMS.Unsigned32; -- task stack size
|
|
Initial_Priority : RTEMS.Task_priority; -- task priority
|
|
Attribute_Set : RTEMS.Attribute; -- task attributes
|
|
Entry_Point : RTEMS.Task_Entry; -- task entry point
|
|
Mode_Set : RTEMS.Mode; -- task initial mode
|
|
Argument : RTEMS.Unsigned32; -- task argument
|
|
end record;
|
|
|
|
type Initialization_Tasks_Table is array ( RTEMS.Unsigned32 range <> ) of
|
|
RTEMS.Initialization_Tasks_Table_Entry;
|
|
|
|
type Initialization_Tasks_Table_Pointer is access all
|
|
Initialization_Tasks_Table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@table @b
|
|
@item name
|
|
is the name of this initialization task.
|
|
|
|
@item stack_size
|
|
is the size of the stack for this initialization task.
|
|
|
|
@item initial_priority
|
|
is the priority of this initialization task.
|
|
|
|
@item attribute_set
|
|
is the attribute set used during creation of this initialization task.
|
|
|
|
@item entry_point
|
|
is the address of the entry point of this initialization task.
|
|
|
|
@item mode_set
|
|
is the initial execution mode of this initialization task.
|
|
|
|
@item argument
|
|
is the initial argument for this initialization task.
|
|
|
|
@end table
|
|
|
|
A typical declaration for an Initialization Task Table might appear as follows:
|
|
|
|
@ifset is-C
|
|
@example
|
|
rtems_initialization_tasks_table
|
|
Initialization_tasks[2] = @{
|
|
@{ INIT_1_NAME,
|
|
1024,
|
|
1,
|
|
DEFAULT_ATTRIBUTES,
|
|
Init_1,
|
|
DEFAULT_MODES,
|
|
1
|
|
|
|
@},
|
|
@{ INIT_2_NAME,
|
|
1024,
|
|
250,
|
|
FLOATING_POINT,
|
|
Init_2,
|
|
NO_PREEMPT,
|
|
2
|
|
|
|
@}
|
|
@};
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
Initialization_Tasks : aliased RTEMS.Initialization_Tasks_Table( 1 .. 2 ) := (
|
|
(INIT_1_NAME,
|
|
1024,
|
|
1,
|
|
RTEMS.Default_Attributes,
|
|
Init_1'Access,
|
|
RTEMS.Default_Modes,
|
|
1),
|
|
(INIT_2_NAME,
|
|
1024,
|
|
250,
|
|
RTEMS.Floating_Point,
|
|
Init_2'Access,
|
|
RTEMS.No_Preempt,
|
|
2)
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@section Driver Address Table
|
|
|
|
The Device Driver Table is used to inform the I/O
|
|
Manager of the set of entry points for each device driver
|
|
configured in the system. The table contains one entry for each
|
|
device driver required by the application. The number of
|
|
entries is defined in the number_of_device_drivers entry in the
|
|
Configuration Table. The format of each entry in the Device
|
|
Driver Table is defined in
|
|
the following @value{LANGUAGE} @value{STRUCTURE}:
|
|
|
|
@ifset is-C
|
|
@example
|
|
typedef struct @{
|
|
rtems_device_driver_entry initialization;
|
|
rtems_device_driver_entry open;
|
|
rtems_device_driver_entry close;
|
|
rtems_device_driver_entry read;
|
|
rtems_device_driver_entry write;
|
|
rtems_device_driver_entry control;
|
|
@} rtems_driver_address_table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
type Driver_Address_Table_Entry is
|
|
record
|
|
Initialization : RTEMS.Device_Driver_Entry;
|
|
Open : RTEMS.Device_Driver_Entry;
|
|
Close : RTEMS.Device_Driver_Entry;
|
|
Read : RTEMS.Device_Driver_Entry;
|
|
Write : RTEMS.Device_Driver_Entry;
|
|
Control : RTEMS.Device_Driver_Entry;
|
|
end record;
|
|
|
|
type Driver_Address_Table is array ( RTEMS.Unsigned32 range <> ) of
|
|
RTEMS.Driver_Address_Table_Entry;
|
|
|
|
type Driver_Address_Table_Pointer is access all Driver_Address_Table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@table @b
|
|
@item initialization
|
|
is the address of the entry point called by
|
|
@code{@value{DIRPREFIX}io_initialize}
|
|
to initialize a device driver and its associated devices.
|
|
|
|
@item open
|
|
is the address of the entry point called by @code{@value{DIRPREFIX}io_open}.
|
|
|
|
@item close
|
|
is the address of the entry point called by @code{@value{DIRPREFIX}io_close}.
|
|
|
|
@item read
|
|
is the address of the entry point called by @code{@value{DIRPREFIX}io_read}.
|
|
|
|
@item write
|
|
is the address of the entry point called by @code{@value{DIRPREFIX}io_write}.
|
|
|
|
@item control
|
|
is the address of the entry point called by @code{@value{DIRPREFIX}io_control}.
|
|
|
|
@end table
|
|
|
|
Driver entry points configured as NULL will always
|
|
return a status code of @code{@value{RPREFIX}SUCCESSFUL}. No user code will be
|
|
executed in this situation.
|
|
|
|
A typical declaration for a Device Driver Table might appear as follows:
|
|
|
|
@ifset is-C
|
|
@example
|
|
rtems_driver_address_table Driver_table[2] = @{
|
|
@{ tty_initialize, tty_open, tty_close, /* major = 0 */
|
|
tty_read, tty_write, tty_control
|
|
@},
|
|
@{ lp_initialize, lp_open, lp_close, /* major = 1 */
|
|
NULL, lp_write, lp_control
|
|
@}
|
|
@};
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
@end example
|
|
@end ifset
|
|
|
|
More information regarding the construction and
|
|
operation of device drivers is provided in the I/O Manager
|
|
chapter.
|
|
|
|
@section User Extensions Table
|
|
|
|
The User Extensions Table is used to inform RTEMS of
|
|
the optional user-supplied static extension set. This table
|
|
contains one entry for each possible extension. The entries are
|
|
called at critical times in the life of the system and
|
|
individual tasks. The application may create dynamic extensions
|
|
in addition to this single static set. The format of each entry
|
|
in the User Extensions Table is defined in the following @value{LANGUAGE}
|
|
@value{STRUCTURE}:
|
|
|
|
@ifset is-C
|
|
@example
|
|
typedef User_extensions_routine rtems_extension;
|
|
typedef User_extensions_thread_create_extension rtems_task_create_extension;
|
|
typedef User_extensions_thread_delete_extension rtems_task_delete_extension;
|
|
typedef User_extensions_thread_start_extension rtems_task_start_extension;
|
|
typedef User_extensions_thread_restart_extension rtems_task_restart_extension;
|
|
typedef User_extensions_thread_switch_extension rtems_task_switch_extension;
|
|
typedef User_extensions_thread_begin_extension rtems_task_begin_extension;
|
|
typedef User_extensions_thread_exitted_extension rtems_task_exitted_extension;
|
|
typedef User_extensions_fatal_extension rtems_fatal_extension;
|
|
|
|
typedef User_extensions_Table rtems_extensions_table;
|
|
|
|
typedef struct @{
|
|
rtems_task_create_extension thread_create;
|
|
rtems_task_start_extension thread_start;
|
|
rtems_task_restart_extension thread_restart;
|
|
rtems_task_delete_extension thread_delete;
|
|
rtems_task_switch_extension thread_switch;
|
|
rtems_task_post_switch_extension thread_post_switch;
|
|
rtems_task_begin_extension thread_begin;
|
|
rtems_task_exitted_extension thread_exitted;
|
|
rtems_fatal_extension fatal;
|
|
@} User_extensions_Table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
type Extensions_Table_Entry is
|
|
record
|
|
Thread_Create : RTEMS.Thread_Create_Extension;
|
|
Thread_Start : RTEMS.Thread_Start_Extension;
|
|
Thread_Restart : RTEMS.Thread_Restart_Extension;
|
|
Thread_Delete : RTEMS.Thread_Delete_Extension;
|
|
Thread_Switch : RTEMS.Thread_Switch_Extension;
|
|
Thread_Post_Switch : RTEMS.Thread_Post_Switch_Extension;
|
|
Thread_Begin : RTEMS.Thread_Begin_Extension;
|
|
Thread_Exitted : RTEMS.Thread_Exitted_Extension;
|
|
Fatal : RTEMS.Fatal_Error_Extension;
|
|
end record;
|
|
@end example
|
|
@end ifset
|
|
|
|
@table @b
|
|
|
|
@item thread_create
|
|
is the address of the
|
|
user-supplied subroutine for the TASK_CREATE extension. If this
|
|
extension for task creation is defined, it is called from the
|
|
task_create directive. A value of NULL indicates that no
|
|
extension is provided.
|
|
|
|
@item thread_start
|
|
is the address of the user-supplied
|
|
subroutine for the TASK_START extension. If this extension for
|
|
task initiation is defined, it is called from the task_start
|
|
directive. A value of NULL indicates that no extension is
|
|
provided.
|
|
|
|
@item thread_restart
|
|
is the address of the user-supplied
|
|
subroutine for the TASK_RESTART extension. If this extension
|
|
for task re-initiation is defined, it is called from the
|
|
task_restart directive. A value of NULL indicates that no
|
|
extension is provided.
|
|
|
|
@item thread_delete
|
|
is the address of the user-supplied
|
|
subroutine for the TASK_DELETE extension. If this RTEMS
|
|
extension for task deletion is defined, it is called from the
|
|
task_delete directive. A value of NULL indicates that no
|
|
extension is provided.
|
|
|
|
@item thread_switch
|
|
is the address of the user-supplied
|
|
subroutine for the task context switch extension. This
|
|
subroutine is called from RTEMS dispatcher after the current
|
|
task has been swapped out but before the new task has been
|
|
swapped in. A value of NULL indicates that no extension is
|
|
provided. As this routine is invoked after saving the current
|
|
task's context and before restoring the heir task's context, it
|
|
is not necessary for this routine to save and restore any
|
|
registers.
|
|
|
|
@item thread_post_switch
|
|
is the address of the
|
|
user-supplied subroutine for the post task context switch
|
|
extension. This subroutine is called from RTEMS dispatcher in
|
|
the context of the task which has just been swapped in.
|
|
|
|
@item thread_begin
|
|
is the address of the user-supplied
|
|
subroutine which is invoked immediately before a task begins
|
|
execution. It is invoked in the context of the beginning task.
|
|
A value of NULL indicates that no extension is provided.
|
|
|
|
@item thread_exitted
|
|
is the address of the user-supplied
|
|
subroutine which is invoked when a task exits. This procedure
|
|
is responsible for some action which will allow the system to
|
|
continue execution (i.e. delete or restart the task) or to
|
|
terminate with a fatal error. If this field is set to NULL, the
|
|
default RTEMS TASK_EXITTED handler will be invoked.
|
|
|
|
@item fatal
|
|
is the address of the user-supplied
|
|
subroutine for the FATAL extension. This RTEMS extension of
|
|
fatal error handling is called from the
|
|
@code{@value{DIRPREFIX}fatal_error_occurred}
|
|
directive. If the user's fatal error handler returns or if this
|
|
entry is NULL then the default RTEMS fatal error handler will be
|
|
executed.
|
|
|
|
@end table
|
|
|
|
A typical declaration for a User Extension Table
|
|
which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and
|
|
FATAL extension might appear as follows:
|
|
|
|
@ifset is-C
|
|
@example
|
|
rtems_extensions_table User_extensions = @{
|
|
task_create_extension,
|
|
NULL,
|
|
NULL,
|
|
task_delete_extension,
|
|
task_switch_extension,
|
|
NULL,
|
|
NULL,
|
|
fatal_extension
|
|
@};
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
User_Extensions : RTEMS.Extensions_Table := (
|
|
Task_Create_Extension'Access,
|
|
null,
|
|
null,
|
|
Task_Delete_Extension'Access,
|
|
Task_Switch_Extension'Access,
|
|
null,
|
|
null,
|
|
Fatal_Extension'Access
|
|
);
|
|
@example
|
|
|
|
@end example
|
|
@end ifset
|
|
|
|
More information regarding the user extensions is
|
|
provided in the User Extensions chapter.
|
|
|
|
@section Multiprocessor Configuration Table
|
|
|
|
The Multiprocessor Configuration Table contains
|
|
information needed when using RTEMS in a multiprocessor
|
|
configuration. Many of the details associated with configuring
|
|
a multiprocessor system are dependent on the multiprocessor
|
|
communications layer provided by the user. The address of the
|
|
Multiprocessor Configuration Table should be placed in the
|
|
User_multiprocessing_table entry in the primary Configuration
|
|
Table. Further details regarding many of the entries in the
|
|
Multiprocessor Configuration Table will be provided in the
|
|
Multiprocessing chapter. The format of the Multiprocessor
|
|
Configuration Table is defined in
|
|
the following @value{LANGUAGE} @value{STRUCTURE}:
|
|
|
|
@ifset is-C
|
|
@example
|
|
typedef struct @{
|
|
rtems_unsigned32 node;
|
|
rtems_unsigned32 maximum_nodes;
|
|
rtems_unsigned32 maximum_global_objects;
|
|
rtems_unsigned32 maximum_proxies;
|
|
rtems_mpci_table *User_mpci_table;
|
|
@} rtems_multiprocessing_table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
type Multiprocessing_Table is
|
|
record
|
|
Node : RTEMS.Unsigned32;
|
|
Maximum_Nodes : RTEMS.Unsigned32;
|
|
Maximum_Global_Objects : RTEMS.Unsigned32;
|
|
Maximum_Proxies : RTEMS.Unsigned32;
|
|
User_MPCI_Table : RTEMS.MPCI_Table_Pointer;
|
|
end record;
|
|
|
|
type Multiprocessing_Table_Pointer is access all Multiprocessing_Table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@table @b
|
|
@item node
|
|
is a unique processor identifier
|
|
and is used in routing messages between nodes in a
|
|
multiprocessor configuration. Each processor must have a unique
|
|
node number. RTEMS assumes that node numbers start at one and
|
|
increase sequentially. This assumption can be used to advantage
|
|
by the user-supplied MPCI layer. Typically, this requirement is
|
|
made when the node numbers are used to calculate the address of
|
|
inter-processor communication links. Zero should be avoided as
|
|
a node number because some MPCI layers use node zero to
|
|
represent broadcasted packets. Thus, it is recommended that
|
|
node numbers start at one and increase sequentially.
|
|
|
|
@item maximum_nodes
|
|
is the number of processor nodes in the system.
|
|
|
|
@item maximum_global_objects
|
|
is the maximum number of global objects which can exist at any
|
|
given moment in the entire system. If this parameter is not the
|
|
same on all nodes in the system, then a fatal error is generated
|
|
to inform the user that the system is inconsistent.
|
|
|
|
@item maximum_proxies
|
|
is the maximum number of proxies which can exist at any given moment
|
|
on this particular node. A proxy is a substitute task control block
|
|
which represent a task residing on a remote node when that task blocks
|
|
on a remote object. Proxies are used in situations in which delayed
|
|
interaction is required with a remote node.
|
|
|
|
@item User_mpci_table
|
|
is the address of the Multiprocessor Communications Interface
|
|
Table. This table contains the entry points of user-provided functions
|
|
which constitute the multiprocessor communications layer. This table
|
|
must be provided in multiprocessor configurations with all
|
|
entries configured. The format of this table and details
|
|
regarding its entries can be found in the next section.
|
|
|
|
@end table
|
|
|
|
@section Multiprocessor Communications Interface Table
|
|
|
|
The format of this table is defined in
|
|
the following @value{LANGUAGE} @value{STRUCTURE}:
|
|
|
|
@ifset is-C
|
|
@example
|
|
typedef struct @{
|
|
rtems_unsigned32 default_timeout; /* in ticks */
|
|
rtems_unsigned32 maximum_packet_size;
|
|
rtems_mpci_initialization_entry initialization;
|
|
rtems_mpci_get_packet_entry get_packet;
|
|
rtems_mpci_return_packet_entry return_packet;
|
|
rtems_mpci_send_entry send;
|
|
rtems_mpci_receive_entry receive;
|
|
@} rtems_mpci_table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
type MPCI_Table is
|
|
record
|
|
Default_Timeout : RTEMS.Unsigned32; -- in ticks
|
|
Maximum_Packet_Size : RTEMS.Unsigned32;
|
|
Initialization : RTEMS.MPCI_Initialization_Entry;
|
|
Get_Packet : RTEMS.MPCI_Get_Packet_Entry;
|
|
Return_Packet : RTEMS.MPCI_Return_Packet_Entry;
|
|
Send : RTEMS.MPCI_Send_Entry;
|
|
Receive : RTEMS.MPCI_Receive_Entry;
|
|
end record;
|
|
|
|
type MPCI_Table_Pointer is access all MPCI_Table;
|
|
@end example
|
|
@end ifset
|
|
|
|
@table @b
|
|
@item default_timeout
|
|
is the default maximum length of time a task should block waiting for
|
|
a response to a directive which results in communication with a remote node.
|
|
The maximum length of time is a function the user supplied
|
|
multiprocessor communications layer and the media used. This
|
|
timeout only applies to directives which would not block if the
|
|
operation were performed locally.
|
|
|
|
@item maximum_packet_size
|
|
is the size in bytes of the longest packet which the MPCI layer is capable
|
|
of sending. This value should represent the total number of bytes available
|
|
for a RTEMS interprocessor messages.
|
|
|
|
@item initialization
|
|
is the address of the entry point for the initialization procedure of the
|
|
user supplied multiprocessor communications layer.
|
|
|
|
@item get_packet
|
|
is the address of the entry point for the procedure called by RTEMS to
|
|
obtain a packet from the user supplied multiprocessor communications layer.
|
|
|
|
@item return_packet
|
|
is the address of the entry point for the procedure called by RTEMS to
|
|
return a packet to the user supplied multiprocessor communications layer.
|
|
|
|
@item send
|
|
is the address of the entry point for the procedure called by RTEMS to
|
|
send an envelope to another node. This procedure is part of the user
|
|
supplied multiprocessor communications layer.
|
|
|
|
@item receive
|
|
is the address of the entry point for the
|
|
procedure called by RTEMS to retrieve an envelope containing a
|
|
message from another node. This procedure is part of the user
|
|
supplied multiprocessor communications layer.
|
|
|
|
@end table
|
|
|
|
More information regarding the required functionality of these
|
|
entry points is provided in the Multiprocessor chapter.
|
|
|
|
@section Determining Memory Requirements
|
|
|
|
Since memory is a critical resource in many real-time
|
|
embedded systems, RTEMS was specifically designed to allow
|
|
unused managers to be excluded from the run-time environment.
|
|
This allows the application designer the flexibility to tailor
|
|
RTEMS to most efficiently meet system requirements while still
|
|
satisfying even the most stringent memory constraints. As
|
|
result, the size of the RTEMS executive is application
|
|
dependent. A Memory Requirements worksheet is provided in the
|
|
Applications Supplement document for a specific target
|
|
processor. This worksheet can be used to calculate the memory
|
|
requirements of a custom RTEMS run-time environment. To insure
|
|
that enough memory is allocated for future versions of RTEMS,
|
|
the application designer should round these memory requirements
|
|
up. The following managers may be optionally excluded:
|
|
|
|
@itemize @bullet
|
|
@item signal
|
|
@item region
|
|
@item dual ported memory
|
|
@item event
|
|
@item multiprocessing
|
|
@item partition
|
|
@item timer
|
|
@item semaphore
|
|
@item message
|
|
@item rate monotonic
|
|
@end itemize
|
|
|
|
RTEMS based applications must somehow provide memory
|
|
for RTEMS' code and data space. Although RTEMS' data space must
|
|
be in RAM, its code space can be located in either ROM or RAM.
|
|
In addition, the user must allocate RAM for the RTEMS RAM
|
|
Workspace. The size of this area is application dependent and
|
|
can be calculated using the formula provided in the Memory
|
|
Requirements chapter of the Applications Supplement document
|
|
for a specific target processor.
|
|
|
|
All RTEMS data variables and routine names used by
|
|
RTEMS begin with the underscore ( _ ) character followed by an
|
|
upper-case letter. If RTEMS is linked with an application, then
|
|
the application code should NOT contain any symbols which begin
|
|
with the underscore character and followed by an upper-case
|
|
letter to avoid any naming conflicts. All RTEMS directive names
|
|
should be treated as reserved words.
|
|
|
|
@section Sizing the RTEMS RAM Workspace
|
|
|
|
The RTEMS RAM Workspace is a user-specified block of
|
|
memory reserved for use by RTEMS. The application should NOT
|
|
modify this memory. This area consists primarily of the RTEMS
|
|
data structures whose exact size depends upon the values
|
|
specified in the Configuration Table. In addition, task stacks
|
|
and floating point context areas are dynamically allocated from
|
|
the RTEMS RAM Workspace.
|
|
|
|
The starting address of the RTEMS RAM Workspace must
|
|
be aligned on a four-byte boundary. Failure to properly align
|
|
the workspace area will result in the
|
|
@code{@value{DIRPREFIX}fatal_error_occurred}
|
|
directive being invoked with the
|
|
@code{@value{RPREFIX}INVALID_ADDRESS} error code.
|
|
|
|
A worksheet is provided in the Memory Requirements
|
|
chapter of the Applications Supplement document for a specific
|
|
target processor to assist the user in calculating the minimum
|
|
size of the RTEMS RAM Workspace for each application. The value
|
|
calculated with this worksheet is the minimum value that should
|
|
be specified as the work_space_size parameter of the
|
|
Configuration Table. The user is cautioned that future versions
|
|
of RTEMS may not have the same memory requirements per object.
|
|
Although the value calculated is sufficient for a particular
|
|
target processor and release of RTEMS, memory usage is subject
|
|
to change across versions and target processors. The user is
|
|
advised to allocate somewhat more memory than the worksheet
|
|
recommends to insure compatibility with future releases for a
|
|
specific target processor and other target processors. To avoid
|
|
problems, the user should recalculate the memory requirements
|
|
each time one of the following events occurs:
|
|
|
|
@itemize @bullet
|
|
@item a configuration parameter is modified,
|
|
@item task or interrupt stack requirements change,
|
|
@item task floating point attribute is altered,
|
|
@item RTEMS is upgraded, or
|
|
@item the target processor is changed.
|
|
@end itemize
|
|
|
|
Failure to provide enough space in the RTEMS RAM
|
|
Workspace will result in the
|
|
@code{@value{DIRPREFIX}fatal_error_occurred} directive
|
|
being invoked with the appropriate error code.
|