mirror of
https://gitlab.rtems.org/rtems/rtos/rtems.git
synced 2025-12-06 15:43:15 +00:00
6d0009508f
* io.t, conf.t: PR 160. Added the IO Manager's register and unregister interface documentation.
2029 lines
75 KiB
Perl
2029 lines
75 KiB
Perl
@c COPYRIGHT (c) 1988-2002.
|
|
@c On-Line Applications Research Corporation (OAR).
|
|
@c All rights reserved.
|
|
@c
|
|
@c $Id$
|
|
@c
|
|
|
|
@c The following macros from confdefs.h have not been discussed in this
|
|
@c chapter:
|
|
@c
|
|
@c CONFIGURE_NEWLIB_EXTENSION - probably not needed
|
|
@c CONFIGURE_MALLOC_REGION - probably not needed
|
|
@c CONFIGURE_LIBIO_SEMAPHORES - implicitly discussed.
|
|
@c CONFIGURE_INTERRUPT_STACK_MEMORY
|
|
@c CONFIGURE_GNAT_RTEMS
|
|
@c CONFIGURE_GNAT_MUTEXES
|
|
@c CONFIGURE_GNAT_KEYS
|
|
@c CONFIGURE_MAXIMUM_ADA_TASKS
|
|
@c CONFIGURE_MAXIMUM_FAKE_ADA_TASKS
|
|
@c CONFIGURE_ADA_TASKS_STACK
|
|
@c
|
|
@c In addition, there should be examples of defining your own
|
|
@c Device Driver Table, Init task table, etc.
|
|
@c
|
|
@c Regardless, this is a big step up. :)
|
|
@c
|
|
|
|
@chapter Configuring a System
|
|
|
|
@section Introduction
|
|
|
|
RTEMS must be configured for an application. This configuration
|
|
information encompasses a variety of information including
|
|
the length of each clock tick, the maximum number of each RTEMS
|
|
object that can be created, the application initialization tasks,
|
|
and the device drivers in the application. This information
|
|
is placed in data structures that are given to RTEMS at
|
|
system initialization time. This chapter details the
|
|
format of these data structures as well as a simpler
|
|
mechanism to automate the generation of these structures.
|
|
|
|
|
|
@section Automatic Generation of System Configuration
|
|
|
|
@cindex confdefs.h
|
|
@findex confdefs.h
|
|
|
|
RTEMS provides the @code{confdefs.h} C language header file that
|
|
based on the setting of a variety of macros can automatically
|
|
produce nearly all of the configuration tables required
|
|
by an RTEMS application. Rather than building the individual
|
|
tables by hand, the application simply specifies the values
|
|
for the configuration parameters it wishes to set. In the following
|
|
example, the configuration information for a simple system with
|
|
a message queue and a time slice of 50 milliseconds is configured:
|
|
|
|
@example
|
|
@group
|
|
#define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
|
|
#define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
|
|
|
|
#define CONFIGURE_MICROSECONDS_PER_TICK 1000 /* 1 millisecond */
|
|
#define CONFIGURE_TICKS_PER_TIMESLICE 50 /* 50 milliseconds */
|
|
|
|
#define CONFIGURE_MAXIMUM_TASKS 4
|
|
#define CONFIGURE_RTEMS_INIT_TASKS_TABLE
|
|
@end group
|
|
@end example
|
|
|
|
This system will begin execution with the single initialization task
|
|
named @code{Init}. It will be configured to have both a console
|
|
device driver (for standard I/O) and a clock tick device driver.
|
|
|
|
For each configuration parameter in the configuration tables, the
|
|
macro corresponding to that field is discussed. Most systems
|
|
can be easily configured using the @code{confdefs.h} mechanism.
|
|
|
|
The @code{CONFIGURE_INIT} constant must be defined in order to
|
|
make @code{confdefs.h} instantiate the configuration data
|
|
structures. This can only be defined in one source file per
|
|
application that includes @code{confdefs.h} or the symbol
|
|
table will be instantiated multiple times and linking errors
|
|
produced.
|
|
|
|
The user should be aware that the defaults are intentionally
|
|
set as low as possible. By default, no application resources
|
|
are configured. The @code{confdefs.h} file ensures that
|
|
at least one application tasks or thread is configured
|
|
and that at least one of the initialization task/thread
|
|
tables is configured.
|
|
|
|
The @code{confdefs.h} file estimates the amount of
|
|
memory required for the RTEMS Executive Workspace. This
|
|
estimate is only as accurate as the information given
|
|
to @code{confdefs.h} and may be either too high or too
|
|
low for a variety of reasons. Some of the reasons that
|
|
@code{confdefs.h} may reserve too much memory for RTEMS
|
|
are:
|
|
|
|
@itemize @bullet
|
|
@item All tasks/threads are assumed to be floating point.
|
|
@end itemize
|
|
|
|
Conversely, there are many more reasons, the resource
|
|
estimate could be too low:
|
|
|
|
@itemize @bullet
|
|
@item Task/thread stacks greater than minimum size must be
|
|
accounted for explicitly by developer.
|
|
|
|
@item Memory for messages is not included.
|
|
|
|
@item Device driver requirements are not included.
|
|
|
|
|
|
@item Network stack requirements are not included.
|
|
|
|
@item Requirements for add-on libraries are not included.
|
|
@end itemize
|
|
|
|
In general, @code{confdefs.h} is very accurate when given
|
|
enough information. However, it is quite easy to use
|
|
a library and not account for its resources.
|
|
|
|
The following subsection list all of the constants which can be
|
|
set by the user.
|
|
|
|
@subsection Library Support Definitions
|
|
|
|
This section defines the file system and IO library
|
|
related configuration parameters supported by
|
|
@code{confdefs.h}.
|
|
|
|
@itemize @bullet
|
|
@findex CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS
|
|
@item @code{CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS} is set to the
|
|
maximum number of files that can be concurrently open. Libio requires
|
|
a Classic RTEMS semaphore for each file descriptor as well as one
|
|
global one. The default value is 3 file descriptors which is
|
|
enough to support standard input, output, and error output.
|
|
|
|
@findex CONFIGURE_TERMIOS_DISABLED
|
|
@item @code{CONFIGURE_TERMIOS_DISABLED} is defined if the
|
|
software implementing POSIX termios functionality is
|
|
not going to be used by this application. By default, this
|
|
is not defined and resources are reserved for the
|
|
termios functionality.
|
|
|
|
@findex CONFIGURE_NUMBER_OF_TERMIOS_PORTS
|
|
@item @code{CONFIGURE_NUMBER_OF_TERMIOS_PORTS} is set to the
|
|
number of ports using the termios functionality. Each
|
|
concurrently active termios port requires resources.
|
|
By default, this is set to 1 so a console port can be
|
|
used.
|
|
|
|
@findex CONFIGURE_HAS_OWN_MOUNT_TABLE
|
|
@item @code{CONFIGURE_HAS_OWN_MOUNT_TABLE} is defined when the
|
|
application provides their own filesystem mount table. The
|
|
mount table is an array of @code{rtems_filesystem_mount_table_t}
|
|
entries pointed to by the global variable
|
|
@code{rtems_filesystem_mount_table}. The number of
|
|
entries in this table is in an integer variable named
|
|
@code{rtems_filesystem_mount_table_t}.
|
|
|
|
@findex CONFIGURE_USE_IMFS_AS_BASE_FILESYSTEM
|
|
@item @code{CONFIGURE_USE_IMFS_AS_BASE_FILESYSTEM} is defined
|
|
if the application wishes to use the full functionality
|
|
IMFS. By default, the miniIMFS is used. The miniIMFS
|
|
is a minimal functionality subset of the In-Memory
|
|
FileSystem (IMFS). The miniIMFS is comparable
|
|
in functionality to the pseudo-filesystem name space provided
|
|
before RTEMS release 4.5.0. The miniIMFS supports
|
|
only directories and device nodes and is smaller in executable
|
|
code size than the full IMFS.
|
|
|
|
@findex STACK_CHECKER_ON
|
|
@item @code{STACK_CHECKER_ON} is defined when the application
|
|
wishes to enable run-time stack bounds checking. This increases
|
|
the time required to create tasks as well as adding overhead
|
|
to each context switch. By default, this is not defined and
|
|
thus stack checking is disabled.
|
|
|
|
@end itemize
|
|
|
|
@subsection Basic System Information
|
|
|
|
This section defines the general system configuration parameters supported by
|
|
@code{confdefs.h}.
|
|
|
|
@itemize @bullet
|
|
@findex CONFIGURE_HAS_OWN_CONFIGURATION_TABLE
|
|
@item @code{CONFIGURE_HAS_OWN_CONFIGURATION_TABLE} should only be defined
|
|
if the application is providing their own complete set of configuration
|
|
tables.
|
|
|
|
@findex CONFIGURE_INTERRUPT_STACK_MEMORY
|
|
@item @code{CONFIGURE_INTERRUPT_STACK_MEMORY} is set to the
|
|
size of the interrupt stack. The interrupt stack size is
|
|
usually set by the BSP but since this memory is allocated
|
|
from the RTEMS Ram Workspace, it must be accounted for. The
|
|
default for this field is RTEMS_MINIMUM_STACK_SIZE. [NOTE:
|
|
At this time, changing this constant does NOT change the
|
|
size of the interrupt stack, only the amount of memory
|
|
reserved for it.]
|
|
|
|
@findex CONFIGURE_EXECUTIVE_RAM_WORK_AREA
|
|
@item @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA} is the base
|
|
address of the RTEMS RAM Workspace. By default, this value
|
|
is NULL indicating that the BSP is to determine the location
|
|
of the RTEMS RAM Workspace.
|
|
|
|
@findex CONFIGURE_MICROSECONDS_PER_TICK
|
|
@item @code{CONFIGURE_MICROSECONDS_PER_TICK} is the length
|
|
of time between clock ticks. By default, this is set to
|
|
10000 microseconds.
|
|
|
|
@findex CONFIGURE_TICKS_PER_TIMESLICE
|
|
@item @code{CONFIGURE_TICKS_PER_TIMESLICE} is the number
|
|
of ticks per each task's timeslice. By default, this is
|
|
50.
|
|
|
|
@findex CONFIGURE_MEMORY_OVERHEAD
|
|
@item @code{CONFIGURE_MEMORY_OVERHEAD} is set to the number of
|
|
bytes the applications wishes to add to the requirements calculated
|
|
by @code{confdefs.h}. The default value is 0.
|
|
|
|
@findex CONFIGURE_EXTRA_TASK_STACKS
|
|
@item @code{CONFIGURE_EXTRA_TASK_STACKS} is set to the number of
|
|
bytes the applications wishes to add to the task stack requirements
|
|
calculated by @code{confdefs.h}. This parameter is very important.
|
|
If the application creates tasks with stacks larger then the
|
|
minimum, then that memory is NOT accounted for by @code{confdefs.h}.
|
|
The default value is 0.
|
|
|
|
@end itemize
|
|
|
|
NOTE: The required size of the Executive RAM Work Area is calculated
|
|
automatically when using the @code{confdefs.h} mechanism.
|
|
|
|
@subsection Device Driver Table
|
|
|
|
This section defines the configuration parameters related
|
|
to the automatic generation of a Device Driver Table. As
|
|
@code{confdefs.h} only is aware of a small set of
|
|
standard device drivers, the generated Device Driver
|
|
Table is suitable for simple applications with no
|
|
custom device drivers.
|
|
|
|
@itemize @bullet
|
|
@findex CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE
|
|
@item @code{CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE} is defined if
|
|
the application wishes to provide their own Device Driver Table.
|
|
The table generated is an array of @code{rtems_driver_address_table}
|
|
entries named @code{Device_drivers}. By default, this is not
|
|
defined indicating the @code{confdefs.h} is providing the
|
|
device driver table.
|
|
|
|
@findex CONFIGURE_MAXIMUM_DRIVERS
|
|
@item @code{CONFIGURE_MAXIMUM_DRIVERS} is defined
|
|
as the number of device drivers per node. By default, this is
|
|
set to 10.
|
|
|
|
@findex CONFIGURE_MAXIMUM_DEVICES
|
|
@item @code{CONFIGURE_MAXIMUM_DEVICES} is defined
|
|
to the number of individual devices that may be registered
|
|
in the system. By default, this is set to 20.
|
|
|
|
@findex CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
|
|
@item @code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER}
|
|
is defined
|
|
if the application wishes to include the Console Device Driver.
|
|
This device driver is responsible for providing standard input
|
|
and output using "/dev/console". By default, this is not
|
|
defined.
|
|
|
|
@findex CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
|
|
@item @code{CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER}
|
|
is defined
|
|
if the application wishes to include the Console Device Driver.
|
|
This device driver is responsible for providing standard input
|
|
and output using "/dev/console". By default, this is not
|
|
defined.
|
|
|
|
@findex CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
|
|
@item @code{CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER}
|
|
is defined if the application wishes to include the Timer Driver.
|
|
This device driver is used to benchmark execution times
|
|
by the RTEMS Timing Test Suites. By default, this is not
|
|
defined.
|
|
|
|
@c @item @code{CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER}
|
|
@c is defined
|
|
@c if the application wishes to include the Real-Time Clock Driver.
|
|
@c By default, this is not defined.
|
|
|
|
@findex CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER
|
|
@item @code{CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER}
|
|
is defined if the application wishes to include the Stub Device Driver.
|
|
This device driver simply provides entry points that return
|
|
successful and is primarily a test fixture.
|
|
By default, this is not defined.
|
|
|
|
@end itemize
|
|
|
|
@subsection Multiprocessing Configuration
|
|
|
|
This section defines the multiprocessing related
|
|
system configuration parameters supported by @code{confdefs.h}.
|
|
This class of Configuration Constants are only applicable if
|
|
@code{CONFIGURE_MP_APPLICATION} is defined.
|
|
|
|
@itemize @bullet
|
|
@findex CONFIGURE_HAS_OWN_MULTIPROCESING_TABLE
|
|
@item @code{CONFIGURE_HAS_OWN_MULTIPROCESING_TABLE} is defined
|
|
if the application wishes to provide their own Multiprocessing
|
|
Configuration Table. The generated table is named
|
|
@code{Multiprocessing_configuration}. By default, this
|
|
is not defined.
|
|
|
|
@findex CONFIGURE_MP_NODE_NUMBER
|
|
@item @code{CONFIGURE_MP_NODE_NUMBER} is the node number of
|
|
this node in a multiprocessor system. The default node number
|
|
is @code{NODE_NUMBER} which is set directly in RTEMS test Makefiles.
|
|
|
|
@findex CONFIGURE_MP_MAXIMUM_NODES
|
|
@item @code{CONFIGURE_MP_MAXIMUM_NODES} is the maximum number
|
|
of nodes in a multiprocessor system. The default is 2.
|
|
|
|
@findex CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS
|
|
@item @code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS}
|
|
is the maximum number
|
|
of concurrently active global objects in a multiprocessor
|
|
system. The default is 32.
|
|
|
|
@findex CONFIGURE_MP_MAXIMUM_PROXIES
|
|
@item @code{CONFIGURE_MP_MAXIMUM_PROXIES} is the maximum number
|
|
of concurrently active thread/task proxies in a multiprocessor
|
|
system. The default is 32.
|
|
|
|
@findex CONFIGURE_MP_MPCI_TABLE_POINTER
|
|
@item @code{CONFIGURE_MP_MPCI_TABLE_POINTER} is the pointer
|
|
to the MPCI Configuration Table. The default value of
|
|
this field is @code{&MPCI_table}.
|
|
@end itemize
|
|
|
|
@subsection Classic API Configuration
|
|
|
|
This section defines the Classic API related
|
|
system configuration parameters supported by @code{confdefs.h}.
|
|
|
|
@itemize @bullet
|
|
@findex CONFIGURE_MAXIMUM_TASKS
|
|
@item @code{CONFIGURE_MAXIMUM_TASKS} is the maximum number of
|
|
Classic API tasks that can be concurrently active.
|
|
The default for this field is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_TIMERS
|
|
@item @code{CONFIGURE_MAXIMUM_TIMERS} is the maximum number of
|
|
Classic API timers that can be concurrently active.
|
|
The default for this field is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_SEMAPHORES
|
|
@item @code{CONFIGURE_MAXIMUM_SEMAPHORES} is the maximum number of
|
|
Classic API semaphores that can be concurrently active.
|
|
The default for this field is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_MESSAGE_QUEUES
|
|
@item @code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES} is the maximum number of
|
|
Classic API message queues that can be concurrently active.
|
|
The default for this field is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_PARTITIONS
|
|
@item @code{CONFIGURE_MAXIMUM_PARTITIONS} is the maximum number of
|
|
Classic API partitions that can be concurrently active.
|
|
The default for this field is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_REGIONS
|
|
@item @code{CONFIGURE_MAXIMUM_REGIONS} is the maximum number of
|
|
Classic API regions that can be concurrently active.
|
|
The default for this field is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_PORTS
|
|
@item @code{CONFIGURE_MAXIMUM_PORTS} is the maximum number of
|
|
Classic API ports that can be concurrently active.
|
|
The default for this field is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_PERIODS
|
|
@item @code{CONFIGURE_MAXIMUM_PERIODS} is the maximum number of
|
|
Classic API rate monotonic periods that can be concurrently active.
|
|
The default for this field is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_USER_EXTENSIONS
|
|
@item @code{CONFIGURE_MAXIMUM_USER_EXTENSIONS} is the maximum number of
|
|
Classic API user extensions that can be concurrently active.
|
|
The default for this field is 0.
|
|
|
|
@end itemize
|
|
|
|
@subsection Classic API Initialization Tasks Table Configuration
|
|
|
|
The @code{confdefs.h} configuration system can automatically
|
|
generate an Initialization Tasks Table named
|
|
@code{Initialization_tasks} with a single entry. The following
|
|
parameters control the generation of that table.
|
|
|
|
@itemize @bullet
|
|
@findex CONFIGURE_RTEMS_INIT_TASKS_TABLE
|
|
@item @code{CONFIGURE_RTEMS_INIT_TASKS_TABLE} is defined
|
|
if the user wishes to use a Classic RTEMS API Initialization
|
|
Task Table. The application may choose to use the initialization
|
|
tasks or threads table from another API. By default, this
|
|
field is not defined as the user MUST select their own
|
|
API for initialization tasks.
|
|
|
|
@findex CONFIGURE_HAS_OWN_INIT_TASK_TABLE
|
|
@item @code{CONFIGURE_HAS_OWN_INIT_TASK_TABLE} is defined
|
|
if the user wishes to define their own Classic API Initialization
|
|
Tasks Table. This table should be named @code{Initialization_tasks}.
|
|
By default, this is not defined.
|
|
|
|
@findex CONFIGURE_INIT_TASK_NAME
|
|
@item @code{CONFIGURE_INIT_TASK_NAME} is the name
|
|
of the single initialization task defined by the
|
|
Classic API Initialization Tasks Table. By default
|
|
the value is @code{rtems_build_name( 'U', 'I', '1', ' ' )}.
|
|
|
|
@findex CONFIGURE_INIT_TASK_STACK_SIZE
|
|
@item @code{CONFIGURE_INIT_TASK_STACK_SIZE}
|
|
is the stack size
|
|
of the single initialization task defined by the
|
|
Classic API Initialization Tasks Table. By default
|
|
the value is @code{RTEMS_MINIMUM_STACK_SIZE}.
|
|
|
|
@findex CONFIGURE_INIT_TASK_PRIORITY
|
|
@item @code{CONFIGURE_INIT_TASK_PRIORITY}
|
|
is the initial priority
|
|
of the single initialization task defined by the
|
|
Classic API Initialization Tasks Table. By default
|
|
the value is 1 which is the highest priority
|
|
in the Classic API.
|
|
|
|
@findex CONFIGURE_INIT_TASK_ATTRIBUTES
|
|
@item @code{CONFIGURE_INIT_TASK_ATTRIBUTES}
|
|
is the task attributes
|
|
of the single initialization task defined by the
|
|
Classic API Initialization Tasks Table. By default
|
|
the value is @code{RTEMS_DEFAULT_ATTRIBUTES}.
|
|
|
|
@findex CONFIGURE_INIT_TASK_ENTRY_POINT
|
|
@item @code{CONFIGURE_INIT_TASK_ENTRY_POINT}
|
|
is the entry point (a.k.a. function name)
|
|
of the single initialization task defined by the
|
|
Classic API Initialization Tasks Table. By default
|
|
the value is @code{Init}.
|
|
|
|
@findex CONFIGURE_INIT_TASK_INITIAL_MODES
|
|
@item @code{CONFIGURE_INIT_TASK_INITIAL_MODES}
|
|
is the initial execution mode
|
|
of the single initialization task defined by the
|
|
Classic API Initialization Tasks Table. By default
|
|
the value is @code{RTEMS_NO_PREEMPT}.
|
|
|
|
@findex CONFIGURE_INIT_TASK_ARGUMENTS
|
|
@item @code{CONFIGURE_INIT_TASK_ARGUMENTS}
|
|
is the task argument
|
|
of the single initialization task defined by the
|
|
Classic API Initialization Tasks Table. By default
|
|
the value is 0.
|
|
|
|
@end itemize
|
|
|
|
|
|
@subsection POSIX API Configuration
|
|
|
|
The parameters in this section are used to configure resources
|
|
for the RTEMS POSIX API. They are only relevant if the POSIX API
|
|
is enabled at configure time using the @code{--enable-posix} option.
|
|
|
|
@itemize @bullet
|
|
@findex CONFIGURE_MAXIMUM_POSIX_THREADS
|
|
@item @code{CONFIGURE_MAXIMUM_POSIX_THREADS} is the maximum number of
|
|
POSIX API threads that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_POSIX_MUTEXES
|
|
@item @code{CONFIGURE_MAXIMUM_POSIX_MUTEXES} is the maximum number of
|
|
POSIX API mutexes that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES
|
|
@item @code{CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES} is the maximum number of
|
|
POSIX API condition variables that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_POSIX_KEYS
|
|
@item @code{CONFIGURE_MAXIMUM_POSIX_KEYS} is the maximum number of
|
|
POSIX API keys that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_POSIX_TIMERS
|
|
@item @code{CONFIGURE_MAXIMUM_POSIX_TIMERS} is the maximum number of
|
|
POSIX API timers that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS
|
|
@item @code{CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS} is the maximum number of
|
|
POSIX API queued signals that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES
|
|
@item @code{CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES} is the maximum number of
|
|
POSIX API message queues that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_POSIX_SEMAPHORES
|
|
@item @code{CONFIGURE_MAXIMUM_POSIX_SEMAPHORES} is the maximum number of
|
|
POSIX API semaphores that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@end itemize
|
|
|
|
@subsection POSIX Initialization Threads Table Configuration
|
|
|
|
The @code{confdefs.h} configuration system can automatically
|
|
generate a POSIX Initialization Threads Table named
|
|
@code{POSIX_Initialization_threads} with a single entry. The following
|
|
parameters control the generation of that table.
|
|
|
|
@itemize @bullet
|
|
@findex CONFIGURE_POSIX_INIT_THREAD_TABLE
|
|
@item @code{CONFIGURE_POSIX_INIT_THREAD_TABLE}
|
|
is defined
|
|
if the user wishes to use a POSIX API Initialization
|
|
Threads Table. The application may choose to use the initialization
|
|
tasks or threads table from another API. By default, this
|
|
field is not defined as the user MUST select their own
|
|
API for initialization tasks.
|
|
|
|
@findex CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE
|
|
@item @code{CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE}
|
|
is defined if the user wishes to define their own POSIX API Initialization
|
|
Threads Table. This table should be named @code{POSIX_Initialization_threads}.
|
|
By default, this is not defined.
|
|
|
|
@findex CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT
|
|
@item @code{CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT}
|
|
is the entry point (a.k.a. function name)
|
|
of the single initialization thread defined by the
|
|
POSIX API Initialization Threads Table. By default
|
|
the value is @code{POSIX_Init}.
|
|
|
|
@findex CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE
|
|
@item @code{CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE}
|
|
is the stack size of the single initialization thread defined by the
|
|
POSIX API Initialization Threads Table. By default
|
|
the value is @code{RTEMS_MINIMUM_STACK_SIZE * 2}.
|
|
|
|
@end itemize
|
|
|
|
@subsection ITRON API Configuration
|
|
|
|
The parameters in this section are used to configure resources
|
|
for the RTEMS ITRON API. They are only relevant if the POSIX API
|
|
is enabled at configure time using the @code{--enable-itron} option.
|
|
|
|
@itemize @bullet
|
|
@findex CONFIGURE_MAXIMUM_ITRON_TASKS
|
|
@item @code{CONFIGURE_MAXIMUM_ITRON_TASKS}
|
|
is the maximum number of
|
|
ITRON API tasks that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_ITRON_SEMAPHORES
|
|
@item @code{CONFIGURE_MAXIMUM_ITRON_SEMAPHORES}
|
|
is the maximum number of
|
|
ITRON API semaphores that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_ITRON_EVENTFLAGS
|
|
@item @code{CONFIGURE_MAXIMUM_ITRON_EVENTFLAGS}
|
|
is the maximum number of
|
|
ITRON API eventflags that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_ITRON_MAILBOXES
|
|
@item @code{CONFIGURE_MAXIMUM_ITRON_MAILBOXES}
|
|
is the maximum number of
|
|
ITRON API mailboxes that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_ITRON_MESSAGE_BUFFERS
|
|
@item @code{CONFIGURE_MAXIMUM_ITRON_MESSAGE_BUFFERS}
|
|
is the maximum number of
|
|
ITRON API message buffers that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_ITRON_PORTS
|
|
@item @code{CONFIGURE_MAXIMUM_ITRON_PORTS}
|
|
is the maximum number of
|
|
ITRON API ports that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_ITRON_MEMORY_POOLS
|
|
@item @code{CONFIGURE_MAXIMUM_ITRON_MEMORY_POOLS}
|
|
is the maximum number of
|
|
ITRON API memory pools that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@findex CONFIGURE_MAXIMUM_ITRON_FIXED_MEMORY_POOLS
|
|
@item @code{CONFIGURE_MAXIMUM_ITRON_FIXED_MEMORY_POOLS}
|
|
is the maximum number of
|
|
ITRON API fixed memory pools that can be concurrently active.
|
|
The default is 0.
|
|
|
|
@end itemize
|
|
|
|
@subsection ITRON Initialization Task Table Configuration
|
|
|
|
The @code{confdefs.h} configuration system can automatically
|
|
generate an ITRON Initialization Tasks Table named
|
|
@code{ITRON_Initialization_tasks} with a single entry. The following
|
|
parameters control the generation of that table.
|
|
|
|
@itemize @bullet
|
|
@findex CONFIGURE_ITRON_INIT_TASK_TABLE
|
|
@item @code{CONFIGURE_ITRON_INIT_TASK_TABLE} is defined
|
|
if the user wishes to use a ITRON API Initialization
|
|
Tasks Table. The application may choose to use the initialization
|
|
tasks or threads table from another API. By default, this
|
|
field is not defined as the user MUST select their own
|
|
API for initialization tasks.
|
|
|
|
@findex CONFIGURE_ITRON_HAS_OWN_INIT_TASK_TABLE
|
|
@item @code{CONFIGURE_ITRON_HAS_OWN_INIT_TASK_TABLE}
|
|
is defined if the user wishes to define their own ITRON API Initialization
|
|
Tasks Table. This table should be named @code{ITRON_Initialization_tasks}.
|
|
By default, this is not defined.
|
|
|
|
@findex CONFIGURE_ITRON_INIT_TASK_ENTRY_POINT
|
|
@item @code{CONFIGURE_ITRON_INIT_TASK_ENTRY_POINT}
|
|
is the entry point (a.k.a. function name)
|
|
of the single initialization task defined by the
|
|
ITRON API Initialization Tasks Table. By default
|
|
the value is @code{ITRON_Init}.
|
|
|
|
@findex CONFIGURE_ITRON_INIT_TASK_ATTRIBUTES
|
|
@item @code{CONFIGURE_ITRON_INIT_TASK_ATTRIBUTES}
|
|
is the attribute set
|
|
of the single initialization task defined by the
|
|
ITRON API Initialization Tasks Table. By default
|
|
the value is @code{TA_HLNG}.
|
|
|
|
@findex CONFIGURE_ITRON_INIT_TASK_PRIORITY
|
|
@item @code{CONFIGURE_ITRON_INIT_TASK_PRIORITY}
|
|
is the initial priority
|
|
of the single initialization task defined by the
|
|
ITRON API Initialization Tasks Table. By default
|
|
the value is @code{1} which is the highest priority
|
|
in the ITRON API.
|
|
|
|
@findex CONFIGURE_ITRON_INIT_TASK_STACK_SIZE
|
|
@item @code{CONFIGURE_ITRON_INIT_TASK_STACK_SIZE}
|
|
is the stack size of the single initialization task defined by the
|
|
ITRON API Initialization Tasks Table. By default
|
|
the value is @code{RTEMS_MINIMUM_STACK_SIZE}.
|
|
|
|
@end itemize
|
|
|
|
@subsection Ada Tasks
|
|
|
|
This section defines the system configuration parameters supported
|
|
by @code{confdefs.h} related to configuring RTEMS to support
|
|
a task using Ada tasking with GNAT.
|
|
|
|
@itemize @bullet
|
|
@findex CONFIGURE_GNAT_RTEMS
|
|
@item @code{CONFIGURE_GNAT_RTEMS} is defined to inform
|
|
RTEMS that the GNAT Ada run-time is to be used by the
|
|
application. This configuration parameter is critical
|
|
as it makes @code{confdefs.h} configure the resources
|
|
(mutexes and keys) used implicitly by the GNAT run-time.
|
|
By default, this parameter is not defined.
|
|
|
|
@findex CONFIGURE_MAXIMUM_ADA_TASKS
|
|
@item @code{CONFIGURE_MAXIMUM_ADA_TASKS} is the
|
|
number of Ada tasks that can be concurrently active
|
|
in the system. By default, when @code{CONFIGURE_GNAT_RTEMS}
|
|
is defined, this is set to 20.
|
|
|
|
@findex CONFIGURE_MAXIMUM_FAKE_ADA_TASKS
|
|
@item @code{CONFIGURE_MAXIMUM_FAKE_ADA_TASKS} is
|
|
the number of "fake" Ada tasks that can be concurrently
|
|
active in the system. A "fake" Ada task is a non-Ada
|
|
task that makes calls back into Ada code and thus
|
|
implicitly uses the Ada run-time.
|
|
|
|
@end itemize
|
|
|
|
@section Configuration Table
|
|
|
|
@cindex Configuration Table
|
|
@cindex RTEMS 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
|
|
@findex rtems_configuration_table
|
|
@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 maximum_drivers;
|
|
rtems_unsigned32 number_of_device_drivers;
|
|
rtems_driver_address_table *Device_driver_table;
|
|
rtems_unsigned32 number_of_initial_extensions;
|
|
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;
|
|
Number_Of_Initial_Extensions : RTEMS.Unsigned32;
|
|
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}.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA}
|
|
which defaults to @code{NULL}. Normally, this field should be
|
|
configured as @code{NULL} as BSPs will assign memory for the
|
|
RTEMS RAM Workspace as part of system initialization.
|
|
|
|
@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.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_SIZE}
|
|
and is calculated based on the other system configuration settings.
|
|
|
|
@item microseconds_per_tick
|
|
is number of microseconds per clock tick.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MICROSECONDS_PER_TICK}.
|
|
If not defined by the application, then the
|
|
@code{CONFIGURE_MICROSECONDS_PER_TICK} macro defaults to 10000
|
|
(10 milliseconds).
|
|
|
|
@item ticks_per_timeslice
|
|
is the number of clock ticks for a timeslice.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_TICKS_PER_TIMESLICE}.
|
|
|
|
@item maximum_devices
|
|
is the maximum number of devices that can be registered.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_DEVICES}.
|
|
|
|
@item maximum_drivers
|
|
is the maximum number of device drivers that can be registered.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_DRIVERS}.
|
|
This value is set to @code{maximum_devices} if it is greater
|
|
than @code{maximum_drivers}.
|
|
|
|
@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 @code{User_driver_address_table} entry should be NULL.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field is calculated
|
|
automatically based on the number of entries in the
|
|
Device Driver Table. This calculation is based on the assumption
|
|
that the Device Driver Table is named @code{Device_drivers}
|
|
and defined in C. This table may be generated automatically
|
|
for simple applications using only the device drivers that correspond
|
|
to the following macros:
|
|
|
|
@itemize @bullet
|
|
|
|
@item @code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER}
|
|
@item @code{CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER}
|
|
@item @code{CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER}
|
|
@item @code{CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER}
|
|
@item @code{CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER}
|
|
|
|
@end itemize
|
|
|
|
Note that network device drivers are not configured in the
|
|
Device Driver Table.
|
|
|
|
@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.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the Device Driver Table is assumed to be
|
|
named @code{Device_drivers} and defined in C. If the application is providing
|
|
its own Device Driver Table, then the macro
|
|
@code{CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE} must be defined to indicate
|
|
this and prevent @code{confdefs.h} from generating the table.
|
|
|
|
@item number_of_initial_extensions
|
|
is the number of initial user extensions. There should be
|
|
the same number of entries as in the User_extension_table. If this field
|
|
is zero, then the User_driver_address_table entry should be NULL.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_NUMBER_OF_INITIAL_EXTENSIONS}
|
|
which is set automatically by @code{confdefs.h} based on the size
|
|
of the User Extensions Table.
|
|
|
|
@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.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the User Extensions Table is named
|
|
@code{Configuration_Initial_Extensions} and defined in
|
|
confdefs.h. It is initialized based on the following
|
|
macros:
|
|
|
|
@itemize @bullet
|
|
|
|
@item @code{CONFIGURE_INITIAL_EXTENSIONS}
|
|
@item @code{STACK_CHECKER_EXTENSION}
|
|
|
|
@end itemize
|
|
|
|
The application may configure one or more initial user extension
|
|
sets by setting the @code{CONFIGURE_INITIAL_EXTENSIONS} macro. By
|
|
defining the @code{STACK_CHECKER_EXTENSION} macro, the task stack bounds
|
|
checking user extension set is automatically included in the
|
|
application.
|
|
|
|
@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.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the Multiprocessor Configuration Table
|
|
is automatically generated when the @code{CONFIGURE_MP_APPLICATION}
|
|
is defined. If @code{CONFIGURE_MP_APPLICATION} is not defined, the this
|
|
entry is set to NULL. The generated table has the name
|
|
@code{Multiprocessing_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.] This table is built automatically and this
|
|
entry filled in, if using the @code{confdefs.h} application
|
|
configuration mechanism. The generated table has the name
|
|
@code{Configuration_RTEMS_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. This table is built automatically
|
|
and this entry filled in, if using the @code{confdefs.h} application
|
|
configuration mechanism. The @code{confdefs.h} application
|
|
mechanism will fill this field in with the address of the
|
|
@code{Configuration_POSIX_API} table of POSIX API is configured
|
|
and NULL if the POSIX API is not configured.
|
|
|
|
@end table
|
|
|
|
@section RTEMS API Configuration Table
|
|
|
|
@cindex 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
|
|
@findex rtems_api_configuration_table
|
|
@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.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_TASKS}.
|
|
If not defined by the application, then the @code{CONFIGURE_MAXIMUM_TASKS}
|
|
macro defaults to 10.
|
|
|
|
@item maximum_timers
|
|
is the maximum number of timers
|
|
that can be concurrently active in the system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_TIMERS}.
|
|
If not defined by the application, then the @code{CONFIGURE_MAXIMUM_TIMERS}
|
|
macro defaults to 0.
|
|
|
|
@item maximum_semaphores
|
|
is the maximum number of
|
|
semaphores that can be concurrently active in the system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_SEMAPHORES}.
|
|
If not defined by the application, then the @code{CONFIGURE_MAXIMUM_SEMAPHORES}
|
|
macro defaults to 0.
|
|
|
|
@item maximum_message_queues
|
|
is the maximum number of
|
|
message queues that can be concurrently active in the system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES}.
|
|
If not defined by the application, then the
|
|
@code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES} macro defaults to 0.
|
|
|
|
@item maximum_partitions
|
|
is the maximum number of
|
|
partitions that can be concurrently active in the system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_PARTITIONS}.
|
|
If not defined by the application, then the @code{CONFIGURE_MAXIMUM_PARTITIONS}
|
|
macro defaults to 0.
|
|
|
|
@item maximum_regions
|
|
is the maximum number of regions
|
|
that can be concurrently active in the system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_REGIONS}.
|
|
If not defined by the application, then the @code{CONFIGURE_MAXIMUM_REGIONS}
|
|
macro defaults to 0.
|
|
|
|
@item maximum_ports
|
|
is the maximum number of ports into
|
|
dual-port memory areas that can be concurrently active in the
|
|
system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_PORTS}.
|
|
If not defined by the application, then the @code{CONFIGURE_MAXIMUM_PORTS}
|
|
macro defaults to 0.
|
|
|
|
@item number_of_initialization_tasks
|
|
is the number of initialization tasks configured. At least one
|
|
RTEMS initialization task or POSIX initializatin must be configured
|
|
in order for the user's application to begin executing.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the user must define the
|
|
@code{CONFIGURE_RTEMS_INIT_TASKS_TABLE} to indicate that there
|
|
is one or more RTEMS initialization task. If the application
|
|
only has one RTEMS initialization task, then the automatically
|
|
generated Initialization Task Table will be sufficient. The following
|
|
macros correspond to the single initialization task:
|
|
|
|
@itemize @bullet
|
|
|
|
@item @code{CONFIGURE_INIT_TASK_NAME} - is the name of the task.
|
|
If this macro is not defined by the application, then this defaults
|
|
to the task name of @code{"UI1 "} for User Initialization Task 1.
|
|
|
|
@item @code{CONFIGURE_INIT_TASK_STACK_SIZE} - is the stack size
|
|
of the single initialization task. If this macro is not defined
|
|
by the application, then this defaults to @code{RTEMS_MINIMUM_STACK_SIZE}.
|
|
|
|
@item @code{CONFIGURE_INIT_TASK_PRIORITY} - is the initial priority
|
|
of the single initialization task. If this macro is not defined
|
|
by the application, then this defaults to 1.
|
|
|
|
@item @code{CONFIGURE_INIT_TASK_ATTRIBUTES} - is the attributes
|
|
of the single initialization task. If this macro is not defined
|
|
by the application, then this defaults to @code{RTEMS_DEFAULT_ATTRIBUTES}.
|
|
|
|
@item @code{CONFIGURE_INIT_TASK_ENTRY_POINT} - is the entry point
|
|
of the single initialization task. If this macro is not defined
|
|
by the application, then this defaults to the C language routine
|
|
@code{Init}.
|
|
|
|
@item @code{CONFIGURE_INIT_TASK_INITIAL_MODES} - is the initial execution
|
|
modes of the single initialization task. If this macro is not defined
|
|
by the application, then this defaults to @code{RTEMS_NO_PREEMPT}.
|
|
|
|
@item @code{CONFIGURE_INIT_TASK_ARGUMENTS} - is the argument passed to the
|
|
of the single initialization task. If this macro is not defined
|
|
by the application, then this defaults to 0.
|
|
|
|
|
|
@end itemize
|
|
|
|
|
|
has the option to have
|
|
value for this field corresponds
|
|
to the setting of the macro @code{}.
|
|
|
|
@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.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA}.
|
|
|
|
@end table
|
|
|
|
@section POSIX API Configuration Table
|
|
|
|
@cindex 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
|
|
@findex posix_initialization_threads_table
|
|
@findex posix_api_configuration_table
|
|
@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_timers;
|
|
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_Timers : 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.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_THREADS}.
|
|
If not defined by the application, then the
|
|
@code{CONFIGURE_MAXIMUM_POSIX_THREADS} macro defaults to 10.
|
|
|
|
@item maximum_mutexes
|
|
is the maximum number of mutexes that can be concurrently
|
|
active in the system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_MUTEXES}.
|
|
If not defined by the application, then the
|
|
@code{CONFIGURE_MAXIMUM_POSIX_MUTEXES} macro defaults to 0.
|
|
|
|
@item maximum_condition_variables
|
|
is the maximum number of condition variables that can be
|
|
concurrently active in the system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES}.
|
|
If not defined by the application, then the
|
|
@code{CONFIGURE_MAXIMUM_POSIX_CONDITION_VARIABLES} macro defaults to 0.
|
|
|
|
@item maximum_keys
|
|
is the maximum number of keys that can be concurrently active in the system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_KEYS}.
|
|
If not defined by the application, then the
|
|
@code{CONFIGURE_MAXIMUM_POSIX_KEYS} macro defaults to 0.
|
|
|
|
@item maximum_timers
|
|
is the maximum number of POSIX timers that can be concurrently active
|
|
in the system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_TIMERS}.
|
|
If not defined by the application, then the
|
|
@code{CONFIGURE_MAXIMUM_POSIX_TIMERS} macro defaults to 0.
|
|
|
|
@item maximum_queued_signals
|
|
is the maximum number of queued signals that can be concurrently
|
|
pending in the system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS}.
|
|
If not defined by the application, then the
|
|
@code{CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS} macro defaults to 0.
|
|
|
|
@item number_of_initialization_threads
|
|
is the number of initialization threads configured. At least one
|
|
initialization threads must be configured.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the user must define the
|
|
@code{CONFIGURE_POSIX_INIT_THREAD_TABLE} to indicate that there
|
|
is one or more POSIX initialization thread. If the application
|
|
only has one POSIX initialization thread, then the automatically
|
|
generated POSIX Initialization Thread Table will be sufficient. The following
|
|
macros correspond to the single initialization task:
|
|
|
|
@itemize @bullet
|
|
|
|
@item @code{CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT} - is the entry
|
|
point of the thread. If this macro is not defined by the application,
|
|
then this defaults to the C routine @code{POSIX_Init}.
|
|
|
|
@item @code{CONFIGURE_POSIX_INIT_TASK_STACK_SIZE} - is the stack size
|
|
of the single initialization thread. If this macro is not defined
|
|
by the application, then this defaults to
|
|
@code{(RTEMS_MINIMUM_STACK_SIZE * 2)}.
|
|
|
|
@end itemize
|
|
|
|
@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
|
|
@code{posix_initialization_threads_table} @value{STRUCTURE}.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the address of the @code{POSIX_Initialization_threads} structure.
|
|
|
|
@end table
|
|
|
|
@section CPU Dependent Information Table
|
|
|
|
@cindex 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.
|
|
|
|
The @code{confdefs.h} mechanism does not support generating this
|
|
table. It is normally filled in by the Board Support Package.
|
|
|
|
@section Initialization Task Table
|
|
|
|
@cindex Initialization Tasks 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
|
|
@code{@value{DIRPREFIX}task_create} and
|
|
@code{@value{DIRPREFIX}task_start} directives. The number of entries is
|
|
found in the @code{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
|
|
@findex rtems_initialization_tasks_table
|
|
@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
|
|
|
|
@cindex Device Driver 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. This table is copied to the Device Drive
|
|
Table during the IO Manager's initialization giving the entries in this
|
|
table the lower major numbers. The format of each entry in the Device
|
|
Driver Table is defined in the following @value{LANGUAGE}
|
|
@value{STRUCTURE}:
|
|
|
|
@ifset is-C
|
|
@findex rtems_driver_address_table
|
|
@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
|
|
|
|
@cindex 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_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_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
|
|
|
|
@cindex 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
|
|
@code{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.
|
|
|
|
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the macro @code{CONFIGURE_MP_APPLICATION} must
|
|
be defined to automatically generate the Multiprocessor Configuration Table.
|
|
If @code{CONFIGURE_MP_APPLICATION}, is not defined, then a NULL pointer
|
|
is configured as the address of this table.
|
|
|
|
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.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MP_NODE_NUMBER}.
|
|
If not defined by the application, then the @code{CONFIGURE_MP_NODE_NUMBER}
|
|
macro defaults to the value of the @code{NODE_NUMBER} macro which is
|
|
set on the compiler command line by the RTEMS Multiprocessing Test Suites.
|
|
|
|
|
|
@item maximum_nodes
|
|
is the number of processor nodes in the system.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MP_MAXIMUM_NODES}.
|
|
If not defined by the application, then the @code{CONFIGURE_MP_MAXIMUM_NODES}
|
|
macro defaults to the value 2.
|
|
|
|
@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.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS}.
|
|
If not defined by the application, then the
|
|
@code{CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS} macro defaults to the value 32.
|
|
|
|
|
|
@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.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MP_MAXIMUM_PROXIES}.
|
|
If not defined by the application, then the @code{CONFIGURE_MP_MAXIMUM_PROXIES}
|
|
macro defaults to the value 32.
|
|
|
|
|
|
@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.
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the value for this field corresponds
|
|
to the setting of the macro @code{CONFIGURE_MP_MPCI_TABLE_POINTER}.
|
|
If not defined by the application, then the
|
|
@code{CONFIGURE_MP_MPCI_TABLE_POINTER} macro defaults to the
|
|
address of the table named @code{MPCI_table}.
|
|
|
|
|
|
@end table
|
|
|
|
@section Multiprocessor Communications Interface Table
|
|
|
|
@cindex Multiprocessor Communications Interface Table
|
|
|
|
This table defines the set of callouts that must be provided by
|
|
an Multiprocessor Communications Interface implementation.
|
|
|
|
When using the @code{confdefs.h} mechanism for configuring
|
|
an RTEMS application, the name of this table is assumed
|
|
to be @code{MPCI_table} unless the application sets
|
|
the @code{CONFIGURE_MP_MPCI_TABLE_POINTER} when configuring a
|
|
multiprocessing system.
|
|
|
|
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, the RTEMS Classic API was specifically designed to allow
|
|
unused managers to be forcibly 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 Classic API 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 is designed to be built and installed as a library
|
|
that is linked into the application. As such, much of
|
|
RTEMS is implemented in such a way that there is a single
|
|
entry point per source file. This avoids having the
|
|
linker being forced to pull large object files in their
|
|
entirety into an application when the application references
|
|
a single symbol.
|
|
|
|
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 private 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 @code{confdefs.h} mechanism calcalutes the size
|
|
of the RTEMS RAM Workspace automatically. It assumes that
|
|
all tasks are floating point and that all will be allocated
|
|
the miminum stack space. This calculation also automatically
|
|
includes the memory that will be allocated for internal use
|
|
by RTEMS. The following macros may be set
|
|
by the application to make the calculation
|
|
of memory required more accurate:
|
|
|
|
@itemize @bullet
|
|
|
|
@item @code{CONFIGURE_MEMORY_OVERHEAD}
|
|
@item @code{CONFIGURE_EXTRA_TASK_STACKS}
|
|
|
|
@end itemize
|
|
|
|
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 @b{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 @code{work_space_size} parameter of the
|
|
Configuration Table.
|
|
|
|
The allocation of objects can operate in two modes. The default mode
|
|
has an object number ceiling. No more than the specified number of
|
|
objects can be allocated from the RTEMS RAM Workspace. The number of objects
|
|
specified in the particular API Configuration table fields are
|
|
allocated at initialisation. The second mode allows the number of
|
|
objects to grow to use the available free memory in the RTEMS RAM Workspace.
|
|
|
|
The auto-extending mode can be enabled individually for each object
|
|
type by using the macro @code{rtems_resource_unlimited}. This takes a value
|
|
as a parameter, and is used to set the object maximum number field in
|
|
an API Configuration table. The value is an allocation unit size. When
|
|
RTEMS is required to grow the object table it is grown by this
|
|
size. The kernel will return the object memory back to the RTEMS RAM Workspace
|
|
when an object is destroyed. The kernel will only return an allocated
|
|
block of objects to the RTEMS RAM Workspace if at least half the allocation
|
|
size of free objects remain allocated. RTEMS always keeps one
|
|
allocation block of objects allocated. Here is an example of using
|
|
@code{rtems_resource_unlimited}:
|
|
|
|
@example
|
|
#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
|
|
@end example
|
|
|
|
The user is cautioned that future versions of RTEMS may not have the
|
|
same memory requirements per object. Although the value calculated is
|
|
suficient 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.
|