summaryrefslogtreecommitdiffstats
path: root/c_user
diff options
context:
space:
mode:
authorAmar Takhar <amar@rtems.org>2016-01-17 19:13:37 -0500
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:23 -0400
commit1a1be7f4569b59f643d873b280cf9051d6f051bf (patch)
tree1b3c9bf47752217d7a2001a2fc08db233b009aba /c_user
parent4783b0d0e4f5a94c5a6103892cf3abf86a0a9eb5 (diff)
downloadrtems-docs-1a1be7f4569b59f643d873b280cf9051d6f051bf.tar.bz2
Fix markup.
Diffstat (limited to 'c_user')
-rw-r--r--c_user/c_user.rst295
1 files changed, 173 insertions, 122 deletions
diff --git a/c_user/c_user.rst b/c_user/c_user.rst
index 6fc47bc..fe2c2ad 100644
--- a/c_user/c_user.rst
+++ b/c_user/c_user.rst
@@ -588,7 +588,7 @@ of the RTEMS executive is application dependent.
RTEMS requires RAM to manage each instance of an RTEMS object
that is created. Thus the more RTEMS objects an application
-needs, the more memory that must be reserved. See:ref:`Configuring a System <Configuring-a-System>` for more details.
+needs, the more memory that must be reserved. See `Configuring a System`_.
RTEMS utilizes memory for both code and data space.
Although RTEMS’ data space must be in RAM, its code space can be
@@ -786,7 +786,7 @@ Chapter 29:
when manipulating POSIX ``struct timespec`` instances.
Chapter 30:
- Constant Bandwidth Server Scheduler API::
+ Constant Bandwidth Server Scheduler API.
Chapter 31:
Directive Status Codes: provides a definition of each of the
@@ -1100,7 +1100,9 @@ task could request to delay until midnight on New Year’s Eve
before lowering the ball at Times Square.
The data type ``rtems_time_of_day`` is used to specify
calendar time in RTEMS services.
-See :ref:`Time and Date Data Structures <Clock-Manager-Time-and-Date-Data-Structures>`... index:: rtems_time_of_day
+See `Time and Date Data Structures`_
+
+... index:: rtems_time_of_day
Obviously, the directives which use intervals or wall
time cannot operate without some external mechanism which
@@ -1163,85 +1165,103 @@ The following is a complete list of the RTEMS primitive
data types in alphabetical order:
- .. index:: rtems_address
+
``rtems_address`` is the data type used to manage
addresses. It is equivalent to
a "void \*" pointer.
- .. index:: rtems_asr
+
``rtems_asr`` is the return type for an
RTEMS ASR.
- .. index:: rtems_asr_entry
+
``rtems_asr_entry`` is the address of
the entry point to an RTEMS ASR.
- .. index:: rtems_attribute
+
``rtems_attribute`` is the data type used
to manage the attributes for RTEMS objects. It is primarily
used as an argument to object create routines to specify
characteristics of the new object.
- .. index:: rtems_boolean
+
``rtems_boolean`` may only take on the
values of ``TRUE`` and ``FALSE``.
This type is deprecated. Use "bool" instead.
- .. index:: rtems_context
+
``rtems_context`` is the CPU dependent
data structure used to manage the integer and system
register portion of each task’s context.
- .. index:: rtems_context_fp
+
``rtems_context_fp`` is the CPU dependent
data structure used to manage the floating point portion of
each task’s context.
- .. index:: rtems_device_driver
+
``rtems_device_driver`` is the
return type for a RTEMS device driver routine.
- .. index:: rtems_device_driver_entry
+
``rtems_device_driver_entry`` is the
entry point to a RTEMS device driver routine.
- .. index:: rtems_device_major_number
+
``rtems_device_major_number`` is the
data type used to manage device major numbers.
- .. index:: rtems_device_minor_number
+
``rtems_device_minor_number`` is the
data type used to manage device minor numbers.
- .. index:: rtems_double
+
``rtems_double`` is the RTEMS data
type that corresponds to double precision floating point
on the target hardware.
This type is deprecated. Use "double" instead.
- .. index:: rtems_event_set
+
``rtems_event_set`` is the data
type used to manage and manipulate RTEMS event sets
with the Event Manager.
- .. index:: rtems_extension
+
``rtems_extension`` is the return type
for RTEMS user extension routines.
- .. index:: rtems_fatal_extension
+
``rtems_fatal_extension`` is the
entry point for a fatal error user extension handler routine.
- .. index:: rtems_id
+
``rtems_id`` is the data type used
to manage and manipulate RTEMS object IDs.
- .. index:: rtems_interrupt_frame
+
``rtems_interrupt_frame`` is the
data structure that defines the format of the interrupt
stack frame as it appears to a user ISR. This data
structure may not be defined on all ports.
- .. index:: rtems_interrupt_level
+
``rtems_interrupt_level`` is the
data structure used with the ``rtems_interrupt_disable``,``rtems_interrupt_enable``, and``rtems_interrupt_flash`` routines. This
data type is CPU dependent and usually corresponds to
@@ -1249,21 +1269,25 @@ data types in alphabetical order:
the interrupt mask level.
- .. index:: rtems_interval
+
``rtems_interval`` is the data
type used to manage and manipulate time intervals.
Intervals are non-negative integers used to measure
the length of time in clock ticks.
- .. index:: rtems_isr
+
``rtems_isr`` is the return type
of a function implementing an RTEMS ISR.
- .. index:: rtems_isr_entry
+
``rtems_isr_entry`` is the address of
the entry point to an RTEMS ISR. It is equivalent to the
entry point of the function implementing the ISR.
- .. index:: rtems_mp_packet_classes
+
``rtems_mp_packet_classes`` is the
enumerated type which specifies the categories of
multiprocessing messages. For example, one of the
@@ -1271,39 +1295,48 @@ data types in alphabetical order:
the Task Manager.
- .. index:: rtems_mode
+
``rtems_mode`` is the data type
used to manage and dynamically manipulate the execution
mode of an RTEMS task.
- .. index:: rtems_mpci_entry
+
``rtems_mpci_entry`` is the return type
of an RTEMS MPCI routine.
- .. index:: rtems_mpci_get_packet_entry
+
``rtems_mpci_get_packet_entry`` is the address of
the entry point to the get packet routine for an MPCI implementation.
- .. index:: rtems_mpci_initialization_entry
+
``rtems_mpci_initialization_entry`` is the address of
the entry point to the initialization routine for an MPCI implementation.
- .. index:: rtems_mpci_receive_packet_entry
+
``rtems_mpci_receive_packet_entry`` is the address of
the entry point to the receive packet routine for an MPCI implementation.
- .. index:: rtems_mpci_return_packet_entry
+
``rtems_mpci_return_packet_entry`` is the address of
the entry point to the return packet routine for an MPCI implementation.
- .. index:: rtems_mpci_send_packet_entry
+
``rtems_mpci_send_packet_entry`` is the address of
the entry point to the send packet routine for an MPCI implementation.
- .. index:: rtems_mpci_table
+
``rtems_mpci_table`` is the data structure
containing the configuration information for an MPCI.
- .. index:: rtems_name
+
``rtems_name`` is the data type used to
contain the name of a Classic API object. It is an unsigned
thirty-two bit integer which can be treated as a numeric
@@ -1311,6 +1344,7 @@ data types in alphabetical order:
contain four ASCII characters.
- .. index:: rtems_option
+
``rtems_option`` is the data type
used to specify which behavioral options the caller desires.
It is commonly used with potentially blocking directives to specify
@@ -1318,53 +1352,63 @@ data types in alphabetical order:
indicating that the resource was not available.
- .. index:: rtems_packet_prefix
+
``rtems_packet_prefix`` is the data structure
that defines the first bytes in every packet sent between nodes
in an RTEMS multiprocessor system. It contains routing information
that is expected to be used by the MPCI layer.
- .. index:: rtems_signal_set
+
``rtems_signal_set`` is the data
type used to manage and manipulate RTEMS signal sets
with the Signal Manager.
- .. index:: int8_t
+
``int8_t`` is the C99 data type that corresponds to signed eight
bit integers. This data type is defined by RTEMS in a manner that
ensures it is portable across different target processors.
- .. index:: int16_t
+
``int16_t`` is the C99 data type that corresponds to signed
sixteen bit integers. This data type is defined by RTEMS in a manner
that ensures it is portable across different target processors.
- .. index:: int32_t
+
``int32_t`` is the C99 data type that corresponds to signed
thirty-two bit integers. This data type is defined by RTEMS in a manner
that ensures it is portable across different target processors.
- .. index:: int64_t
+
``int64_t`` is the C99 data type that corresponds to signed
sixty-four bit integers. This data type is defined by RTEMS in a manner
that ensures it is portable across different target processors.
- .. index:: rtems_single
+
``rtems_single`` is the RTEMS data
type that corresponds to single precision floating point
on the target hardware.
This type is deprecated. Use "float" instead.
- .. index:: rtems_status_codes
+
``rtems_status_codes`` is the return type for most
RTEMS services. This is an enumerated type of approximately twenty-five
values. In general, when a service returns a particular status code, it
indicates that a very specific error condition has occurred.
- .. index:: rtems_task
+
``rtems_task`` is the return type for an
RTEMS Task.
- .. index:: rtems_task_argument
+
``rtems_task_argument`` is the data
type for the argument passed to each RTEMS task. In RTEMS 4.7
and older, this is an unsigned thirty-two bit integer. In
@@ -1373,84 +1417,103 @@ data types in alphabetical order:
pointer on the target architecture.
- .. index:: rtems_task_begin_extension
+
``rtems_task_begin_extension`` is the
entry point for a task beginning execution user extension handler routine.
- .. index:: rtems_task_create_extension
+
``rtems_task_create_extension`` is the
entry point for a task creation execution user extension handler routine.
- .. index:: rtems_task_delete_extension
+
``rtems_task_delete_extension`` is the
entry point for a task deletion user extension handler routine.
- .. index:: rtems_task_entry
+
``rtems_task_entry`` is the address of
the entry point to an RTEMS ASR. It is equivalent to the
entry point of the function implementing the ASR.
- .. index:: rtems_task_exitted_extension
+
``rtems_task_exitted_extension`` is the
entry point for a task exitted user extension handler routine.
- .. index:: rtems_task_priority
+
``rtems_task_priority`` is the data type
used to manage and manipulate task priorities.
- .. index:: rtems_task_restart_extension
+
``rtems_task_restart_extension`` is the
entry point for a task restart user extension handler routine.
- .. index:: rtems_task_start_extension
+
``rtems_task_start_extension`` is the
entry point for a task start user extension handler routine.
- .. index:: rtems_task_switch_extension
+
``rtems_task_switch_extension`` is the
entry point for a task context switch user extension handler routine.
- .. index:: rtems_tcb
+
``rtems_tcb`` is the data structure associated
with each task in an RTEMS system.
- .. index:: rtems_time_of_day
+
``rtems_time_of_day`` is the data structure
used to manage and manipulate calendar time in RTEMS.
- .. index:: rtems_timer_service_routine
+
``rtems_timer_service_routine`` is the
return type for an RTEMS Timer Service Routine.
- .. index:: rtems_timer_service_routine_entry
+
``rtems_timer_service_routine_entry`` is the address of
the entry point to an RTEMS TSR. It is equivalent to the
entry point of the function implementing the TSR.
- .. index:: rtems_vector_number
+
``rtems_vector_number`` is the data
type used to manage and manipulate interrupt vector numbers.
- .. index:: uint8_t
+
``uint8_t`` is the C99 data type that corresponds to unsigned
eight bit integers. This data type is defined by RTEMS in a manner that
ensures it is portable across different target processors.
- .. index:: uint16_t
+
``uint16_t`` is the C99 data type that corresponds to unsigned
sixteen bit integers. This data type is defined by RTEMS in a manner
that ensures it is portable across different target processors.
- .. index:: uint32_t
+
``uint32_t`` is the C99 data type that corresponds to unsigned
thirty-two bit integers. This data type is defined by RTEMS in a manner
that ensures it is portable across different target processors.
- .. index:: uint64_t
+
``uint64_t`` is the C99 data type that corresponds to unsigned
sixty-four bit integers. This data type is defined by RTEMS in a manner
that ensures it is portable across different target processors.
- .. index:: uintptr_t
+
``uintptr_t`` is the C99 data type that corresponds to the
unsigned integer type that is of sufficient size to represent addresses
as unsigned integers. This data type is defined by RTEMS in a manner
@@ -1524,7 +1587,7 @@ equal priority tasks, tasks will execute in the order they become ready
or FIFO order. Even though there are ways to manipulate and adjust task
priorities, the most important rule to remember is:
-- ```` *Priority based scheduling algorithms will always select the
+- *Priority based scheduling algorithms will always select the
highest priority task that is ready to run when allocating the processor
to a task.*
@@ -2059,7 +2122,7 @@ for any of the following reasons:
created or started successfully.
A discussion of RTEMS actions when a fatal error occurs
-may be found :ref:`Fatal Error Manager Announcing a Fatal Error <Fatal-Error-Manager-Announcing-a-Fatal-Error>`.
+may be found `Announcing a Fatal Error`_.
Operations
==========
@@ -2084,8 +2147,8 @@ environment is set up. This consists of
The ``rtems_initialize_executive`` directive uses a system
initialization linker set to initialize only those parts of the overall RTEMS
-feature set that is necessary for a particular application. See :ref:`Linker
-Sets <Linker-Sets>`. Each RTEMS feature used the application may optionally register an
+feature set that is necessary for a particular application. See `Linker Sets`_.
+Each RTEMS feature used the application may optionally register an
initialization handler. The system initialization API is available via``#included <rtems/sysinit.h>``.
A list of all initialization steps follows. Some steps are optional depending
@@ -2139,7 +2202,7 @@ and the initialization stack may be re-used for interrupt processing.
Many of RTEMS actions during initialization are based upon
the contents of the Configuration Table. For more information
regarding the format and contents of this table, please refer
-to the chapter :ref:`Configuring a System <Configuring-a-System>`.
+to the chapter `Configuring a System`_.
The final action in the initialization sequence is the
initiation of multitasking. When the scheduler and dispatcher
@@ -4366,7 +4429,6 @@ has occurred. Elapsed time is measured in ticks. A tick is
defined to be an integral number of microseconds which is
specified by the user in the Configuration Table.
-.. _Clock-Manager-Time-and-Date-Data-Structures:
Time and Date Data Structures
-----------------------------
@@ -5817,7 +5879,7 @@ This analysis determines whether a task set is schedulable under
worst-case conditions and emphasizes the predictability of the
system’s behavior. It has been proven that:
-- ```` *RMS is an optimal static priority algorithm for
+- *RMS is an optimal static priority algorithm for
scheduling independent, preemptible, periodic tasks
on a single processor.*
@@ -5838,20 +5900,19 @@ which has been ready longest will execute first. RMS’s priority
assignment scheme does not provide one with exact numeric values
for task priorities. For example, consider the following task
set and priority assignments:
-.. code:: c
- +--------------------+---------------------+---------------------+
- | Task | Period | Priority |
- | | (in milliseconds) | |
- +--------------------+---------------------+---------------------+
- | 1 | 100 | Low |
- +--------------------+---------------------+---------------------+
- | 2 | 50 | Medium |
- +--------------------+---------------------+---------------------+
- | 3 | 50 | Medium |
- +--------------------+---------------------+---------------------+
- | 4 | 25 | High |
- +--------------------+---------------------+---------------------+
++--------------------+---------------------+---------------------+
+| Task | Period | Priority |
+| | (in milliseconds) | |
++====================+=====================+=====================+
+| 1 | 100 | Low |
++--------------------+---------------------+---------------------+
+| 2 | 50 | Medium |
++--------------------+---------------------+---------------------+
+| 3 | 50 | Medium |
++--------------------+---------------------+---------------------+
+| 4 | 25 | High |
++--------------------+---------------------+---------------------+
RMS only calls for task 1 to have the lowest
priority, task 4 to have the highest priority, and tasks 2 and 3
@@ -5943,18 +6004,18 @@ This example illustrates the application of the
Processor Utilization Rule to an application with three critical
periodic tasks. The following table details the RMS priority,
period, execution time, and processor utilization for each task:
-.. code:: c
- +------------+----------+--------+-----------+-------------+
- | Task | RMS | Period | Execution | Processor |
- | | Priority | | Time | Utilization |
- +------------+----------+--------+-----------+-------------+
- | 1 | High | 100 | 15 | 0.15 |
- +------------+----------+--------+-----------+-------------+
- | 2 | Medium | 200 | 50 | 0.25 |
- +------------+----------+--------+-----------+-------------+
- | 3 | Low | 300 | 100 | 0.33 |
- +------------+----------+--------+-----------+-------------+
+
++------------+----------+--------+-----------+-------------+
+| Tas k | RMS | Period | Execution | Processor |
+| | Priority | | Time | Utilization |
++============+==========+========+===========+=============+
+| 1 | High | 100 | 15 | 0.15 |
++------------+----------+--------+-----------+-------------+
+| 2 | Medium | 200 | 50 | 0.25 |
++------------+----------+--------+-----------+-------------+
+| 3 | Low | 300 | 100 | 0.33 |
++------------+----------+--------+-----------+-------------+
The total processor utilization for this task set is
0.73 which is below the upper bound of 3 * (2**(1/3) - 1), or
@@ -5997,16 +6058,16 @@ example where task execution time has been increased from 15 to
execution time, and processor utilization for each task:
.. code:: c
- +------------+----------+--------+-----------+-------------+
- | Task | RMS | Period | Execution | Processor |
- | | Priority | | Time | Utilization |
- +------------+----------+--------+-----------+-------------+
- | 1 | High | 100 | 25 | 0.25 |
- +------------+----------+--------+-----------+-------------+
- | 2 | Medium | 200 | 50 | 0.25 |
- +------------+----------+--------+-----------+-------------+
- | 3 | Low | 300 | 100 | 0.33 |
- +------------+----------+--------+-----------+-------------+
++------------+----------+--------+-----------+-------------+
+| Task | RMS | Period | Execution | Processor |
+| | Priority | | Time | Utilization |
++============+==========+========+===========+=============+
+| 1 | High | 100 | 25 | 0.25 |
++------------+----------+--------+-----------+-------------+
+| 2 | Medium | 200 | 50 | 0.25 |
++------------+----------+--------+-----------+-------------+
+| 3 | Low | 300 | 100 | 0.33 |
++------------+----------+--------+-----------+-------------+
The total processor utilization for the modified task
set is 0.83 which is above the upper bound of 3 * (2**(1/3) - 1),
@@ -6022,14 +6083,14 @@ the total execution time, and whether all the deadlines have
been met.
.. code:: c
- +----------+------+------+------+----------------------+---------------+
- | Deadline | Task | Task | Task | Total | All Deadlines |
- | Time | 1 | 2 | 3 | Execution Time | Met? |
- +----------+------+------+------+----------------------+---------------+
- | 100 | 1 | 1 | 1 | 25 + 50 + 100 = 175 | NO |
- +----------+------+------+------+----------------------+---------------+
- | 200 | 2 | 1 | 1 | 50 + 50 + 100 = 200 | YES |
- +----------+------+------+------+----------------------+---------------+
++----------+------+------+------+----------------------+---------------+
+| Deadline | Task | Task | Task | Total | All Deadlines |
+| Time | 1 | 2 | 3 | Execution Time | Met? |
++==========+======+======+======+======================+===============+
+| 100 | 1 | 1 | 1 | 25 + 50 + 100 = 175 | NO |
++----------+------+------+------+----------------------+---------------+
+| 200 | 2 | 1 | 1 | 50 + 50 + 100 = 200 | YES |
++----------+------+------+------+----------------------+---------------+
The key to this analysis is to recognize when each
task will execute. For example at time 100, task 1 must have
@@ -6097,18 +6158,18 @@ For more information on Rate Monotonic Scheduling and
its schedulability analysis, the reader is referred to the
following:
-- ```` *C. L. Liu and J. W. Layland. "Scheduling Algorithms for
+- *C. L. Liu and J. W. Layland. "Scheduling Algorithms for
Multiprogramming in a Hard Real Time Environment." *Journal of
the Association of Computing Machinery*. January 1973. pp. 46-61.*
-- ```` *John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic
+- *John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic
Scheduling Algorithm: Exact Characterization and Average Case
Behavior." *IEEE Real-Time Systems Symposium*. 1989. pp. 166-171.*
-- ```` *Lui Sha and John Goodenough. "Real-Time Scheduling
- Theory and Ada." *IEEE Computer*. April 1990. pp. 53-62.*
+- *Lui Sha and John Goodenough. "Real-Time Scheduling
+ theory and Ada." *IEEE Computer*. April 1990. pp. 53-62.*
-- ```` *Alan Burns. "Scheduling hard real-time systems: a
+- *Alan Burns. "Scheduling hard real-time systems: a
review." *Software Engineering Journal*. May 1991. pp. 116-128.*
Operations
@@ -6540,9 +6601,9 @@ given in ticks or seconds and nanoseconds. The default is seconds and
nanoseconds. If the period’s state is ``RATE_MONOTONIC_INACTIVE``, both
time values will be set to 0. Otherwise, both time values will contain
time information since the last invocation of the``rtems_rate_monotonic_period`` directive. More
-specifically, the (ticks_)since_last_period value contains the elapsed time
+specifically, the ticks_since_last_period value contains the elapsed time
which has occurred since the last invocation of the``rtems_rate_monotonic_period`` directive and the
-(ticks_)executed_since_last_period contains how much processor time the
+ticks_executed_since_last_period contains how much processor time the
owning task has consumed since the invocation of the``rtems_rate_monotonic_period`` directive.
**NOTES:**
@@ -6810,7 +6871,6 @@ cannot complete its interaction with the resource and release
that resource. The high priority task is effectively prevented
from executing by lower priority tasks.
-.. _Semaphore-Manager-Priority-Inheritance:
Priority Inheritance
--------------------
@@ -6888,7 +6948,6 @@ any of the semaphores the task holds. Only when the task
releases ALL of the binary semaphores it holds will its priority
be restored to the normal value.
-.. _Semaphore-Manager-Multiprocessor-Resource-Sharing-Protocol:
Multiprocessor Resource Sharing Protocol
----------------------------------------
@@ -8850,14 +8909,17 @@ direct an event set to a target task. Based upon the state of
the target task, one of the following situations applies:
- Target Task is Blocked Waiting for Events
- - - If the waiting task’s input event condition is
+
+ - If the waiting task’s input event condition is
satisfied, then the task is made ready for execution.
- - - If the waiting task’s input event condition is not
+
+ - If the waiting task’s input event condition is not
satisfied, then the event set is posted but left pending and the
task remains blocked.
- Target Task is Not Waiting for Events
- - - The event set is posted and left pending.
+
+ - The event set is posted and left pending.
Receiving an Event Set
----------------------
@@ -11288,7 +11350,6 @@ a specific target processor.
Operations
==========
-.. _Fatal-Error-Manager-Announcing-a-Fatal-Error:
Announcing a Fatal Error
------------------------
@@ -11702,7 +11763,7 @@ responsible for priming the context area, and the task context
switch extension would save and restore the context of the
device.
-For more information on user extensions, refer to the:ref:`User Extensions Manager <User-Extensions-Manager>` chapter.
+For more information on user extensions, refer to `User Extensions Manager`_.
Multiprocessor Communications Interface (MPCI)
==============================================
@@ -11795,7 +11856,6 @@ Multiprocessing Manager chapter.
.. COMMENT: All rights reserved.
-.. _User-Extensions-Manager:
User Extensions Manager
#######################
@@ -12388,7 +12448,6 @@ preempted.
.. COMMENT: Device Driver Table, Init task table, etc.?
-.. _Configuring-a-System:
Configuring a System
####################
@@ -12451,8 +12510,6 @@ task/thread tables is configured.
.. COMMENT: === Sizing the RTEMS Workspace ===
-.. _Configuring-a-System-Sizing-the-RTEMS-Workspace:
-
Sizing the RTEMS Workspace
==========================
@@ -12468,7 +12525,7 @@ Workspace automatically. It assumes that all tasks are floating point and
that all will be allocated the minimum stack space. This calculation
includes the amount of memory that will be allocated for internal use
by RTEMS. The automatic calculation may underestimate the workspace
-size truly needed by the application, in which case one can use the``CONFIGURE_MEMORY_OVERHEAD`` macro to add a value to the estimate. See:ref:`Configuring a System Specify Memory Overhead <Configuring-a-System-Specify-Memory-Overhead>` for more details.
+size truly needed by the application, in which case one can use the``CONFIGURE_MEMORY_OVERHEAD`` macro to add a value to the estimate. See `Specify Memory Overhead`_ for more details.
The memory area for the RTEMS Workspace is determined by the BSP. In case the
RTEMS Workspace is too large for the available memory, then a fatal run-time
@@ -12488,7 +12545,7 @@ way allocates memory for an initial number of objects and increases the
current allocation by a fixed increment when required. Both ways allocate
space from inside the RTEMS Workspace.
-See :ref:`Configuring a System Unlimited Objects <Configuring-a-System-Unlimited-Objects>` for more details about
+See `Unlimited Objects`_ for more details about
the second way, which allows for dynamic allocation of objects and
therefore does not provide determinism. This mode is useful mostly for
when the number of objects cannot be determined ahead of time or when
@@ -12558,7 +12615,9 @@ Format to be followed for making changes in this file
Please refer to all existing formats.
- RANGE:
+
The range depends on the Data Type of the macro.
+
- − If the data type is of type task priority, then its value should
be an integer in the range of 1 to 255.
- − If the data type is an integer, then it can have numbers, characters
@@ -12573,8 +12632,10 @@ Format to be followed for making changes in this file
an integer>=0 or RTEMS_BUILD_NAME( ’U’, ’I’, ’1’, ’ ’ )
- DEFAULT VALUE
+
The default value should be in the following formats-
Please note that the ’.’ (full stop) is necessary.
+
- − In case the value is not defined then:
This is not defined by default.
- − If we know the default value then:
@@ -12673,14 +12734,13 @@ other things, the application implicitly used the following defaults:
.. COMMENT: === Unlimited Objects ===
-.. _Configuring-a-System-Unlimited-Objects:
Unlimited Objects
-----------------
In real-time embedded systems the RAM is normally a limited, critical
resource and dynamic allocation is avoided as much as possible to
-ensure predictable, deterministic execution times. For such cases, see:ref:`Configuring a System Sizing the RTEMS Workspace <Configuring-a-System-Sizing-the-RTEMS-Workspace>` for an overview
+ensure predictable, deterministic execution times. For such cases, see `Sizing the RTEMS Workspace`_ for an overview
of how to tune the size of the workspace. Frequently when users are
porting software to RTEMS the precise resource requirements of the
software is unknown. In these situations users do not need to control
@@ -12749,7 +12809,7 @@ The following object classes can *not* be configured in unlimited mode:
- POSIX Queued Signals
Due to the memory requirements of unlimited objects it is strongly recommended
-to use them only in combination with the unified work areas. See:ref:`Configuring a System Separate or Unified Work Areas <Configuring-a-System-Separate-or-Unified-Work-Areas>` for more information
+to use them only in combination with the unified work areas. See `Separate or Unified Work Areas`_ for more information
on unified work areas.
The following example demonstrates how the two simple configuration defines for
@@ -12909,7 +12969,7 @@ This object class can be configured in unlimited allocation mode.
The calculations for the required memory in the RTEMS Workspace
for tasks assume that each task has a minimum stack size and
has floating point support enabled. The configuration parameter``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify task stack
-requirements *ABOVE* the minimum size required. See:ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
+requirements *ABOVE* the minimum size required. See `Reserve Task/Thread Stack Memory Above Minimum`_
for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
The maximum number of POSIX threads is specified by``CONFIGURE_MAXIMUM_POSIX_THREADS``.
@@ -13322,7 +13382,7 @@ initialization task defined by the Classic API Initialization Tasks Table.
If the stack size specified is greater than the configured minimum,
it must be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``.
-See :ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
+See `Reserve Task/Thread Stack Memory Above Minimum`_
for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
.. COMMENT: === CONFIGURE_INIT_TASK_PRIORITY ===
@@ -13504,7 +13564,7 @@ This calculations for the required memory in the RTEMS Workspace
for threads assume that each thread has a minimum stack size and
has floating point support enabled. The configuration parameter``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify thread stack
requirements *ABOVE* the minimum size required.
-See :ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
+See `Reserve Task/Thread Stack Memory Above Minimum`_
for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
The maximum number of Classic API Tasks is specified by``CONFIGURE_MAXIMUM_TASKS``.
@@ -13923,7 +13983,7 @@ Threads Table.
If the stack size specified is greater than the configured minimum,
it must be accounted for in ``CONFIGURE_EXTRA_TASK_STACKS``.
-See :ref:`Configuring a System Reserve Task/Thread Stack Memory Above Minimum <Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum>`
+See `Reserve Task/Thread Stack Memory Above Minimum`_
for more information about ``CONFIGURE_EXTRA_TASK_STACKS``.
.. COMMENT: === CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE ===
@@ -13964,7 +14024,6 @@ This section defines the general system configuration parameters supported by``<
.. COMMENT: === CONFIGURE_UNIFIED_WORK_AREAS ===
-.. _Configuring-a-System-Separate-or-Unified-Work-Areas:
Separate or Unified Work Areas
------------------------------
@@ -14208,7 +14267,6 @@ from the RTEMS Workspace would be welcomed by the RTEMS Project.
.. COMMENT: === CONFIGURE_EXTRA_TASK_STACKS ===
-.. _Configuring-a-System-Reserve-Task_002fThread-Stack-Memory-Above-Minimum:
Reserve Task/Thread Stack Memory Above Minimum
----------------------------------------------
@@ -14546,7 +14604,6 @@ and providing work-arounds when the memory estimated by``<rtems/confdefs.h>`` is
.. COMMENT: === CONFIGURE_MEMORY_OVERHEAD ===
-.. _Configuring-a-System-Specify-Memory-Overhead:
Specify Memory Overhead
-----------------------
@@ -16261,7 +16318,6 @@ Deterministic Priority Scheduler.
.. COMMENT: === Configuring Clustered Schedulers ===
-.. _Configuring-a-System-Configuring-Clustered-Schedulers:
Configuring Clustered Schedulers
--------------------------------
@@ -16432,7 +16488,6 @@ configuration parameters which apply.
.. COMMENT: === CONFIGURE_SMP_APPLICATION ===
-.. _Configuring-a-System-Enable-SMP-Support-for-Applications:
Enable SMP Support for Applications
-----------------------------------
@@ -17264,6 +17319,7 @@ The PCI Library startup behaviour can be configured in four different
ways depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined:
- .. index:: PCI_LIB_AUTO
+
``PCI_LIB_AUTO`` is used to enable the PCI auto configuration
software. PCI will be automatically probed, PCI buses enumerated, all
devices and bridges will be initialized using Plug & Play software
@@ -17273,6 +17329,7 @@ ways depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined:
bridge driver set up.
- .. index:: PCI_LIB_READ
+
``PCI_LIB_READ`` is used to enable the PCI read configuration
software. The current PCI configuration is read to create the RAM
representation (the PCI device tree) of the PCI devices present. PCI devices
@@ -17281,6 +17338,7 @@ ways depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined:
prior to booting into RTEMS.
- .. index:: PCI_LIB_STATIC
+
``PCI_LIB_STATIC`` is used to enable the PCI static configuration
software. The user provides a PCI tree with information how all PCI devices
are to be configured at compile time by linking in a custom``struct pci_bus pci_hb`` tree. The static PCI library will not probe PCI
@@ -17291,6 +17349,7 @@ ways depending on how ``CONFIGURE_PCI_CONFIG_LIB`` is defined:
dynamic memory allocation.
- .. index:: PCI_LIB_PERIPHERAL
+
``PCI_LIB_PERIPHERAL`` is used to enable the PCI peripheral
configuration. It is similar to ``PCI_LIB_STATIC``, but it will never write
the configuration to the PCI devices since PCI peripherals are not allowed to
@@ -17961,10 +18020,9 @@ available on
- SPARC.
It must be explicitly enabled via the ``--enable-smp`` configure command
-line option. To enable SMP in the application configuration see:ref:`Configuring a System Enable SMP Support for Applications <Configuring-a-System-Enable-SMP-Support-for-Applications>`. The default
+line option. To enable SMP in the application configuration see `Enable SMP Support for Applications`_. The default
scheduler for SMP applications supports up to 32 processors and is a global
-fixed priority scheduler, see also :ref:`Configuring a System Configuring
-Clustered Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`. For example applications see:file:`testsuites/smptests`.
+fixed priority scheduler, see also `Configuring Clustered Schedulers`_. For example applications see:file:`testsuites/smptests`.
*WARNING: The SMP support in RTEMS is work in progress. Before you
start using this RTEMS version for SMP ask on the RTEMS mailing list.*
@@ -18136,23 +18194,20 @@ available
- message queues,
-- semaphores using the :ref:`Semaphore Manager Priority Inheritance <Semaphore-Manager-Priority-Inheritance>`
+- semaphores using the `Priority Inheritance`_
protocol (priority boosting), and
-- semaphores using the :ref:`Semaphore Manager Multiprocessor Resource
- Sharing Protocol <Semaphore-Manager-Multiprocessor-Resource-Sharing-Protocol>` (MrsP).
+- semaphores using the `Multiprocessor Resource Sharing Protocol`_ (MrsP).
The clustered scheduling approach enables separation of functions with
real-time requirements and functions that profit from fairness and high
throughput provided the scheduler instances are fully decoupled and adequate
inter-cluster synchronization primitives are used. This is work in progress.
-For the configuration of clustered schedulers see :ref:`Configuring a System
-Configuring Clustered Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`.
+For the configuration of clustered schedulers see `Configuring Clustered Schedulers`_.
-To set the scheduler of a task see :ref:`Symmetric Multiprocessing Services
-SCHEDULER_IDENT - Get ID of a scheduler <Symmetric-Multiprocessing-Services-SCHEDULER_005fIDENT-_002d-Get-ID-of-a-scheduler>` and :ref:`Symmetric Multiprocessing
-Services TASK_SET_SCHEDULER - Set scheduler of a task <Symmetric-Multiprocessing-Services-TASK_005fSET_005fSCHEDULER-_002d-Set-scheduler-of-a-task>`.
+To set the scheduler of a task see `SCHEDULER_IDENT - Get ID of a scheduler`_
+and `TASK_SET_SCHEDULER - Set scheduler of a task`_.
Task Priority Queues
--------------------
@@ -18645,7 +18700,6 @@ None.
.. COMMENT: rtems_scheduler_ident
-.. _Symmetric-Multiprocessing-Services-SCHEDULER_005fIDENT-_002d-Get-ID-of-a-scheduler:
SCHEDULER_IDENT - Get ID of a scheduler
---------------------------------------
@@ -18670,8 +18724,7 @@ the processor set of this scheduler is empty
**DESCRIPTION:**
Identifies a scheduler by its name. The scheduler name is determined by the
-scheduler configuration. See :ref:`Configuring a System Configuring Clustered
-Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`.
+scheduler configuration. See `Configuring a System`_.
**NOTES:**
@@ -18740,7 +18793,6 @@ None.
.. COMMENT: rtems_task_set_scheduler
-.. _Symmetric-Multiprocessing-Services-TASK_005fSET_005fSCHEDULER-_002d-Set-scheduler-of-a-task:
TASK_SET_SCHEDULER - Set scheduler of a task
--------------------------------------------
@@ -19192,8 +19244,9 @@ CPU. The window size may vary and must be taken into consideration by the
host driver. The below routines must be used to access I/O space. The address
given to the functions is not the PCI I/O addresses, the caller must have
translated PCI I/O addresses (available in the PCI BARs) into a BSP or host
-driver custom address, see :ref:`PCI Library Access functions <PCI-Library-Access-functions>` for how
+driver custom address, see `Access functions`_ for how
addresses are translated.
+
.. code:: c
/* Read a register over PCI I/O Space \*/
@@ -19230,8 +19283,6 @@ architecture must provide necessary functions in order to implement this.
In order to support non-standard big-endian PCI bus the above pci_* functions
is required, pci_ld_le16 != ld_le16 on big endian PCI buses.
-.. _PCI-Library-Access-functions:
-
Access functions
~~~~~~~~~~~~~~~~
@@ -19296,7 +19347,7 @@ The PCI Library relies on the BSP for implementing shared interrupt handling
through the BSP_PCI_shared_interrupt_* functions/macros, they must be defined
when including bsp.h.
-PCI device drivers may use the pci_interrupt_ routines in order to call the
+PCI device drivers may use the pci_interrupt_* routines in order to call the
BSP specific functions in a platform independent way. The PCI interrupt
interface has been made similar to the RTEMS IRQ extension so that a BSP can
use the standard RTEMS interrupt functions directly.
@@ -19346,7 +19397,7 @@ routine.
Recursive routines make calculating peak stack usage difficult, if not
impossible. Each call to the recursive routine consumes *n* bytes
-of stack space. If the routine recursives 1000 times, then``1000 * *n*`` bytes of stack space are required.
+of stack space. If the routine recursives 1000 times, then ``1000 * *n*`` bytes of stack space are required.
Execution
---------
@@ -19568,21 +19619,24 @@ This routine prints a table with the following information per task:
- percentage of time consumed by this task
The following is an example of the report generated:
-.. code:: c
- -------------------------------------------------------------------------------
- CPU USAGE BY THREAD
- ------------+----------------------------------------+---------------+---------
- ID | NAME | SECONDS | PERCENT
- ------------+----------------------------------------+---------------+---------
- 0x04010001 | IDLE | 0 | 0.000
- 0x08010002 | TA1 | 1203 | 0.748
- 0x08010003 | TA2 | 203 | 0.126
- 0x08010004 | TA3 | 202 | 0.126
- ------------+----------------------------------------+---------------+---------
- TICKS SINCE LAST SYSTEM RESET: 1600
- TOTAL UNITS: 1608
- -------------------------------------------------------------------------------
+
++------------------------------------------------------------------------------+
+|CPU USAGE BY THREAD |
++-----------+----------------------------------------+-------------------------+
+|ID | NAME | SECONDS | PERCENT |
++-----------+----------------------------------------+---------------+---------+
+|0x04010001 | IDLE | 0 | 0.000 |
++-----------+----------------------------------------+---------------+---------+
+|0x08010002 | TA1 | 1203 | 0.748 |
++-----------+----------------------------------------+---------------+---------+
+|0x08010003 | TA2 | 203 | 0.126 |
++-----------+----------------------------------------+---------------+---------+
+|0x08010004 | TA3 | 202 | 0.126 |
++-----------+----------------------------------------+---------------+---------+
+|TICKS SINCE LAST SYSTEM RESET: 1600 |
+|TOTAL UNITS: 1608 |
++------------------------------------------------------------------------------+
Notice that the "TOTAL UNITS" is greater than the ticks per reset.
This is an artifact of the way in which RTEMS keeps track of CPU
@@ -22374,8 +22428,6 @@ Returns the enumeration name for the specified status code.
.. COMMENT: All rights reserved.
-.. _Linker-Sets:
-
Linker Sets
###########
@@ -23536,8 +23588,7 @@ Glossary
A :dfn:`scheduler instance` is a scheduling algorithm with a corresponding
context to store its internal state. Each processor in the system is owned by
at most one scheduler instance. The processor to scheduler instance assignment
- is determined at application configuration time. See :ref:`Configuring a System
- Configuring Clustered Schedulers <Configuring-a-System-Configuring-Clustered-Schedulers>`.
+ is determined at application configuration time. See `Configuring a System`_.
:dfn:`segments`
Variable sized memory blocks allocated