rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-15 02:16:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

c-user: Fix index locations.

Browse Source 
Update #3229.
This commit is contained in:
Chris Johns 2017-11-12 14:34:48 +11:00
parent 42d50d760e
commit 6c5640131f
36 changed files with 920 additions and 785 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
c-user/ada_support.rst
View File

@ -6,11 +6,11 @@
.. _ada_support
.. index:: Ada
Ada Support
************
.. index:: Ada
Introduction
============
RTEMS has long had support for the Ada programming language
@ -24,7 +24,7 @@ components to this support:
Ada Programming Language Support
================================
The Ada programming natively supports multi-threaded programming
The Ada programming natively supports multi-threaded programming
with its own tasking and concurrency model. Native Ada multi-threaded
applications should work using GNAT/RTEMS with no changes.
@ -90,10 +90,9 @@ to violating assumptions in the GNAT run-time. Specifically a priority
ceiling mutex should never be used from an ISR and it is difficult to
predict when the Ada compiler or run-time will use a mutex.
RTEMS has two capabilities which can assist in avoiding this problem. The
RTEMS has two capabilities which can assist in avoiding this problem. The
Classic API Timer Manager allows the creation of Timer Service Routines
which execute in the context of a task rather than the clock tick
Interrupt Service Routine. Similarly, there is support for Interrupt Tasks
which is a mechanism to defer the processing of the event from the
hardware interrupt level to a thread.

29
c-user/barrier_manager.rst
View File

@ -4,11 +4,11 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: barrier
Barrier Manager
***************
.. index:: barrier
Introduction
============
@ -162,11 +162,12 @@ sequence, related constants, usage, and status codes.
.. _rtems_barrier_create:
BARRIER_CREATE - Create a barrier
---------------------------------
.. index:: create a barrier
.. index:: rtems_barrier_create
BARRIER_CREATE - Create a barrier
---------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -237,12 +238,13 @@ NOTES:
.. _rtems_barrier_ident:
BARRIER_IDENT - Get ID of a barrier
-----------------------------------
.. index:: get ID of a barrier
.. index:: obtain ID of a barrier
.. index:: rtems_barrier_ident
BARRIER_IDENT - Get ID of a barrier
-----------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -278,11 +280,12 @@ NOTES:
.. _rtems_barrier_delete:
BARRIER_DELETE - Delete a barrier
---------------------------------
.. index:: delete a barrier
.. index:: rtems_barrier_delete
BARRIER_DELETE - Delete a barrier
---------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -320,12 +323,13 @@ NOTES:
.. _rtems_barrier_wait:
BARRIER_OBTAIN - Acquire a barrier
----------------------------------
.. index:: obtain a barrier
.. index:: lock a barrier
.. index:: rtems_barrier_wait
BARRIER_OBTAIN - Acquire a barrier
----------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -394,12 +398,13 @@ NOTES:
.. _rtems_barrier_release:
BARRIER_RELEASE - Release a barrier
-----------------------------------
.. index:: wait at a barrier
.. index:: release a barrier
.. index:: rtems_barrier_release
BARRIER_RELEASE - Release a barrier
-----------------------------------
CALLING SEQUENCE:
.. code-block:: c

2
c-user/board_support_packages.rst
View File

@ -9,10 +9,10 @@ Board Support Packages
.. index:: Board Support Packages
.. index:: BSPs
.. index:: BSP, definition
Introduction
============
.. index:: BSP, definition
A board support package (BSP) is a collection of user-provided facilities which
interface RTEMS and an application with a specific hardware platform. These

118
c-user/chains.rst
View File

@ -172,9 +172,10 @@ Add nodes with the following code:
The chain is initialized and the nodes allocated and appended to the
chain. This is an example of a pool of buffers.
.. index:: chain iterate
Iterating a Chain
-----------------
.. index:: chain iterate
Iterating a chain is a common function. The example shows how to iterate the
buffer pool chain created in the last section to find buffers starting with a
@ -219,11 +220,12 @@ The section details the Chains directives.
.. _rtems_chain_initialize:
Initialize Chain With Nodes
---------------------------
.. index:: chain initialize
.. index:: rtems_chain_initialize
Initialize Chain With Nodes
---------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -256,11 +258,12 @@ NOTES:
.. _rtems_chain_initialize_empty:
Initialize Empty
----------------
.. index:: chain initialize empty
.. index:: rtems_chain_initialize_empty
Initialize Empty
----------------
CALLING SEQUENCE:
.. code-block:: c
@ -284,11 +287,12 @@ NOTES:
.. _rtems_chain_is_null_node:
Is Null Node ?
--------------
.. index:: chain is node null
.. index:: rtems_chain_is_null_node
Is Null Node ?
--------------
CALLING SEQUENCE:
.. code-block:: c
@ -309,11 +313,12 @@ DESCRIPTION:
.. _rtems_chain_head:
Head
----
.. index:: chain get head
.. index:: rtems_chain_head
Head
----
CALLING SEQUENCE:
.. code-block:: c
@ -333,11 +338,12 @@ DESCRIPTION:
.. _rtems_chain_tail:
Tail
----
.. index:: chain get tail
.. index:: rtems_chain_tail
Tail
----
CALLING SEQUENCE:
.. code-block:: c
@ -357,11 +363,12 @@ DESCRIPTION:
.. _rtems_chain_are_nodes_equal:
Are Two Nodes Equal ?
---------------------
.. index:: chare are nodes equal
.. index:: rtems_chain_are_nodes_equal
Are Two Nodes Equal ?
---------------------
CALLING SEQUENCE:
.. code-block:: c
@ -384,11 +391,12 @@ DESCRIPTION:
.. _rtems_chain_is_empty:
Is the Chain Empty
------------------
.. index:: chain is chain empty
.. index:: rtems_chain_is_empty
Is the Chain Empty
------------------
CALLING SEQUENCE:
.. code-block:: c
@ -410,11 +418,12 @@ DESCRIPTION:
.. _rtems_chain_is_first:
Is this the First Node on the Chain ?
-------------------------------------
.. index:: chain is node the first
.. index:: rtems_chain_is_first
Is this the First Node on the Chain ?
-------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -436,11 +445,12 @@ DESCRIPTION:
.. _rtems_chain_is_last:
Is this the Last Node on the Chain ?
------------------------------------
.. index:: chain is node the last
.. index:: rtems_chain_is_last
Is this the Last Node on the Chain ?
------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -462,11 +472,12 @@ DESCRIPTION:
.. _rtems_chain_has_only_one_node:
Does this Chain have only One Node ?
------------------------------------
.. index:: chain only one node
.. index:: rtems_chain_has_only_one_node
Does this Chain have only One Node ?
------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -488,11 +499,12 @@ DESCRIPTION:
.. _rtems_chain_node_count_unprotected:
Returns the node count of the chain (unprotected)
-------------------------------------------------
.. index:: chain only one node
.. index:: rtems_chain_node_count_unprotected
Returns the node count of the chain (unprotected)
-------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -512,11 +524,12 @@ DESCRIPTION:
.. _rtems_chain_is_head:
Is this Node the Chain Head ?
-----------------------------
.. index:: chain is node the head
.. index:: rtems_chain_is_head
Is this Node the Chain Head ?
-----------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -539,11 +552,12 @@ DESCRIPTION:
.. _rtems_chain_is_tail:
Is this Node the Chain Tail ?
-----------------------------
.. index:: chain is node the tail
.. index:: rtems_chain_is_tail
Is this Node the Chain Tail ?
-----------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -566,11 +580,12 @@ DESCRIPTION:
.. _rtems_chain_extract:
Extract a Node
--------------
.. index:: chain extract a node
.. index:: rtems_chain_extract
Extract a Node
--------------
CALLING SEQUENCE:
.. code-block:: c
@ -596,11 +611,12 @@ NOTES:
.. _rtems_chain_extract_unprotected:
Extract a Node (unprotected)
----------------------------
.. index:: chain extract a node unprotected
.. index:: rtems_chain_extract_unprotected
Extract a Node (unprotected)
----------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -623,11 +639,12 @@ NOTES:
.. _rtems_chain_get:
Get the First Node
------------------
.. index:: chain get first node
.. index:: rtems_chain_get
Get the First Node
------------------
CALLING SEQUENCE:
.. code-block:: c
@ -655,11 +672,12 @@ NOTES:
.. _rtems_chain_get_unprotected:
Get the First Node (unprotected)
--------------------------------
.. index:: chain get first node
.. index:: rtems_chain_get_unprotected
Get the First Node (unprotected)
--------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -683,11 +701,12 @@ NOTES:
.. _rtems_chain_insert:
Insert a Node
-------------
.. index:: chain insert a node
.. index:: rtems_chain_insert
Insert a Node
-------------
CALLING SEQUENCE:
.. code-block:: c
@ -715,11 +734,12 @@ NOTES:
.. _rtems_chain_insert_unprotected:
Insert a Node (unprotected)
---------------------------
.. index:: chain insert a node unprotected
.. index:: rtems_chain_insert_unprotected
Insert a Node (unprotected)
---------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -744,11 +764,12 @@ NOTES:
.. _rtems_chain_append:
Append a Node
-------------
.. index:: chain append a node
.. index:: rtems_chain_append
Append a Node
-------------
CALLING SEQUENCE:
.. code-block:: c
@ -775,11 +796,12 @@ NOTES:
.. _rtems_chain_append_unprotected:
Append a Node (unprotected)
---------------------------
.. index:: chain append a node unprotected
.. index:: rtems_chain_append_unprotected
Append a Node (unprotected)
---------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -803,11 +825,12 @@ NOTES:
.. _rtems_chain_prepend:
Prepend a Node
--------------
.. index:: prepend node
.. index:: rtems_chain_prepend
Prepend a Node
--------------
CALLING SEQUENCE:
.. code-block:: c
@ -834,11 +857,12 @@ NOTES:
.. _rtems_chain_prepend_unprotected:
Prepend a Node (unprotected)
----------------------------
.. index:: prepend node unprotected
.. index:: rtems_chain_prepend_unprotected
Prepend a Node (unprotected)
----------------------------
CALLING SEQUENCE:
.. code-block:: c

72
c-user/clock_manager.rst
View File

@ -92,9 +92,10 @@ field in this data structure is the number of seconds since the POSIX epoch of
*January 1, 1970* but will never be prior to the RTEMS epoch of *January 1,
1988*.
.. index:: timeslicing
Clock Tick and Timeslicing
--------------------------
.. index:: timeslicing
Timeslicing is a task scheduling discipline in which tasks of equal priority
are executed for a specific period of time before control of the CPU is passed
@ -111,9 +112,10 @@ running task's time-remaining counter when both timeslicing and preemption are
enabled. If the task's timeslice has expired, then that task will be preempted
if there exists a ready task of equal priority.
.. index:: delays
Delays
------
.. index:: delays
A sleep timer allows a task to delay for a given interval or up until a given
time, and then wake and continue execution. This type of timer is created
@ -122,9 +124,10 @@ directives and, as a result, does not have an RTEMS ID. Once activated, a
sleep timer cannot be explicitly deleted. Each task may activate one and only
one sleep timer at a time.
.. index:: timeouts
Timeouts
--------
.. index:: timeouts
Timeouts are a special type of timer automatically created when the timeout
option is used on the ``rtems_message_queue_receive``, ``rtems_event_receive``,
@ -183,11 +186,11 @@ RTEMS provides multiple directives which can be used by an application to obtain
Calendar time operations will return an error code if invoked before the date
and time have been set.
.. index:: rtems_clock_get
Transition Advice for the Obsolete rtems_clock_get
--------------------------------------------------
.. index:: rtems_clock_get
The method ``rtems_clock_get`` took an untyped pointer with an
options argument to indicate the time information desired. This has
been replaced with a set of typed directives whose name is of the form
@ -211,11 +214,12 @@ related constants, usage, and status codes.
.. _rtems_clock_set:
CLOCK_SET - Set date and time
-----------------------------
.. index:: set the time of day
.. index:: rtems_clock_set
CLOCK_SET - Set date and time
-----------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -260,11 +264,12 @@ NOTES:
.. _rtems_clock_get_tod:
CLOCK_GET_TOD - Get date and time in TOD format
-----------------------------------------------
.. index:: obtain the time of day
.. index:: rtems_clock_get_tod
CLOCK_GET_TOD - Get date and time in TOD format
-----------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -303,11 +308,12 @@ NOTES:
.. _rtems_clock_get_tod_timeval:
CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
-----------------------------------------------------------
.. index:: obtain the time of day
.. index:: rtems_clock_get_tod_timeval
CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
-----------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -346,11 +352,12 @@ NOTES:
.. _rtems_clock_get_seconds_since_epoch:
CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
-------------------------------------------------------
.. index:: obtain seconds since epoch
.. index:: rtems_clock_get_seconds_since_epoch
CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
-------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -389,11 +396,12 @@ NOTES:
.. _rtems_clock_get_ticks_per_second:
CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
-------------------------------------------------
.. index:: obtain seconds since epoch
.. index:: rtems_clock_get_ticks_per_second
CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
-------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -418,12 +426,13 @@ NOTES:
.. _rtems_clock_get_ticks_since_boot:
CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value
------------------------------------------------------------
.. index:: obtain ticks since boot
.. index:: get current ticks counter value
.. index:: rtems_clock_get_ticks_since_boot
CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value
------------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -452,9 +461,10 @@ NOTES:
.. _rtems_clock_tick_later:
.. index:: rtems_clock_tick_later
CLOCK_TICK_LATER - Get tick value in the future
-----------------------------------------------
.. index:: rtems_clock_tick_later
CALLING SEQUENCE:
.. code-block:: c
@ -477,9 +487,10 @@ NOTES:
.. _rtems_clock_tick_later_usec:
.. index:: rtems_clock_tick_later_usec
CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds
--------------------------------------------------------------------
.. index:: rtems_clock_tick_later_usec
CALLING SEQUENCE:
.. code-block:: c
@ -502,9 +513,10 @@ NOTES:
.. _rtems_clock_tick_before:
.. index:: rtems_clock_tick_before
CLOCK_TICK_BEFORE - Is tick value is before a point in time
-----------------------------------------------------------
.. index:: rtems_clock_tick_before
CALLING SEQUENCE:
.. code-block:: c
@ -542,12 +554,13 @@ EXAMPLE:
.. _rtems_clock_get_uptime:
CLOCK_GET_UPTIME - Get the time since boot
------------------------------------------
.. index:: clock get uptime
.. index:: uptime
.. index:: rtems_clock_get_uptime
CLOCK_GET_UPTIME - Get the time since boot
------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -577,12 +590,13 @@ NOTES:
.. _rtems_clock_get_uptime_timeval:
CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
--------------------------------------------------------------------
.. index:: clock get uptime interval
.. index:: uptime
.. index:: rtems_clock_get_uptime_timeval
CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
--------------------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -607,12 +621,13 @@ NOTES:
.. _rtems_clock_get_uptime_seconds:
CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot
-----------------------------------------------------
.. index:: clock get uptime seconds
.. index:: uptime
.. index:: rtems_clock_get_uptime_seconds
CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot
-----------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -633,12 +648,13 @@ NOTES:
.. _rtems_clock_get_uptime_nanoseconds:
CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot
-------------------------------------------------------------
.. index:: clock get nanoseconds uptime
.. index:: uptime
.. index:: rtems_clock_get_uptime_nanoseconds
CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot
-------------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c

338
c-user/configuring_a_system.rst
View File

File diff suppressed because it is too large Load Diff

59
c-user/constant_bandwidth_server.rst
View File

@ -42,12 +42,11 @@ provided by the CBS API are:
Background
==========
.. index:: CBS parameters
.. index:: rtems_cbs_parameters
Constant Bandwidth Server Definitions
-------------------------------------
.. index:: CBS parameters
.. index:: rtems_cbs_parameters
The Constant Bandwidth Server API enables tasks to communicate with the
scheduler and indicate its scheduling parameters. The scheduler has to be set
@ -71,10 +70,10 @@ ordinary tasks that are not attached to any server.
In order to make the server effective to the executing tasks, tasks have to be
attached to the servers. The ``rtems_cbs_server_id`` is a type denoting an id
of a server and ``rtems_id`` a type for id of tasks.
.. index:: CBS periodic tasks
Handling Periodic Tasks
-----------------------
.. index:: CBS periodic tasks
Each task's execution begins with a default background priority (see the
chapter Scheduling Concepts to understand the concept of priorities in
@ -84,10 +83,10 @@ of periodic behavior, or you declare deadline and budget using the CBS API in
which case these properties are constant for all subsequent periods, unless you
change them using the CBS API again. Task now only has to indicate and end of
each period using ``rtems_rate_monotonic_period``.
.. index:: CBS overrun handler
Registering a Callback Function
-------------------------------
.. index:: CBS overrun handler
In case tasks attached to servers are not aware of their execution time and
happen to exceed it, the scheduler does not guarantee execution any more and
@ -113,10 +112,10 @@ The calling convention of the callback function is:
void overrun_handler(
rtems_cbs_server_id server_id
);
.. index:: CBS limitations
Limitations
-----------
.. index:: CBS limitations
When using this scheduler you have to keep in mind several things:
@ -234,11 +233,11 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_cbs_initialize:
.. index:: initialize the CBS library
.. index:: rtems_cbs_initialize
CBS_INITIALIZE - Initialize the CBS library
-------------------------------------------
.. index:: initialize the CBS library
.. index:: rtems_cbs_initialize
CALLING SEQUENCE:
.. code-block:: c
@ -272,11 +271,11 @@ NOTES:
\clearpage
.. _rtems_cbs_cleanup:
.. index:: cleanup the CBS library
.. index:: rtems_cbs_cleanup
CBS_CLEANUP - Cleanup the CBS library
-------------------------------------
.. index:: cleanup the CBS library
.. index:: rtems_cbs_cleanup
CALLING SEQUENCE:
.. code-block:: c
@ -302,11 +301,11 @@ NOTES:
\clearpage
.. _rtems_cbs_create_server:
.. index:: create a new bandwidth server
.. index:: rtems_cbs_create_server
CBS_CREATE_SERVER - Create a new bandwidth server
-------------------------------------------------
.. index:: create a new bandwidth server
.. index:: rtems_cbs_create_server
CALLING SEQUENCE:
.. code-block:: c
@ -350,11 +349,11 @@ NOTES:
\clearpage
.. _rtems_cbs_attach_thread:
.. index:: attach a thread to server
.. index:: rtems_cbs_attach_thread
CBS_ATTACH_THREAD - Attach a thread to server
---------------------------------------------
.. index:: attach a thread to server
.. index:: rtems_cbs_attach_thread
CALLING SEQUENCE:
.. code-block:: c
@ -392,11 +391,11 @@ NOTES:
\clearpage
.. _rtems_cbs_detach_thread:
.. index:: detach a thread from server
.. index:: rtems_cbs_detach_thread
CBS_DETACH_THREAD - Detach a thread from server
-----------------------------------------------
.. index:: detach a thread from server
.. index:: rtems_cbs_detach_thread
CALLING SEQUENCE:
.. code-block:: c
@ -429,11 +428,11 @@ NOTES:
\clearpage
.. _rtems_cbs_destroy_server:
.. index:: destroy a bandwidth server
.. index:: rtems_cbs_destroy_server
CBS_DESTROY_SERVER - Destroy a bandwidth server
-----------------------------------------------
.. index:: destroy a bandwidth server
.. index:: rtems_cbs_destroy_server
CALLING SEQUENCE:
.. code-block:: c
@ -466,11 +465,11 @@ NOTES:
\clearpage
.. _rtems_cbs_get_server_id:
.. index:: get an ID of a server
.. index:: rtems_cbs_get_server_id
CBS_GET_SERVER_ID - Get an ID of a server
-----------------------------------------
.. index:: get an ID of a server
.. index:: rtems_cbs_get_server_id
CALLING SEQUENCE:
.. code-block:: c
@ -497,11 +496,11 @@ DESCRIPTION:
\clearpage
.. _rtems_cbs_get_parameters:
.. index:: get scheduling parameters of a server
.. index:: rtems_cbs_get_parameters
CBS_GET_PARAMETERS - Get scheduling parameters of a server
----------------------------------------------------------
.. index:: get scheduling parameters of a server
.. index:: rtems_cbs_get_parameters
CALLING SEQUENCE:
.. code-block:: c
@ -534,11 +533,11 @@ NOTES:
\clearpage
.. _rtems_cbs_set_parameters:
.. index:: set scheduling parameters
.. index:: rtems_cbs_set_parameters
CBS_SET_PARAMETERS - Set scheduling parameters
----------------------------------------------
.. index:: set scheduling parameters
.. index:: rtems_cbs_set_parameters
CALLING SEQUENCE:
.. code-block:: c
@ -573,11 +572,11 @@ NOTES:
\clearpage
.. _rtems_cbs_get_execution_time:
.. index:: get elapsed execution time
.. index:: rtems_cbs_get_execution_time
CBS_GET_EXECUTION_TIME - Get elapsed execution time
---------------------------------------------------
.. index:: get elapsed execution time
.. index:: rtems_cbs_get_execution_time
CALLING SEQUENCE:
.. code-block:: c
@ -611,11 +610,11 @@ NOTES:
\clearpage
.. _rtems_cbs_get_remaining_budget:
.. index:: get remaining execution time
.. index:: rtems_cbs_get_remaining_budget
CBS_GET_REMAINING_BUDGET - Get remaining execution time
-------------------------------------------------------
.. index:: get remaining execution time
.. index:: rtems_cbs_get_remaining_budget
CALLING SEQUENCE:
.. code-block:: c
@ -649,11 +648,11 @@ NOTES:
\clearpage
.. _rtems_cbs_get_approved_budget:
.. index:: get scheduler approved execution time
.. index:: rtems_cbs_get_approved_budget
CBS_GET_APPROVED_BUDGET - Get scheduler approved execution time
---------------------------------------------------------------
.. index:: get scheduler approved execution time
.. index:: rtems_cbs_get_approved_budget
CALLING SEQUENCE:
.. code-block:: c

4
c-user/cpu_usage_statistics.rst
View File

@ -4,6 +4,8 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: CPU Usage
CPU Usage Statistics
********************
@ -109,6 +111,7 @@ calling sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_cpu_usage_report:
.. index:: rtems_cpu_usage_report
cpu_usage_report - Report CPU Usage Statistics
----------------------------------------------
@ -133,6 +136,7 @@ NOTES:
\clearpage
.. _rtems_cpu_usage_reset:
.. index:: rtems_cpu_usage_reset
cpu_usage_reset - Reset CPU Usage Statistics
--------------------------------------------

6
c-user/directive_status_codes.rst
View File

@ -3,6 +3,8 @@
.. COMMENT: Copyright 2015 embedded brains GmbH
.. COMMENT: All rights reserved.
.. index:: Status Codes
Directive Status Codes
**********************
@ -18,6 +20,8 @@ Directives
The directives are:
.. index:: rtems_status_code
.. list-table::
:class: rtems-table
@ -81,10 +85,10 @@ The directives are:
\clearpage
.. _rtems_status_text:
.. index:: rtems_status_text
STATUS_TEXT - Returns the enumeration name for a status code
------------------------------------------------------------
.. index:: rtems_status_text
CALLING SEQUENCE:
.. code-block:: c

33
c-user/dual_ports_memory_manager.rst
View File

@ -4,12 +4,12 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Dual-Ported Memory Manager
**************************
.. index:: ports
.. index:: dual ported memory
Dual-Ported Memory Manager
**************************
Introduction
============
@ -27,12 +27,13 @@ areas (DPMA). The directives provided by the dual-ported memory manager are:
- rtems_port_internal_to_external_ - Convert internal to external address
Background
==========
.. index:: dual ported memory, definition
.. index:: external addresses, definition
.. index:: internal addresses, definition
Background
==========
A dual-ported memory area (DPMA) is an contiguous block of RAM owned by a
particular processor but which can be accessed by other processors in the
system. The owner accesses the memory using internal addresses, while other
@ -99,11 +100,11 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_port_create:
.. index:: create a port
.. index:: rtems_port_create
PORT_CREATE - Create a port
---------------------------
.. index:: create a port
.. index:: rtems_port_create
CALLING SEQUENCE:
.. code-block:: c
@ -152,13 +153,13 @@ NOTES:
\clearpage
.. _rtems_port_ident:
PORT_IDENT - Get ID of a port
-----------------------------
.. index:: get ID of a port
.. index:: obtain ID of a port
.. index:: rtems_port_ident
PORT_IDENT - Get ID of a port
-----------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -193,11 +194,11 @@ NOTES:
\clearpage
.. _rtems_port_delete:
.. index:: delete a port
.. index:: rtems_port_delete
PORT_DELETE - Delete a port
---------------------------
.. index:: delete a port
.. index:: rtems_port_delete
CALLING SEQUENCE:
.. code-block:: c
@ -230,11 +231,11 @@ NOTES:
\clearpage
.. _rtems_port_external_to_internal:
.. index:: convert external to internal address
.. index:: rtems_port_external_to_internal
PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
----------------------------------------------------------------
.. index:: convert external to internal address
.. index:: rtems_port_external_to_internal
CALLING SEQUENCE:
.. code-block:: c
@ -270,11 +271,11 @@ NOTES:
\clearpage
.. _rtems_port_internal_to_external:
.. index:: convert internal to external address
.. index:: rtems_port_internal_to_external
PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
----------------------------------------------------------------
.. index:: convert internal to external address
.. index:: rtems_port_internal_to_external
CALLING SEQUENCE:
.. code-block:: c

22
c-user/event_manager.rst
View File

@ -4,11 +4,11 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: events
Event Manager
*************
.. index:: events
Introduction
============
@ -21,12 +21,13 @@ and synchronization. The directives provided by the event manager are:
Background
==========
Event Sets
----------
.. index:: event flag, definition
.. index:: event set, definition
.. index:: rtems_event_set
Event Sets
----------
An event flag is used by a task (or ISR) to inform another task of the
occurrence of a significant situation. Thirty-two event flags are associated
with each task. A collection of one or more event flags is referred to as an
@ -59,11 +60,12 @@ condition is satisfied when at least a single requested event is posted. The
``RTEMS_EVENT_ALL`` algorithm states that an event condition is satisfied when
every requested event is posted.
Building an Event Set or Condition
----------------------------------
.. index:: event condition, building
.. index:: event set, building
Building an Event Set or Condition
----------------------------------
An event set or condition is built by a bitwise OR of the desired events. The
set of valid events is ``RTEMS_EVENT_0`` through ``RTEMS_EVENT_31``. If an
event is not explicitly specified in the set or condition, then it is not
@ -181,11 +183,11 @@ related constants, usage, and status codes.
\clearpage
.. _rtems_event_send:
.. index:: send event set to a task
.. index:: rtems_event_send
EVENT_SEND - Send event set to a task
-------------------------------------
.. index:: send event set to a task
.. index:: rtems_event_send
CALLING SEQUENCE:
.. code-block:: c
@ -232,11 +234,11 @@ NOTES:
\clearpage
.. _rtems_event_receive:
.. index:: receive event condition
.. index:: rtems_event_receive
EVENT_RECEIVE - Receive event condition
---------------------------------------
.. index:: receive event condition
.. index:: rtems_event_receive
CALLING SEQUENCE:
.. code-block:: c

39
c-user/fatal_error.rst
View File

@ -5,12 +5,11 @@
.. COMMENT: All rights reserved.
.. _fatal_error_manager:
.. index:: fatal errors
Fatal Error Manager
*******************
.. index:: fatal errors
Introduction
============
@ -34,13 +33,13 @@ provided by the fatal error manager are:
Background
==========
Overview
--------
.. index:: fatal error detection
.. index:: fatal error processing
.. index:: fatal error user extension
Overview
--------
The fatal error manager is called upon detection of an irrecoverable error
condition by either RTEMS or the application software. Fatal errors are also
used in case it is difficult or impossible to return an error condition by
@ -388,10 +387,10 @@ Operations
==========
.. _Terminate:
.. index:: _Terminate
Announcing a Fatal Error
------------------------
.. index:: _Terminate
The :c:func:`_Terminate()` internal error handler is invoked when the
application or the executive itself determines that a fatal error has occurred
@ -443,13 +442,13 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_fatal:
FATAL - Invoke the fatal error
------------------------------
.. index:: announce fatal error
.. index:: fatal error, announce
.. index:: rtems_fatal
FATAL - Invoke the fatal error
------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -473,12 +472,12 @@ NOTE:
\clearpage
.. _rtems_shutdown_executive:
.. index:: shutdown RTEMS
.. index:: rtems_shutdown_executive
SHUTDOWN_EXECUTIVE - Shutdown RTEMS
-----------------------------------
.. index:: shutdown RTEMS
.. index:: rtems_shutdown_executive
CALLING SEQUENCE:
.. code-block:: c
@ -505,11 +504,11 @@ NOTES:
\clearpage
.. _rtems_exception_frame_print:
.. index:: exception frame
.. index:: rtems_exception_frame_print
EXCEPTION_FRAME_PRINT - Prints the exception frame
--------------------------------------------------
.. index:: exception frame
.. index:: rtems_exception_frame_print
CALLING SEQUENCE:
.. code-block:: c
@ -529,11 +528,11 @@ DESCRIPTION:
\clearpage
.. _rtems_fatal_source_text:
.. index:: fatal error
.. index:: rtems_fatal_source_text
FATAL_SOURCE_TEXT - Returns a text for a fatal source
-----------------------------------------------------
.. index:: fatal error
.. index:: rtems_fatal_source_text
CALLING SEQUENCE:
.. code-block:: c
@ -554,11 +553,11 @@ DESCRIPTION:
\clearpage
.. _rtems_internal_error_text:
.. index:: fatal error
.. index:: rtems_internal_error_text
INTERNAL_ERROR_TEXT - Returns a text for an internal error code
---------------------------------------------------------------
.. index:: fatal error
.. index:: rtems_internal_error_text
CALLING SEQUENCE:
.. code-block:: c
@ -579,13 +578,13 @@ DESCRIPTION:
\clearpage
.. _rtems_fatal_error_occurred:
FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated)
------------------------------------------------------------------
.. index:: announce fatal error
.. index:: fatal error, announce
.. index:: rtems_fatal_error_occurred
FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated)
------------------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c

9
c-user/initialization.rst
View File

@ -22,9 +22,10 @@ The Initialization Manager provides only one directive:
Background
==========
.. index:: initialization tasks
Initialization Tasks
--------------------
.. index:: initialization tasks
Initialization task(s) are the mechanism by which RTEMS transfers initial
control to the user's application. Initialization tasks differ from other
@ -305,13 +306,13 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_initialize_executive:
.. index:: initialize RTEMS
.. index:: start multitasking
.. index:: rtems_initialize_executive
INITIALIZE_EXECUTIVE - Initialize RTEMS
---------------------------------------
.. index:: initialize RTEMS
.. index:: start multitasking
.. index:: rtems_initialize_executive
CALLING SEQUENCE:
.. code-block:: c

51
c-user/interrupt_manager.rst
View File

@ -4,6 +4,8 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: interrupts
Interrupt Manager
*****************
@ -44,9 +46,10 @@ from an ISR. The interrupt manager includes the following directive:
Background
==========
.. index:: interrupt processing
Processing an Interrupt
-----------------------
.. index:: interrupt processing
The interrupt manager allows the application to connect a function to a
hardware interrupt vector. When an interrupt occurs, the processor will
@ -111,9 +114,10 @@ another ISR. RTEMS supports efficient interrupt nesting by allowing the nested
ISRs to terminate without performing any dispatch processing. Only when the
outermost ISR terminates will the postponed dispatching occur.
.. index:: interrupt levels
RTEMS Interrupt Levels
----------------------
.. index:: interrupt levels
Many processors support multiple interrupt levels or priorities. The exact
number of interrupt levels is processor dependent. RTEMS internally supports
@ -122,9 +126,10 @@ specific information on the mapping between RTEMS and the target processor's
interrupt levels, refer to the Interrupt Processing chapter of the Applications
Supplement document for a specific target processor.
.. index:: disabling interrupts
Disabling of Interrupts by RTEMS
--------------------------------
.. index:: disabling interrupts
During the execution of directive calls, critical sections of code may be
executed. When these sections are encountered, RTEMS disables all maskable
@ -264,13 +269,13 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_interrupt_catch:
INTERRUPT_CATCH - Establish an ISR
----------------------------------
.. index:: establish an ISR
.. index:: install an ISR
.. index:: rtems_interrupt_catch
INTERRUPT_CATCH - Establish an ISR
----------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -308,11 +313,11 @@ NOTES:
\clearpage
.. _rtems_interrupt_disable:
.. index:: disable interrupts
.. index:: rtems_interrupt_disable
INTERRUPT_DISABLE - Disable Interrupts
--------------------------------------
.. index:: disable interrupts
.. index:: rtems_interrupt_disable
CALLING SEQUENCE:
.. code-block:: c
@ -346,11 +351,11 @@ NOTES:
\clearpage
.. _rtems_interrupt_enable:
.. index:: enable interrupts
.. index:: rtems_interrupt_enable
INTERRUPT_ENABLE - Enable Interrupts
------------------------------------
.. index:: enable interrupts
.. index:: rtems_interrupt_enable
CALLING SEQUENCE:
.. code-block:: c
@ -381,11 +386,11 @@ NOTES:
\clearpage
.. _rtems_interrupt_flash:
.. index:: flash interrupts
.. index:: rtems_interrupt_flash
INTERRUPT_FLASH - Flash Interrupts
----------------------------------
.. index:: flash interrupts
.. index:: rtems_interrupt_flash
CALLING SEQUENCE:
.. code-block:: c
@ -416,11 +421,11 @@ NOTES:
\clearpage
.. _rtems_interrupt_local_disable:
.. index:: disable interrupts
.. index:: rtems_interrupt_local_disable
INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor
-----------------------------------------------------------------
.. index:: disable interrupts
.. index:: rtems_interrupt_local_disable
CALLING SEQUENCE:
.. code-block:: c
@ -453,11 +458,11 @@ NOTES:
\clearpage
.. _rtems_interrupt_local_enable:
.. index:: enable interrupts
.. index:: rtems_interrupt_local_enable
INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor
---------------------------------------------------------------
.. index:: enable interrupts
.. index:: rtems_interrupt_local_enable
CALLING SEQUENCE:
.. code-block:: c
@ -484,10 +489,10 @@ NOTES:
\clearpage
.. _rtems_interrupt_lock_initialize:
.. index:: rtems_interrupt_lock_initialize
INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock
--------------------------------------------------
.. index:: rtems_interrupt_lock_initialize
CALLING SEQUENCE:
.. code-block:: c
@ -512,10 +517,10 @@ NOTES:
\clearpage
.. _rtems_interrupt_lock_acquire:
.. index:: rtems_interrupt_lock_acquire
INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock
--------------------------------------------
.. index:: rtems_interrupt_lock_acquire
CALLING SEQUENCE:
.. code-block:: c
@ -547,10 +552,10 @@ NOTES:
\clearpage
.. _rtems_interrupt_lock_release:
.. index:: rtems_interrupt_lock_release
INTERRUPT_LOCK_RELEASE - Release an ISR Lock
--------------------------------------------
.. index:: rtems_interrupt_lock_release
CALLING SEQUENCE:
.. code-block:: c
@ -579,10 +584,10 @@ NOTES:
\clearpage
.. _rtems_interrupt_lock_acquire_isr:
.. index:: rtems_interrupt_lock_acquire_isr
INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR
---------------------------------------------------------
.. index:: rtems_interrupt_lock_acquire_isr
CALLING SEQUENCE:
.. code-block:: c
@ -617,10 +622,10 @@ NOTES:
\clearpage
.. _rtems_interrupt_lock_release_isr:
.. index:: rtems_interrupt_lock_release_isr
INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR
---------------------------------------------------------
.. index:: rtems_interrupt_lock_release_isr
CALLING SEQUENCE:
.. code-block:: c
@ -649,11 +654,11 @@ NOTES:
\clearpage
.. _rtems_interrupt_is_in_progress:
.. index:: is interrupt in progress
.. index:: rtems_interrupt_is_in_progress
INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress
------------------------------------------------
.. index:: is interrupt in progress
.. index:: rtems_interrupt_is_in_progress
CALLING SEQUENCE:
.. code-block:: c

65
c-user/io_manager.rst
View File

@ -4,12 +4,12 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
I/O Manager
***********
.. index:: device drivers
.. index:: IO Manager
I/O Manager
***********
Introduction
============
@ -40,9 +40,10 @@ drivers. The directives provided by the I/O manager are:
Background
==========
.. index:: Device Driver Table
Device Driver Table
-------------------
.. index:: Device Driver Table
Each application utilizing the RTEMS I/O manager must specify the address of a
Device Driver Table in its Configuration Table. This table contains each device
@ -73,11 +74,12 @@ table.
The :file:`confdefs.h` entry ``CONFIGURE_MAXIMUM_DRIVERS`` configures the
number of driver slots available to the application.
Major and Minor Device Numbers
------------------------------
.. index:: major device number
.. index:: minor device number
Major and Minor Device Numbers
------------------------------
Each call to the I/O manager must provide a device's major and minor numbers as
arguments. The major number is the index of the requested driver's entry
points in the Device Driver Table, and is used to select a specific device
@ -91,9 +93,10 @@ driver.
The data types ``rtems_device_major_number`` and ``rtems_device_minor_number``
are used to manipulate device major and minor numbers, respectively.
.. index:: device names
Device Names
------------
.. index:: device names
The I/O Manager provides facilities to associate a name with a particular
device. Directives are provided to register the name of a device and to look
@ -122,9 +125,10 @@ Although the RTEMS I/O manager provides a framework for device drivers, it
makes no assumptions regarding the construction or operation of a device
driver.
.. index:: runtime driver registration
Runtime Driver Registration
---------------------------
.. index:: runtime driver registration
Board support package and application developers can select wether a device
driver is statically entered into the default device table or registered at
@ -144,9 +148,10 @@ Dynamic registration helps applications where:
- Support for runtime loadable driver modules.
.. index:: device driver interface
Device Driver Interface
-----------------------
.. index:: device driver interface
When an application invokes an I/O manager directive, RTEMS determines which
device driver entry point must be invoked. The information passed by the
@ -226,11 +231,11 @@ related constants, usage, and status codes.
\clearpage
.. _rtems_io_register_driver:
.. index:: register a device driver
.. index:: rtems_io_register_driver
IO_REGISTER_DRIVER - Register a device driver
---------------------------------------------
.. index:: register a device driver
.. index:: rtems_io_register_driver
CALLING SEQUENCE:
.. code-block:: c
@ -284,11 +289,11 @@ NOTES:
\clearpage
.. _rtems_io_unregister_driver:
.. index:: unregister a device driver
.. index:: rtems_io_unregister_driver
IO_UNREGISTER_DRIVER - Unregister a device driver
-------------------------------------------------
.. index:: unregister a device driver
.. index:: rtems_io_unregister_driver
CALLING SEQUENCE:
.. code-block:: c
@ -317,11 +322,11 @@ NOTES:
\clearpage
.. _rtems_io_initialize:
.. index:: initialize a device driver
.. index:: rtems_io_initialize
IO_INITIALIZE - Initialize a device driver
------------------------------------------
.. index:: initialize a device driver
.. index:: rtems_io_initialize
CALLING SEQUENCE:
.. code-block:: c
@ -360,11 +365,11 @@ NOTES:
\clearpage
.. _rtems_io_register_name:
.. index:: register device
.. index:: rtems_io_register_name
IO_REGISTER_NAME - Register a device
------------------------------------
.. index:: register device
.. index:: rtems_io_register_name
CALLING SEQUENCE:
.. code-block:: c
@ -395,11 +400,11 @@ NOTES:
\clearpage
.. _rtems_io_lookup_name:
.. index:: lookup device major and minor number
.. index:: rtems_io_lookup_name
IO_LOOKUP_NAME - Lookup a device
--------------------------------
.. index:: lookup device major and minor number
.. index:: rtems_io_lookup_name
CALLING SEQUENCE:
.. code-block:: c
@ -430,11 +435,11 @@ NOTES:
\clearpage
.. _rtems_io_open:
.. index:: open a devive
.. index:: rtems_io_open
IO_OPEN - Open a device
-----------------------
.. index:: open a devive
.. index:: rtems_io_open
CALLING SEQUENCE:
.. code-block:: c
@ -468,11 +473,11 @@ NOTES:
\clearpage
.. _rtems_io_close:
.. index:: close a device
.. index:: rtems_io_close
IO_CLOSE - Close a device
-------------------------
.. index:: close a device
.. index:: rtems_io_close
CALLING SEQUENCE:
.. code-block:: c
@ -506,11 +511,11 @@ NOTES:
\clearpage
.. _rtems_io_read:
.. index:: read from a device
.. index:: rtems_io_read
IO_READ - Read from a device
----------------------------
.. index:: read from a device
.. index:: rtems_io_read
CALLING SEQUENCE:
.. code-block:: c
@ -545,11 +550,11 @@ NOTES:
\clearpage
.. _rtems_io_write:
.. index:: write to a device
.. index:: rtems_io_write
IO_WRITE - Write to a device
----------------------------
.. index:: write to a device
.. index:: rtems_io_write
CALLING SEQUENCE:
.. code-block:: c
@ -584,13 +589,13 @@ NOTES:
\clearpage
.. _rtems_io_control:
IO_CONTROL - Special device services
------------------------------------
.. index:: special device services
.. index:: IO Control
.. index:: rtems_io_control
IO_CONTROL - Special device services
------------------------------------
CALLING SEQUENCE:
.. code-block:: c

45
c-user/key_concepts.rst
View File

@ -17,11 +17,11 @@ one with these concepts.
.. _objects:
.. index:: objects
Objects
=======
.. index:: objects
RTEMS provides directives which can be used to dynamically create, delete, and
manipulate a set of predefined object types. These types include tasks,
message queues, semaphores, memory regions, memory partitions, timers, ports,
@ -37,14 +37,17 @@ selected by the user as a meaningful "tag" which may commonly reflect the
object's use in the application. Conversely, object IDs are designed to
facilitate efficient object manipulation by the executive.
Object Names
------------
.. index:: object name
.. index:: rtems_name
Object Names
------------
An object name is an unsigned thirty-two bit entity associated with the object
by the user. The data type ``rtems_name`` is used to store object
names... index:: rtems_build_name
names.
.. index:: rtems_build_name
Although not required by RTEMS, object names are often composed of four ASCII
characters which help identify that object. For example, a task which causes a
@ -84,12 +87,13 @@ name:
printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") );
}
Object IDs
----------
.. index:: object ID
.. index:: object ID composition
.. index:: rtems_id
Object IDs
----------
An object ID is a unique unsigned integer value which uniquely identifies an
object instance. Object IDs are passed as arguments to many directives in
RTEMS and RTEMS translates the ID to an internal object pointer. The efficient
@ -198,9 +202,10 @@ create time and freed when the object is deleted. With the exception of user
extension routines, object control blocks are not directly manipulated by user
applications.
.. index:: communication and synchronization
Communication and Synchronization
=================================
.. index:: communication and synchronization
In real-time multitasking applications, the ability for cooperating execution
threads to communicate and synchronize with each other is imperative. A
@ -239,9 +244,10 @@ synchronization, while the event manager primarily provides a high performance
synchronization mechanism. The signal manager supports only asynchronous
communication and is typically used for exception handling.
.. index:: locking protocols
Locking Protocols
=================
.. index:: locking protocols
RTEMS supports the four locking protocols
@ -265,10 +271,10 @@ obtain, release and timeout operations depend on the complexity of this
resource dependency graph.
.. _PriorityInversion:
.. index:: priority inversion
Priority Inversion
------------------
.. index:: priority inversion
Priority inversion is a form of indefinite postponement which is common in
multitasking, preemptive executives with shared resources. Priority inversion
@ -281,11 +287,11 @@ complete its interaction with the resource and release that resource. The high
priority task is effectively prevented from executing by lower priority tasks.
.. _PriorityCeiling:
.. index:: priority ceiling protocol
.. index:: immediate ceiling priority protocol
Immediate Ceiling Priority Protocol (ICPP)
------------------------------------------
.. index:: priority ceiling protocol
.. index:: immediate ceiling priority protocol
Each mutex using the Immediate Ceiling Priority Protocol (ICPP) has a ceiling
priority. The priority of the mutex owner is immediately raised to the ceiling
@ -307,10 +313,10 @@ protocol is more forgiving in that it does not require this apriori
information.
.. _PriorityInheritance:
.. index:: priority inheritance protocol
Priority Inheritance Protocol
-----------------------------
.. index:: priority inheritance protocol
The priority of the mutex owner is raised to the highest priority of all
threads that currently wait for ownership of this mutex :cite:`Sha:1990:PI`.
@ -318,10 +324,10 @@ Since RTEMS 5.1, priority updates due to the priority inheritance protocol
take place immediately and are propagated recursively.
.. _MrsP:
.. index:: Multiprocessor Resource Sharing Protocol (MrsP)
Multiprocessor Resource Sharing Protocol (MrsP)
-----------------------------------------------
.. index:: Multiprocessor Resource Sharing Protocol (MrsP)
The Multiprocessor Resource Sharing Protocol (MrsP) is a generalization of the
priority ceiling protocol to clustered scheduling :cite:`Burns:2013:MrsP`. One
@ -339,10 +345,10 @@ overcome some shortcomings of the original implementation
:cite:`Catellani:2015:MrsP`.
.. _OMIP:
.. index:: O(m) Independence-Preserving Protocol (OMIP)
O(m) Independence-Preserving Protocol (OMIP)
----------------------------------------------------
.. index:: O(m) Independence-Preserving Protocol (OMIP)
The :math:`O(m)` Independence-Preserving Protocol (OMIP) is a generalization of
the priority inheritance protocol to clustered scheduling which avoids the
@ -355,9 +361,10 @@ need internal locking. The complex part of the implementation is contained in
the thread queues and shared with the MrsP support. This locking protocol is
available since RTEMS 5.1.
.. index:: thread queues
Thread Queues
=============
.. index:: thread queues
In case more than one :term:`thread` may wait on a synchronization object, e.g.
a semaphore or a message queue, then the waiting threads are added to a data
@ -415,9 +422,10 @@ A red-black tree is used to implement the priority queues yielding a
:math:`O(log(n))` worst-case time complexity for enqueue and dequeue operations
with :math:`n` being the count of threads already on the queue.
.. index:: time
Time
====
.. index:: time
The development of responsive real-time applications requires an understanding
of how RTEMS maintains and supports time-related operations. The basic unit of
@ -505,9 +513,10 @@ and removal operations offered by the timer wheel algorithms. See also
tree support already used in other areas, e.g. for the thread priority queues.
Less code is a good thing for size, testing and verification.
.. index:: memory management
Memory Management
=================
.. index:: memory management
RTEMS memory management facilities can be grouped into two classes: dynamic
memory allocation and address translation. Dynamic memory allocation is

43
c-user/linker_sets.rst
View File

@ -5,12 +5,11 @@
.. COMMENT: All rights reserved.
.. _linker_sets:
.. index:: linkersets
Linker Sets
***********
.. index:: linkersets
Introduction
============
@ -128,10 +127,10 @@ Directives
\clearpage
.. _RTEMS_LINKER_SET_BEGIN:
.. index:: RTEMS_LINKER_SET_BEGIN
RTEMS_LINKER_SET_BEGIN - Designator of the linker set begin marker
------------------------------------------------------------------
.. index:: RTEMS_LINKER_SET_BEGIN
CALLING SEQUENCE:
.. code-block:: c
@ -161,10 +160,10 @@ NOTE:
\clearpage
.. _RTEMS_LINKER_SET_END:
.. index:: RTEMS_LINKER_SET_END
RTEMS_LINKER_SET_END - Designator of the linker set end marker
--------------------------------------------------------------
.. index:: RTEMS_LINKER_SET_END
CALLING SEQUENCE:
.. code-block:: c
@ -183,10 +182,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_SET_SIZE:
.. index:: RTEMS_LINKER_SET_SIZE
RTEMS_LINKER_SET_SIZE - The linker set size in characters
---------------------------------------------------------
.. index:: RTEMS_LINKER_SET_SIZE
CALLING SEQUENCE:
.. code-block:: c
@ -204,10 +203,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_SET_ITEM_COUNT:
.. index:: RTEMS_LINKER_SET_ITEM_COUNT
RTEMS_LINKER_SET_ITEM_COUNT - The linker set item count
---------------------------------------------------------
.. index:: RTEMS_LINKER_SET_ITEM_COUNT
CALLING SEQUENCE:
.. code-block:: c
@ -224,10 +223,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_SET_IS_EMPTY:
.. index:: RTEMS_LINKER_SET_IS_EMPTY
RTEMS_LINKER_SET_IS_EMPTY - Is the linker set empty?
---------------------------------------------------------
.. index:: RTEMS_LINKER_SET_IS_EMPTY
CALLING SEQUENCE:
.. code-block:: c
@ -245,10 +244,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_SET_FOREACH:
.. index:: RTEMS_LINKER_SET_FOREACH
RTEMS_LINKER_SET_FOREACH - Iterate through the linker set items
---------------------------------------------------------
.. index:: RTEMS_LINKER_SET_FOREACH
CALLING SEQUENCE:
.. code-block:: c
@ -281,10 +280,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_ROSET_DECLARE:
.. index:: RTEMS_LINKER_ROSET_DECLARE
RTEMS_LINKER_ROSET_DECLARE - Declares a read-only linker set
------------------------------------------------------------
.. index:: RTEMS_LINKER_ROSET_DECLARE
CALLING SEQUENCE:
.. code-block:: c
@ -304,10 +303,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_ROSET:
.. index:: RTEMS_LINKER_ROSET
RTEMS_LINKER_ROSET - Defines a read-only linker set
---------------------------------------------------
.. index:: RTEMS_LINKER_ROSET
CALLING SEQUENCE:
.. code-block:: c
@ -327,10 +326,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_ROSET_ITEM_DECLARE:
.. index:: RTEMS_LINKER_ROSET_ITEM_DECLARE
RTEMS_LINKER_ROSET_ITEM_DECLARE - Declares a read-only linker set item
----------------------------------------------------------------------
.. index:: RTEMS_LINKER_ROSET_ITEM_DECLARE
CALLING SEQUENCE:
.. code-block:: c
@ -352,10 +351,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_ROSET_ITEM_REFERENCE:
.. index:: RTEMS_LINKER_ROSET_ITEM_REFERENCE
RTEMS_LINKER_ROSET_ITEM_REFERENCE - References a read-only linker set item
--------------------------------------------------------------------------
.. index:: RTEMS_LINKER_ROSET_ITEM_REFERENCE
CALLING SEQUENCE:
.. code-block:: c
@ -377,10 +376,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_ROSET_ITEM:
.. index:: RTEMS_LINKER_ROSET_ITEM
RTEMS_LINKER_ROSET_ITEM - Defines a read-only linker set item
-------------------------------------------------------------
.. index:: RTEMS_LINKER_ROSET_ITEM
CALLING SEQUENCE:
.. code-block:: c
@ -402,10 +401,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_ROSET_ITEM_ORDERED:
.. index:: RTEMS_LINKER_ROSET_ITEM_ORDERED
RTEMS_LINKER_ROSET_ITEM_ORDERED - Defines an ordered read-only linker set item
------------------------------------------------------------------------------
.. index:: RTEMS_LINKER_ROSET_ITEM_ORDERED
CALLING SEQUENCE:
.. code-block:: c
@ -459,10 +458,10 @@ NOTES:
\clearpage
.. _RTEMS_LINKER_ROSET_CONTENT:
.. index:: RTEMS_LINKER_ROSET_CONTENT
RTEMS_LINKER_ROSET_CONTENT - Marks a declaration as a read-only linker set content
----------------------------------------------------------------------------------
.. index:: RTEMS_LINKER_ROSET_CONTENT
CALLING SEQUENCE:
.. code-block:: c
@ -481,10 +480,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_RWSET_DECLARE:
.. index:: RTEMS_LINKER_RWSET_DECLARE
RTEMS_LINKER_RWSET_DECLARE - Declares a read-write linker set
-------------------------------------------------------------
.. index:: RTEMS_LINKER_RWSET_DECLARE
CALLING SEQUENCE:
.. code-block:: c
@ -504,10 +503,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_RWSET:
.. index:: RTEMS_LINKER_RWSET
RTEMS_LINKER_RWSET - Defines a read-write linker set
----------------------------------------------------
.. index:: RTEMS_LINKER_RWSET
CALLING SEQUENCE:
.. code-block:: c
@ -527,10 +526,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_RWSET_ITEM_DECLARE:
.. index:: RTEMS_LINKER_RWSET_ITEM_DECLARE
RTEMS_LINKER_RWSET_ITEM_DECLARE - Declares a read-write linker set item
-----------------------------------------------------------------------
.. index:: RTEMS_LINKER_RWSET_ITEM_DECLARE
CALLING SEQUENCE:
.. code-block:: c
@ -552,10 +551,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_RWSET_ITEM_REFERENCE:
.. index:: RTEMS_LINKER_RWSET_ITEM_REFERENCE
RTEMS_LINKER_RWSET_ITEM_REFERENCE - References a read-write linker set item
---------------------------------------------------------------------------
.. index:: RTEMS_LINKER_RWSET_ITEM_REFERENCE
CALLING SEQUENCE:
.. code-block:: c
@ -577,10 +576,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_RWSET_ITEM:
.. index:: RTEMS_LINKER_RWSET_ITEM
RTEMS_LINKER_RWSET_ITEM - Defines a read-write linker set item
--------------------------------------------------------------
.. index:: RTEMS_LINKER_RWSET_ITEM
CALLING SEQUENCE:
.. code-block:: c
@ -602,10 +601,10 @@ DESCRIPTION:
\clearpage
.. _RTEMS_LINKER_RWSET_ITEM_ORDERED:
.. index:: RTEMS_LINKER_RWSET_ITEM_ORDERED
RTEMS_LINKER_RWSET_ITEM_ORDERED - Defines an ordered read-write linker set item
-------------------------------------------------------------------------------
.. index:: RTEMS_LINKER_RWSET_ITEM_ORDERED
CALLING SEQUENCE:
.. code-block:: c
@ -659,10 +658,10 @@ NOTES:
\clearpage
.. _RTEMS_LINKER_RWSET_CONTENT:
.. index:: RTEMS_LINKER_RWSET_CONTENT
RTEMS_LINKER_RWSET_CONTENT - Marks a declaration as a read-write linker set content
-----------------------------------------------------------------------------------
.. index:: RTEMS_LINKER_RWSET_CONTENT
CALLING SEQUENCE:
.. code-block:: c

45
c-user/message_manager.rst
View File

@ -4,12 +4,12 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Message Manager
***************
.. index:: messages
.. index:: message queues
Message Manager
***************
Introduction
============
@ -64,9 +64,10 @@ buffer of the message queue or directly to a peer in certain cases. This copy
operation is performed with interrupts disabled. So it is advisable to keep
the messages as short as possible.
.. index:: message queue attributes
Building a Message Queue Attribute Set
--------------------------------------
.. index:: message queue attributes
In general, an attribute set is built by a bitwise OR of the desired attribute
components. The set of valid message queue attributes is provided in the
@ -220,11 +221,11 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_message_queue_create:
.. index:: create a message queue
.. index:: rtems_message_queue_create
MESSAGE_QUEUE_CREATE - Create a queue
-------------------------------------
.. index:: create a message queue
.. index:: rtems_message_queue_create
CALLING SEQUENCE:
.. code-block:: c
@ -307,11 +308,11 @@ NOTES:
\clearpage
.. _rtems_message_queue_ident:
.. index:: get ID of a message queue
.. index:: rtems_message_queue_ident
MESSAGE_QUEUE_IDENT - Get ID of a queue
---------------------------------------
.. index:: get ID of a message queue
.. index:: rtems_message_queue_ident
CALLING SEQUENCE:
.. code-block:: c
@ -360,11 +361,11 @@ NOTES:
\clearpage
.. _rtems_message_queue_delete:
.. index:: delete a message queue
.. index:: rtems_message_queue_delete
MESSAGE_QUEUE_DELETE - Delete a queue
-------------------------------------
.. index:: delete a message queue
.. index:: rtems_message_queue_delete
CALLING SEQUENCE:
.. code-block:: c
@ -418,11 +419,11 @@ NOTES:
\clearpage
.. _rtems_message_queue_send:
.. index:: send message to a queue
.. index:: rtems_message_queue_send
MESSAGE_QUEUE_SEND - Put message at rear of a queue
---------------------------------------------------
.. index:: send message to a queue
.. index:: rtems_message_queue_send
CALLING SEQUENCE:
.. code-block:: c
@ -475,11 +476,11 @@ NOTES:
\clearpage
.. _rtems_message_queue_urgent:
.. index:: put message at front of queue
.. index:: rtems_message_queue_urgent
MESSAGE_QUEUE_URGENT - Put message at front of a queue
------------------------------------------------------
.. index:: put message at front of queue
.. index:: rtems_message_queue_urgent
**CALLING SEQUENCE:**
.. code-block:: c
@ -532,11 +533,11 @@ NOTES:
\clearpage
.. _rtems_message_queue_broadcast:
.. index:: broadcast message to a queue
.. index:: rtems_message_queue_broadcast
MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue
---------------------------------------------------------
.. index:: broadcast message to a queue
.. index:: rtems_message_queue_broadcast
CALLING SEQUENCE:
.. code-block:: c
@ -592,11 +593,11 @@ NOTES:
\clearpage
.. _rtems_message_queue_receive:
.. index:: receive message from a queue
.. index:: rtems_message_queue_receive
MESSAGE_QUEUE_RECEIVE - Receive message from a queue
----------------------------------------------------
.. index:: receive message from a queue
.. index:: rtems_message_queue_receive
CALLING SEQUENCE:
.. code-block:: c
@ -679,11 +680,11 @@ NOTES:
\clearpage
.. _rtems_message_queue_get_number_pending:
.. index:: get number of pending messages
.. index:: rtems_message_queue_get_number_pending
MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue
----------------------------------------------------------------------------
.. index:: get number of pending messages
.. index:: rtems_message_queue_get_number_pending
CALLING SEQUENCE:
.. code-block:: c
@ -718,11 +719,11 @@ NOTES:
\clearpage
.. _rtems_message_queue_flush:
.. index:: flush messages on a queue
.. index:: rtems_message_queue_flush
MESSAGE_QUEUE_FLUSH - Flush all messages on a queue
---------------------------------------------------
.. index:: flush messages on a queue
.. index:: rtems_message_queue_flush
CALLING SEQUENCE:
.. code-block:: c

30
c-user/multiprocessing.rst
View File

@ -4,11 +4,11 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: multiprocessing
Multiprocessing Manager
***********************
.. index:: multiprocessing
Introduction
============
@ -42,11 +42,11 @@ The directives provided by the Manager are:
- rtems_multiprocessing_announce_ - A multiprocessing communications packet has
arrived
.. index:: multiprocessing topologies
Background
==========
.. index:: multiprocessing topologies
RTEMS makes no assumptions regarding the connection media or topology of a
multiprocessor system. The tasks which compose a particular application can be
spread among as many processors as needed to satisfy the application's timing
@ -68,9 +68,10 @@ a homogeneous one. In keeping with RTEMS philosophy of providing transparent
physical node boundaries, the minimal heterogeneous processing required is
isolated in the MPCI layer.
.. index:: nodes, definition
Nodes
-----
.. index:: nodes, definition
A processor in a RTEMS system is referred to as a node. Each node is assigned
a unique non-zero node number by the application designer. RTEMS assumes that
@ -85,9 +86,10 @@ The node number is used by RTEMS to identify each node when performing remote
operations. Thus, the Multiprocessor Communications Interface Layer (MPCI)
must be able to route messages based on the node number.
.. index:: global objects, definition
Global Objects
--------------
.. index:: global objects, definition
All RTEMS objects which are created with the GLOBAL attribute will be known on
all other nodes. Global objects can be referenced from any node in the system,
@ -99,9 +101,10 @@ field in the Multiprocessor Configuration Table. The distribution of tasks to
processors is performed during the application design phase. Dynamic task
relocation is not supported by RTEMS.
.. index:: global objects table
Global Object Table
-------------------
.. index:: global objects table
RTEMS maintains two tables containing object information on every node in a
multiprocessor system: a local object table and a global object table. The
@ -118,9 +121,10 @@ This parameter, as well as the maximum_nodes parameter, is required to be the
same on all nodes. To maintain consistency among the table copies, every node
in the system must be informed of the creation or deletion of a global object.
.. index:: MPCI and remote operations
Remote Operations
-----------------
.. index:: MPCI and remote operations
When an application performs an operation on a remote global object, RTEMS must
generate a Remote Request (RQ) message and send it to the appropriate node.
@ -175,9 +179,10 @@ error handler should be invoked. RTEMS assumes the reliable transmission and
reception of messages by the MPCI and makes no attempt to detect or correct
errors.
.. index:: proxy, definition
Proxies
-------
.. index:: proxy, definition
A proxy is an RTEMS data structure which resides on a remote node and is used
to represent a task which must block as part of a remote operation. This action
@ -381,9 +386,10 @@ The ``to_convert`` field of the ``rtems_packet_prefix`` portion of the packet
indicates how much of the packet in 32-bit units may require conversion in a
heterogeneous system.
.. index:: heterogeneous multiprocessing
Supporting Heterogeneous Environments
-------------------------------------
.. index:: heterogeneous multiprocessing
Developing an MPCI layer for a heterogeneous system requires a thorough
understanding of the differences between the processors which comprise the
@ -476,11 +482,11 @@ usage, and status codes.
\clearpage
.. _rtems_multiprocessing_announce:
.. index:: announce arrival of package
.. index:: rtems_multiprocessing_announce
MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet
-----------------------------------------------------------
.. index:: announce arrival of package
.. index:: rtems_multiprocessing_announce
CALLING SEQUENCE:
.. code-block:: c

80
c-user/object_services.rst
View File

@ -4,11 +4,11 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: object manipulation
Object Services
***************
.. index:: object manipulation
Introduction
============
@ -181,11 +181,11 @@ Directives
\clearpage
.. _rtems_build_name:
.. index:: build object name
.. index:: rtems_build_name
BUILD_NAME - Build object name from characters
----------------------------------------------
.. index:: build object name
.. index:: rtems_build_name
CALLING SEQUENCE:
.. code-block:: c
@ -213,13 +213,13 @@ NOTES:
\clearpage
.. _rtems_object_get_classic_name:
OBJECT_GET_CLASSIC_NAME - Lookup name from id
---------------------------------------------
.. index:: get name from id
.. index:: obtain name from id
.. index:: rtems_object_get_classic_name
OBJECT_GET_CLASSIC_NAME - Lookup name from id
---------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -251,13 +251,13 @@ NOTES:
\clearpage
.. _rtems_object_get_name:
OBJECT_GET_NAME - Obtain object name as string
----------------------------------------------
.. index:: get object name as string
.. index:: obtain object name as string
.. index:: rtems_object_get_name
OBJECT_GET_NAME - Obtain object name as string
----------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -284,11 +284,11 @@ NOTES:
\clearpage
.. _rtems_object_set_name:
.. index:: set object name
.. index:: rtems_object_set_name
OBJECT_SET_NAME - Set object name
---------------------------------
.. index:: set object name
.. index:: rtems_object_set_name
CALLING SEQUENCE:
.. code-block:: c
@ -331,11 +331,11 @@ NOTES:
\clearpage
.. _rtems_object_id_get_api:
.. index:: obtain API from id
.. index:: rtems_object_id_get_api
OBJECT_ID_GET_API - Obtain API from Id
--------------------------------------
.. index:: obtain API from id
.. index:: rtems_object_id_get_api
CALLING SEQUENCE:
.. code-block:: c
@ -360,11 +360,11 @@ NOTES:
\clearpage
.. _rtems_object_id_get_class:
.. index:: obtain class from object id
.. index:: rtems_object_id_get_class
OBJECT_ID_GET_CLASS - Obtain Class from Id
------------------------------------------
.. index:: obtain class from object id
.. index:: rtems_object_id_get_class
CALLING SEQUENCE:
.. code-block:: c
@ -389,11 +389,11 @@ NOTES:
\clearpage
.. _rtems_object_id_get_node:
.. index:: obtain node from object id
.. index:: rtems_object_id_get_node
OBJECT_ID_GET_NODE - Obtain Node from Id
----------------------------------------
.. index:: obtain node from object id
.. index:: rtems_object_id_get_node
CALLING SEQUENCE:
.. code-block:: c
@ -418,11 +418,11 @@ NOTES:
\clearpage
.. _rtems_object_id_get_index:
.. index:: obtain index from object id
.. index:: rtems_object_id_get_index
OBJECT_ID_GET_INDEX - Obtain Index from Id
------------------------------------------
.. index:: obtain index from object id
.. index:: rtems_object_id_get_index
CALLING SEQUENCE:
.. code-block:: c
@ -447,11 +447,11 @@ NOTES:
\clearpage
.. _rtems_build_id:
.. index:: build object id from components
.. index:: rtems_build_id
BUILD_ID - Build Object Id From Components
------------------------------------------
.. index:: build object id from components
.. index:: rtems_build_id
CALLING SEQUENCE:
.. code-block:: c
@ -481,11 +481,11 @@ NOTES:
\clearpage
.. _rtems_object_id_api_minimum:
.. index:: obtain minimum API value
.. index:: rtems_object_id_api_minimum
OBJECT_ID_API_MINIMUM - Obtain Minimum API Value
------------------------------------------------
.. index:: obtain minimum API value
.. index:: rtems_object_id_api_minimum
CALLING SEQUENCE:
.. code-block:: c
@ -506,11 +506,11 @@ NOTES:
\clearpage
.. _rtems_object_id_api_maximum:
.. index:: obtain maximum API value
.. index:: rtems_object_id_api_maximum
OBJECT_ID_API_MAXIMUM - Obtain Maximum API Value
------------------------------------------------
.. index:: obtain maximum API value
.. index:: rtems_object_id_api_maximum
CALLING SEQUENCE:
.. code-block:: c
@ -531,11 +531,11 @@ NOTES:
\clearpage
.. _rtems_object_api_minimum_class:
.. index:: obtain minimum class value
.. index:: rtems_object_api_minimum_class
OBJECT_API_MINIMUM_CLASS - Obtain Minimum Class Value
-----------------------------------------------------
.. index:: obtain minimum class value
.. index:: rtems_object_api_minimum_class
CALLING SEQUENCE:
.. code-block:: c
@ -562,11 +562,11 @@ NOTES:
\clearpage
.. _rtems_object_api_maximum_class:
.. index:: obtain maximum class value
.. index:: rtems_object_api_maximum_class
OBJECT_API_MAXIMUM_CLASS - Obtain Maximum Class Value
-----------------------------------------------------
.. index:: obtain maximum class value
.. index:: rtems_object_api_maximum_class
CALLING SEQUENCE:
.. code-block:: c
@ -593,11 +593,11 @@ NOTES:
\clearpage
.. _rtems_object_id_api_minimum_class:
.. index:: obtain minimum class value for an API
.. index:: rtems_object_id_api_minimum_class
OBJECT_ID_API_MINIMUM_CLASS - Obtain Minimum Class Value for an API
-------------------------------------------------------------------
.. index:: obtain minimum class value for an API
.. index:: rtems_object_id_api_minimum_class
CALLING SEQUENCE:
.. code-block:: c
@ -624,11 +624,11 @@ NOTES:
\clearpage
.. _rtems_object_id_api_maximum_class:
.. index:: obtain maximum class value for an API
.. index:: rtems_object_id_api_maximum_class
OBJECT_ID_API_MAXIMUM_CLASS - Obtain Maximum Class Value for an API
-------------------------------------------------------------------
.. index:: obtain maximum class value for an API
.. index:: rtems_object_id_api_maximum_class
CALLING SEQUENCE:
.. code-block:: c
@ -655,11 +655,11 @@ NOTES:
\clearpage
.. _rtems_object_get_api_name:
.. index:: obtain API name
.. index:: rtems_object_get_api_name
OBJECT_GET_API_NAME - Obtain API Name
-------------------------------------
.. index:: obtain API name
.. index:: rtems_object_get_api_name
CALLING SEQUENCE:
.. code-block:: c
@ -687,11 +687,11 @@ NOTES:
\clearpage
.. _rtems_object_get_api_class_name:
.. index:: obtain class name
.. index:: rtems_object_get_api_class_name
OBJECT_GET_API_CLASS_NAME - Obtain Class Name
---------------------------------------------
.. index:: obtain class name
.. index:: rtems_object_get_api_class_name
CALLING SEQUENCE:
.. code-block:: c
@ -723,11 +723,11 @@ NOTES:
\clearpage
.. _rtems_object_get_class_information:
.. index:: obtain class information
.. index:: rtems_object_get_class_information
OBJECT_GET_CLASS_INFORMATION - Obtain Class Information
-------------------------------------------------------
.. index:: obtain class information
.. index:: rtems_object_get_class_information
CALLING SEQUENCE:
.. code-block:: c

8
c-user/overview.rst
View File

@ -38,6 +38,8 @@ dependent are provided in the Applications Supplement documents. A supplement
document which addresses specific architectural issues that affect RTEMS is
provided for each processor type that is supported.
.. index:: Real-time applications
Real-time Application Systems
=============================
@ -73,6 +75,8 @@ communication channels and global resources that must be shared between
competing processors are introduced. The ramifications of multiple processors
complicate each and every characteristic of a real-time system.
.. index:: Real-time executive
Real-time Executive
===================
@ -113,6 +117,8 @@ developer is then able to concentrate solely on the application. By using
standard software components, the time and cost required to develop
sophisticated real-time applications is significantly reduced.
.. index:: Application architecture
RTEMS Application Architecture
==============================
@ -135,6 +141,8 @@ real-time system can benefit from this architecture by building a rich library
of standard application components which can be used repeatedly in other
real-time projects.
.. index:: Internal Architecture
RTEMS Internal Architecture
===========================

34
c-user/partition_manager.rst
View File

@ -4,11 +4,11 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: partitions
Partition Manager
*****************
.. index:: partitions
Introduction
============
@ -28,9 +28,10 @@ fixed-size units. The directives provided by the partition manager are:
Background
==========
.. index:: partition, definition
Partition Manager Definitions
-----------------------------
.. index:: partition, definition
A partition is a physically contiguous memory area divided into fixed-size
buffers that can be dynamically allocated and deallocated.
@ -45,9 +46,10 @@ buffer is allocated, the entire buffer is available for application use.
Therefore, modifying memory that is outside of an allocated buffer could
destroy the free buffer chain or the contents of an adjacent allocated buffer.
.. index:: partition attribute set, building
Building a Partition Attribute Set
----------------------------------
.. index:: partition attribute set, building
In general, an attribute set is built by a bitwise OR of the desired attribute
components. The set of valid partition attributes is provided in the following
@ -134,11 +136,11 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_partition_create:
.. index:: create a partition
.. index:: rtems_partition_create
PARTITION_CREATE - Create a partition
-------------------------------------
.. index:: create a partition
.. index:: rtems_partition_create
CALLING SEQUENCE:
.. code-block:: c
@ -228,13 +230,13 @@ NOTES:
\clearpage
.. _rtems_partition_ident:
PARTITION_IDENT - Get ID of a partition
---------------------------------------
.. index:: get ID of a partition
.. index:: obtain ID of a partition
.. index:: rtems_partition_ident
PARTITION_IDENT - Get ID of a partition
---------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -282,11 +284,11 @@ NOTES:
\clearpage
.. _rtems_partition_delete:
.. index:: delete a partition
.. index:: rtems_partition_delete
PARTITION_DELETE - Delete a partition
-------------------------------------
.. index:: delete a partition
.. index:: rtems_partition_delete
CALLING SEQUENCE:
.. code-block:: c
@ -331,13 +333,13 @@ NOTES:
\clearpage
.. _rtems_partition_get_buffer:
PARTITION_GET_BUFFER - Get buffer from a partition
--------------------------------------------------
.. index:: get buffer from partition
.. index:: obtain buffer from partition
.. index:: rtems_partition_get_buffer
PARTITION_GET_BUFFER - Get buffer from a partition
--------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -379,11 +381,11 @@ NOTES:
\clearpage
.. _rtems_partition_return_buffer:
.. index:: return buffer to partitition
.. index:: rtems_partition_return_buffer
PARTITION_RETURN_BUFFER - Return buffer to a partition
------------------------------------------------------
.. index:: return buffer to partitition
.. index:: rtems_partition_return_buffer
CALLING SEQUENCE:
.. code-block:: c

8
c-user/pci_library.rst
View File

@ -4,12 +4,12 @@
.. COMMENT: Aeroflex Gaisler AB
.. COMMENT: All rights reserved.
.. index:: PCI
.. index:: libpci
PCI Library
***********
.. index:: libpci
Introduction
============
@ -390,6 +390,8 @@ this is mosly for debugging or for development systems. When the product is
finally deployed macros switch to using the inline functions instead which have
been configured for the correct endianness.
.. index:: PCI address translation
PCI address translation
~~~~~~~~~~~~~~~~~~~~~~~
@ -408,6 +410,8 @@ different PCI spaces/regions.
/* Translate CPU accessible address into PCI address (for DMA) */
static inline int pci_cpu2pci(uint32_t *address, int type);
.. index:: PCI Interrupt
PCI Interrupt
-------------

72
c-user/rate_monotonic_manager.rst
View File

@ -5,12 +5,12 @@
.. COMMENT: COPYRIGHT (c) 2017 Kuan-Hsun Chen.
.. COMMENT: All rights reserved.
Rate Monotonic Manager
**********************
.. index:: rate mononitonic tasks
.. index:: periodic tasks
Rate Monotonic Manager
**********************
Introduction
============
@ -133,9 +133,10 @@ milliseconds every 100 (10 percent of the CPU). As a general rule of thumb,
the higher frequency at which a task executes, the more important it is to
optimize that task.
.. index:: periodic task, definition
Periodicity Definitions
----------------------------------
.. index:: periodic task, definition
A periodic task is one which must be executed at a regular interval. The
interval between successive iterations of the task is referred to as its
@ -165,11 +166,12 @@ joystick. The mechanical action of the fire button ensures a minimum time
period between successive activations, but the missile must be launched by a
hard deadline.
Rate Monotonic Scheduling Algorithm
-----------------------------------
.. index:: Rate Monotonic Scheduling Algorithm, definition
.. index:: RMS Algorithm, definition
Rate Monotonic Scheduling Algorithm
-----------------------------------
The Rate Monotonic Scheduling Algorithm (RMS) is important to real-time systems
designers because it allows one to sufficiently guarantee that a set of tasks
is schedulable (see :cite:`Liu:1973:Scheduling`, :cite:`Lehoczky:1989:RM`,
@ -229,11 +231,11 @@ highest priority non-critical task. Although RMS may be used to assign
priorities to the non-critical tasks, it is not necessary. In this instance,
schedulability is only guaranteed for the critical task set.
.. index:: RMS schedulability analysis
Schedulability Analysis
-----------------------
.. index:: RMS schedulability analysis
RMS allows application designers to ensure that tasks can meet all deadlines under fixed-priority assignment,
even under transient overload, without knowing exactly when any given task will
execute by applying proven schedulability analysis rules.
@ -261,9 +263,10 @@ assumptions:
Once the basic schedulability analysis is understood, some of the above
assumptions can be relaxed and the side-effects accounted for.
.. index:: RMS Processor Utilization Rule
Processor Utilization Rule
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. index:: RMS Processor Utilization Rule
The Processor Utilization Rule requires that processor utilization be
calculated based upon the period and execution time of each task.
@ -312,9 +315,10 @@ upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor
Utilization Rule. Therefore, this task set is guaranteed to be schedulable
using RMS.
.. index:: RMS First Deadline Rule
First Deadline Rule
^^^^^^^^^^^^^^^^^^^
.. index:: RMS First Deadline Rule
If a given set of tasks do exceed the processor utilization upper limit imposed
by the Processor Utilization Rule, they can still be guaranteed to meet all
@ -631,11 +635,11 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_rate_monotonic_create:
.. index:: create a period
.. index:: rtems_rate_monotonic_create
RATE_MONOTONIC_CREATE - Create a rate monotonic period
------------------------------------------------------
.. index:: create a period
.. index:: rtems_rate_monotonic_create
CALLING SEQUENCE:
.. code-block:: c
@ -671,13 +675,13 @@ NOTES:
\clearpage
.. _rtems_rate_monotonic_ident:
RATE_MONOTONIC_IDENT - Get ID of a period
-----------------------------------------
.. index:: get ID of a period
.. index:: obtain ID of a period
.. index:: rtems_rate_monotonic_ident
RATE_MONOTONIC_IDENT - Get ID of a period
-----------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -710,11 +714,11 @@ NOTES:
\clearpage
.. _rtems_rate_monotonic_cancel:
.. index:: cancel a period
.. index:: rtems_rate_monotonic_cancel
RATE_MONOTONIC_CANCEL - Cancel a period
---------------------------------------
.. index:: cancel a period
.. index:: rtems_rate_monotonic_cancel
CALLING SEQUENCE:
.. code-block:: c
@ -752,10 +756,10 @@ NOTES:
.. _rtems_rate_monotonic_delete:
.. index:: rtems_rate_monotonic_delete
.. index:: delete a period
RATE_MONOTONIC_DELETE - Delete a rate monotonic period
------------------------------------------------------
.. index:: delete a period
CALLING SEQUENCE:
.. code-block:: c
@ -790,14 +794,14 @@ NOTES:
\clearpage
.. _rtems_rate_monotonic_period:
RATE_MONOTONIC_PERIOD - Conclude current/Start next period
----------------------------------------------------------
.. index:: conclude current period
.. index:: start current period
.. index:: period initiation
.. index:: rtems_rate_monotonic_period
RATE_MONOTONIC_PERIOD - Conclude current/Start next period
----------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -844,13 +848,13 @@ NOTES:
\clearpage
.. _rtems_rate_monotonic_get_status:
RATE_MONOTONIC_GET_STATUS - Obtain status from a period
-------------------------------------------------------
.. index:: get status of period
.. index:: obtain status of period
.. index:: rtems_rate_monotonic_get_status
RATE_MONOTONIC_GET_STATUS - Obtain status from a period
-------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -909,13 +913,13 @@ NOTES:
\clearpage
.. _rtems_rate_monotonic_get_statistics:
RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period
---------------------------------------------------------------
.. index:: get statistics of period
.. index:: obtain statistics of period
.. index:: rtems_rate_monotonic_get_statistics
RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period
---------------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -978,11 +982,11 @@ NOTES:
\clearpage
.. _rtems_rate_monotonic_reset_statistics:
.. index:: reset statistics of period
.. index:: rtems_rate_monotonic_reset_statistics
RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period
---------------------------------------------------------------
.. index:: reset statistics of period
.. index:: rtems_rate_monotonic_reset_statistics
CALLING SEQUENCE:
.. code-block:: c
@ -1012,11 +1016,11 @@ NOTES:
\clearpage
.. _rtems_rate_monotonic_reset_all_statistics:
.. index:: reset statistics of all periods
.. index:: rtems_rate_monotonic_reset_all_statistics
RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods
----------------------------------------------------------------------
.. index:: reset statistics of all periods
.. index:: rtems_rate_monotonic_reset_all_statistics
CALLING SEQUENCE:
.. code-block:: c
@ -1038,13 +1042,13 @@ NOTES:
\clearpage
.. _rtems_rate_monotonic_report_statistics:
RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report
-----------------------------------------------------------------
.. index:: print period statistics report
.. index:: period statistics report
.. index:: rtems_rate_monotonic_report_statistics
RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report
-----------------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c

8
c-user/red_black_trees.rst
View File

@ -4,11 +4,12 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: Red-Black Trees
.. index:: rbtrees
Red-Black Trees
***************
.. index:: rbtrees
Introduction
============
@ -111,9 +112,10 @@ Examples for using the red-black trees can be found in the
Directives
==========
.. index:: rbtree doc
Documentation for the Red-Black Tree Directives
-----------------------------------------------
.. index:: rbtree doc
Source documentation for the Red-Black Tree API can be found in the generated
Doxygen output for ``cpukit/sapi``.

47
c-user/region_manager.rst
View File

@ -4,11 +4,11 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: regions
Region Manager
**************
.. index:: regions
Introduction
============
@ -34,11 +34,12 @@ variable sized units. The directives provided by the region manager are:
Background
==========
Region Manager Definitions
--------------------------
.. index:: region, definition
.. index:: segment, definition
Region Manager Definitions
--------------------------
A region makes up a physically contiguous memory space with user-defined
boundaries from which variable-sized segments are dynamically allocated and
deallocated. A segment is a variable size section of memory which is allocated
@ -59,9 +60,10 @@ boundaries while the region is currently active in the system.
Upon return to the region, the free block is coalesced with its neighbors (if
free) on both sides to produce the largest possible unused block.
.. index:: region attribute set, building
Building an Attribute Set
-------------------------
.. index:: region attribute set, building
In general, an attribute set is built by a bitwise OR of the desired attribute
components. The set of valid region attributes is provided in the following
@ -223,10 +225,11 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_region_create:
.. index:: create a region
REGION_CREATE - Create a region
-------------------------------
.. index:: create a region
CALLING SEQUENCE:
.. code-block:: c
@ -298,13 +301,13 @@ NOTES:
\clearpage
.. _rtems_region_ident:
REGION_IDENT - Get ID of a region
---------------------------------
.. index:: get ID of a region
.. index:: obtain ID of a region
.. index:: rtems_region_ident
REGION_IDENT - Get ID of a region
---------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -340,11 +343,11 @@ NOTES:
\clearpage
.. _rtems_region_delete:
.. index:: delete a region
.. index:: rtems_region_delete
REGION_DELETE - Delete a region
-------------------------------
.. index:: delete a region
.. index:: rtems_region_delete
CALLING SEQUENCE:
.. code-block:: c
@ -381,13 +384,13 @@ NOTES:
\clearpage
.. _rtems_region_extend:
REGION_EXTEND - Add memory to a region
--------------------------------------
.. index:: add memory to a region
.. index:: region, add memory
.. index:: rtems_region_extend
REGION_EXTEND - Add memory to a region
--------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -434,11 +437,11 @@ NOTES:
\clearpage
.. _rtems_region_get_segment:
.. index:: get segment from region
.. index:: rtems_region_get_segment
REGION_GET_SEGMENT - Get segment from a region
----------------------------------------------
.. index:: get segment from region
.. index:: rtems_region_get_segment
CALLING SEQUENCE:
.. code-block:: c
@ -520,11 +523,11 @@ NOTES:
\clearpage
.. _rtems_region_return_segment:
.. index:: return segment to region
.. index:: rtems_region_return_segment
REGION_RETURN_SEGMENT - Return segment to a region
--------------------------------------------------
.. index:: return segment to region
.. index:: rtems_region_return_segment
CALLING SEQUENCE:
.. code-block:: c
@ -569,11 +572,11 @@ NOTES:
\clearpage
.. _rtems_region_get_segment_size:
.. index:: get size of segment
.. index:: rtems_region_get_segment_size
REGION_GET_SEGMENT_SIZE - Obtain size of a segment
--------------------------------------------------
.. index:: get size of segment
.. index:: rtems_region_get_segment_size
CALLING SEQUENCE:
.. code-block:: c
@ -611,11 +614,11 @@ NOTES:
\clearpage
.. _rtems_region_resize_segment:
.. index:: resize segment
.. index:: rtems_region_resize_segment
REGION_RESIZE_SEGMENT - Change size of a segment
------------------------------------------------
.. index:: resize segment
.. index:: rtems_region_resize_segment
CALLING SEQUENCE:
.. code-block:: c

3
c-user/rtems_data_types.rst
View File

@ -4,6 +4,9 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: RTEMS Data Types
.. index:: data types
RTEMS Data Types
****************

43
c-user/scheduling_concepts.rst
View File

@ -4,12 +4,12 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Scheduling Concepts
*******************
.. index:: scheduling
.. index:: task scheduling
Scheduling Concepts
*******************
Introduction
============
@ -39,11 +39,11 @@ The directives provided by the scheduler manager are:
- rtems_scheduler_remove_processor_ - Remove processor from a scheduler
.. index:: scheduling algorithms
Scheduling Algorithms
---------------------
.. index:: scheduling algorithms
RTEMS provides a plugin framework which allows it to support multiple
scheduling algorithms. RTEMS includes multiple scheduling algorithms and the
user can select which of these they wish to use in their application at
@ -60,9 +60,10 @@ scheduling algorithm. This scheduling algoritm is suitable for uniprocessor
Scheduler*. Unless the user configures another scheduling algorithm, RTEMS
will use this on uniprocessor systems.
.. index:: priority scheduling
Priority Scheduling
-------------------
.. index:: priority scheduling
When using priority based scheduling, RTEMS allocates the processor using a
priority-based, preemptive algorithm augmented to provide round-robin
@ -153,9 +154,10 @@ supporting a large number of tasks.
This scheduler is only aware of a single core.
.. index:: earliest deadline first scheduling
Earliest Deadline First Scheduler
---------------------------------
.. index:: earliest deadline first scheduling
This is an alternative scheduler in RTEMS for single core applications. The
primary EDF advantage is high total CPU utilization (theoretically up to
@ -185,9 +187,10 @@ period, it has to be finished until the end of this period. The call of
deadline. Moreover, the ``rtems_rate_monotonic_cancel`` and
``rtems_rate_monotonic_delete`` calls clear the deadlines assigned to the task.
.. index:: constant bandwidth server scheduling
Constant Bandwidth Server Scheduling (CBS)
------------------------------------------
.. index:: constant bandwidth server scheduling
This is an alternative scheduler in RTEMS for single core applications. The
CBS is a budget aware extension of EDF scheduler. The main goal of this
@ -264,11 +267,11 @@ levels). This scheduler supports arbitrary task processor affinities. The
worst-case run-time complexity of some scheduler operations exceeds
:math:`O(n)` while :math:`n` is the count of ready tasks.
.. index:: scheduling mechanisms
Scheduling Modification Mechanisms
==================================
.. index:: scheduling mechanisms
RTEMS provides four mechanisms which allow the user to alter the task
scheduling decisions:
@ -290,9 +293,10 @@ timeslicing and manual round-robin it is important to keep in mind that
preemption (if enabled) of a task by higher priority tasks will occur as
required, overriding the other factors presented in the description.
.. index:: task priority
Task Priority and Scheduling
----------------------------
.. index:: task priority
The most significant task scheduling modification mechanism is the ability for
the user to assign a priority level to each individual task when it is created
@ -301,9 +305,10 @@ on the configured scheduler. A lower priority level means higher priority
(higher importance). The maximum priority level of the default uniprocessor
scheduler is 255.
.. index:: preemption
Preemption
----------
.. index:: preemption
Another way the user can alter the basic scheduling algorithm is by
manipulating the preemption mode flag (``RTEMS_PREEMPT_MASK``) of individual
@ -314,11 +319,12 @@ higher priority levels will not be allowed to execute. Note that the
preemption setting has no effect on the manner in which a task is scheduled.
It only applies once a task has control of the processor.
Timeslicing
-----------
.. index:: timeslicing
.. index:: round robin scheduling
Timeslicing
-----------
Timeslicing or round-robin scheduling is an additional method which can be used
to alter the basic scheduling algorithm. Like preemption, timeslicing is
specified on a task by task basis using the timeslicing mode flag
@ -333,9 +339,10 @@ and continues to run. Remember that a higher priority task will preempt the
task (unless preemption is disabled) as soon as it is ready to run, even if the
task has not used up its entire timeslice.
.. index:: manual round robin
Manual Round-Robin
------------------
.. index:: manual round robin
The final mechanism for altering the RTEMS scheduling algorithm is called
manual round-robin. Manual round-robin is invoked by using
@ -345,9 +352,10 @@ immediately returned to the ready chain at the end of its priority group. If
no other tasks of the same priority are ready to run, then the task does not
lose control of the processor.
.. index:: dispatching
Dispatching Tasks
=================
.. index:: dispatching
The dispatcher is the RTEMS component responsible for allocating the processor
to a ready task. In order to allocate the processor to one task, it must be
@ -370,9 +378,10 @@ unnecessary save and restore operations, the state of the numeric coprocessor
is only saved when a ``RTEMS_FLOATING_POINT`` task is dispatched and that task
was not the last task to utilize the coprocessor.
.. index:: task state transitions
Task State Transitions
======================
.. index:: task state transitions
Tasks in an RTEMS system must always be in one of the five allowable task
states. These states are: executing, ready, blocked, dormant, and

43
c-user/semaphore_manager.rst
View File

@ -4,14 +4,14 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
Semaphore Manager
*****************
.. index:: semaphores
.. index:: binary semaphores
.. index:: counting semaphores
.. index:: mutual exclusion
Semaphore Manager
*****************
Introduction
============
@ -325,11 +325,11 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_semaphore_create:
.. index:: create a semaphore
.. index:: rtems_semaphore_create
SEMAPHORE_CREATE - Create a semaphore
-------------------------------------
.. index:: create a semaphore
.. index:: rtems_semaphore_create
CALLING SEQUENCE:
@ -437,13 +437,12 @@ NOTES:
\clearpage
.. _rtems_semaphore_ident:
.. index:: get ID of a semaphore
.. index:: obtain ID of a semaphore
.. index:: rtems_semaphore_ident
SEMAPHORE_IDENT - Get ID of a semaphore
---------------------------------------
.. index:: get ID of a semaphore
.. index:: obtain ID of a semaphore
.. index:: rtems_semaphore_ident
CALLING SEQUENCE:
.. code-block:: c
@ -490,11 +489,11 @@ NOTES:
\clearpage
.. _rtems_semaphore_delete:
.. index:: delete a semaphore
.. index:: rtems_semaphore_delete
SEMAPHORE_DELETE - Delete a semaphore
-------------------------------------
.. index:: delete a semaphore
.. index:: rtems_semaphore_delete
CALLING SEQUENCE:
.. code-block:: c
@ -546,13 +545,13 @@ NOTES:
\clearpage
.. _rtems_semaphore_obtain:
SEMAPHORE_OBTAIN - Acquire a semaphore
--------------------------------------
.. index:: obtain a semaphore
.. index:: lock a semaphore
.. index:: rtems_semaphore_obtain
SEMAPHORE_OBTAIN - Acquire a semaphore
--------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -645,13 +644,13 @@ NOTES:
\clearpage
.. _rtems_semaphore_release:
SEMAPHORE_RELEASE - Release a semaphore
---------------------------------------
.. index:: release a semaphore
.. index:: unlock a semaphore
.. index:: rtems_semaphore_release
SEMAPHORE_RELEASE - Release a semaphore
---------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -706,13 +705,13 @@ NOTES:
\clearpage
.. _rtems_semaphore_flush:
SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore
----------------------------------------------------------
.. index:: flush a semaphore
.. index:: unblock all tasks waiting on a semaphore
.. index:: rtems_semaphore_flush
SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore
----------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -762,11 +761,11 @@ NOTES:
\clearpage
.. _rtems_semaphore_set_priority:
.. index:: set priority by scheduler for a semaphore
.. index:: rtems_semaphore_set_priority
SEMAPHORE_SET_PRIORITY - Set priority by scheduler for a semaphore
------------------------------------------------------------------
.. index:: set priority by scheduler for a semaphore
.. index:: rtems_semaphore_set_priority
CALLING SEQUENCE:
.. code-block:: c

34
c-user/signal_manager.rst
View File

@ -4,11 +4,11 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: signals
Signal Manager
**************
.. index:: signals
Introduction
============
@ -22,11 +22,12 @@ communication. The directives provided by the signal manager are:
Background
==========
Signal Manager Definitions
--------------------------
.. index:: asynchronous signal routine
.. index:: ASR
Signal Manager Definitions
--------------------------
The signal manager allows a task to optionally define an asynchronous signal
routine (ASR). An ASR is to a task what an ISR is to an application's set of
tasks. When the processor is interrupted, the execution of an application is
@ -46,11 +47,12 @@ A signal set is posted when it is directed (or sent) to a task. A pending
signal is a signal that has been sent to a task with a valid ASR, but has not
been processed by that task's ASR.
A Comparison of ASRs and ISRs
-----------------------------
.. index:: ASR vs. ISR
.. index:: ISR vs. ASR
A Comparison of ASRs and ISRs
-----------------------------
The format of an ASR is similar to that of an ISR with the following
exceptions:
@ -66,9 +68,10 @@ exceptions:
- An ASR has a task mode which can be different from that of the task. An ISR
does not execute as a task and, as a result, does not have a task mode.
.. index:: signal set, building
Building a Signal Set
---------------------
.. index:: signal set, building
A signal set is built by a bitwise OR of the desired signals. The set of valid
signals is ``RTEMS_SIGNAL_0`` through ``RTEMS_SIGNAL_31``. If a signal is not
@ -82,9 +85,10 @@ consisting of ``RTEMS_SIGNAL_6``, ``RTEMS_SIGNAL_15``, and ``RTEMS_SIGNAL_31``.
The signal parameter provided to the ``rtems_signal_send`` directive should be
``RTEMS_SIGNAL_6 | RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``.
.. index:: ASR mode, building
Building an ASR Mode
--------------------
.. index:: ASR mode, building
In general, an ASR's mode is built by a bitwise OR of the desired mode
components. The set of valid mode components is the same as those allowed with
@ -175,6 +179,8 @@ sending the same signal multiple times to a task (without any intermediate
signal processing occurring for the task), has the same result as sending that
signal to that task once.
.. index:: rtems_asr
Processing an ASR
-----------------
@ -185,8 +191,6 @@ and ISRs is limited to the meaning of the single argument passed to an ASR.
The ASR should have the following calling sequence and adhere to C calling
conventions:
.. index:: rtems_asr
.. code-block:: c
rtems_asr user_routine(
@ -208,13 +212,13 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_signal_catch:
SIGNAL_CATCH - Establish an ASR
-------------------------------
.. index:: establish an ASR
.. index:: install an ASR
.. index:: rtems_signal_catch
SIGNAL_CATCH - Establish an ASR
-------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -269,11 +273,11 @@ NOTES:
\clearpage
.. _rtems_signal_send:
.. index:: send signal set
.. index:: rtems_signal_send
SIGNAL_SEND - Send signal set to a task
---------------------------------------
.. index:: send signal set
.. index:: rtems_signal_send
CALLING SEQUENCE:
.. code-block:: c

5
c-user/stack_bounds_checker.rst
View File

@ -4,11 +4,12 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: Stack Bounds Checker
.. index:: stack
Stack Bounds Checker
********************
.. index:: stack
Introduction
============

13
c-user/symmetric_multiprocessing_services.rst
View File

@ -5,6 +5,9 @@
.. COMMENT: Copyright (c) 2017 embedded brains GmbH.
.. COMMENT: All rights reserved.
.. index:: Symmetric Multiprocessing
.. index:: SMP
Symmetric Multiprocessing (SMP)
*******************************
@ -124,11 +127,12 @@ when a task switch occurred at just the wrong moment. Now there are N-1 tasks
executing in parallel all the time and this results in many more opportunities
for small windows in critical sections to be hit.
Task Affinity
-------------
.. index:: task affinity
.. index:: thread affinity
Task Affinity
-------------
RTEMS provides services to manipulate the affinity of a task. Affinity is used
to specify the subset of processors in an SMP system on which a particular task
can execute.
@ -144,11 +148,12 @@ not support affinity, it is likely to ignore all attempts to set affinity.
The scheduler with support for arbitary processor affinities uses a proof of
concept implementation. See https://devel.rtems.org/ticket/2510.
Task Migration
--------------
.. index:: task migration
.. index:: thread migration
Task Migration
--------------
With more than one processor in the system tasks can migrate from one processor
to another. There are four reasons why tasks migrate in RTEMS.

147
c-user/task_manager.rst
View File

@ -4,11 +4,11 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: tasks
Task Manager
************
.. index:: tasks
Introduction
============
@ -56,9 +56,10 @@ and administer tasks. The directives provided by the task manager are:
Background
==========
.. index:: task, definition
Task Definition
---------------
.. index:: task, definition
Many definitions of a task have been proposed in computer literature.
Unfortunately, none of these definitions encompasses all facets of the concept
@ -102,9 +103,10 @@ regains control of the processor, its context is restored from the TCB. When a
task is restarted, the initial state of the task is restored from the starting
context area in the task's TCB.
.. index:: task name
Task Name
---------
.. index:: task name
By default, the task name is defined by the task object name given to
:ref:`rtems_task_create() <rtems_task_create>`. The task name can be obtained
@ -116,9 +118,10 @@ The maximum size of a task name is defined by the application configuration
option :ref:`CONFIGURE_MAXIMUM_THREAD_NAME_SIZE
<CONFIGURE_MAXIMUM_THREAD_NAME_SIZE>`.
.. index:: task states
Task States
-----------
.. index:: task states
A task may exist in one of the following five states:
@ -140,12 +143,13 @@ tasks appear to execute in parallel, but actually each is dispatched to the CPU
for periods of time determined by the RTEMS scheduling algorithm. The
scheduling of a task is based on its current state and priority.
Task Priority
-------------
.. index:: task priority
.. index:: priority, task
.. index:: rtems_task_priority
Task Priority
-------------
A task's priority determines its importance in relation to the other tasks
executing on the same processor. RTEMS supports 255 levels of priority ranging
from 1 to 255. The data type ``rtems_task_priority`` is used to store task
@ -164,11 +168,12 @@ Priorities are used by the scheduler to determine which ready task will be
allowed to execute. In general, the higher the logical priority of a task, the
more likely it is to receive processor execution time.
Task Mode
---------
.. index:: task mode
.. index:: rtems_task_mode
Task Mode
---------
A task's execution mode is a combination of the following four components:
- preemption
@ -242,11 +247,12 @@ the task will execute at interrupt level n.
The set of default modes may be selected by specifying the
``RTEMS_DEFAULT_MODES`` constant.
Accessing Task Arguments
------------------------
.. index:: task arguments
.. index:: task prototype
Accessing Task Arguments
------------------------
All RTEMS tasks are invoked with a single argument which is specified when they
are started or restarted. The argument is commonly used to communicate startup
information to the task. The simplest manner in which to define a task which
@ -263,9 +269,10 @@ accesses it argument is:
Application tasks requiring more information may view this single argument as
an index into an array of parameter blocks.
.. index:: floating point
Floating Point Considerations
-----------------------------
.. index:: floating point
Creating a task with the ``RTEMS_FLOATING_POINT`` attribute flag results in
additional memory being allocated for the TCB to store the state of the numeric
@ -313,9 +320,10 @@ consequence of a ``RTEMS_NO_FLOATING_POINT`` task attempting to access the
floating point unit is CPU dependent but will generally result in an exception
condition.
.. index:: task attributes, building
Building a Task Attribute Set
-----------------------------
.. index:: task attributes, building
In general, an attribute set is built by a bitwise OR of the desired
components. The set of valid task attribute components is listed below:
@ -347,9 +355,10 @@ attribute_set parameter can be set to ``RTEMS_FLOATING_POINT`` because
and used the numeric coprocessor, then the attribute_set parameter would be
``RTEMS_GLOBAL | RTEMS_FLOATING_POINT``.
.. index:: task mode, building
Building a Mode and Mask
------------------------
.. index:: task mode, building
In general, a mode and its corresponding mask is built by a bitwise OR of the
desired components. The set of valid mode constants and each mode's
@ -547,12 +556,12 @@ It is important to note that the ``cpuset`` is not validated until the
``rtems_task_set_affinity`` call is made. At that point, it is validated
against the current system configuration.
Transition Advice for Obsolete Notepads
---------------------------------------
.. index:: rtems_task_get_note
.. index:: rtems_task_set_note
Transition Advice for Obsolete Notepads
---------------------------------------
Task notepads and the associated directives :ref:`rtems_task_get_note` and
:ref:`rtems_task_set_note` were removed in RTEMS 5.1. These were never
thread-safe to access and subject to conflicting use of the notepad index by
@ -564,13 +573,13 @@ over the key (e.g. notepad index) selection. For most applications, POSIX Keys
should be used. These are available in all RTEMS build configurations. It is
also possible that thread-local storage (TLS) is an option for some use cases.
Transition Advice for Obsolete Task Variables
---------------------------------------------
.. index:: rtems_task_variable_add
.. index:: rtems_task_variable_get
.. index:: rtems_task_variable_delete
Transition Advice for Obsolete Task Variables
---------------------------------------------
Task notepads and the associated directives :ref:`rtems_task_variable_add`,
:ref:`rtems_task_variable_get` and :ref:`rtems_task_variable_delete` were
removed in RTEMS 5.1. Task variables must be replaced by POSIX Keys or
@ -590,11 +599,11 @@ related constants, usage, and status codes.
\clearpage
.. _rtems_task_create:
.. index:: create a task
.. index:: rtems_task_create
TASK_CREATE - Create a task
---------------------------
.. index:: create a task
.. index:: rtems_task_create
CALLING SEQUENCE:
.. code-block:: c
@ -735,11 +744,11 @@ NOTES:
\clearpage
.. _rtems_task_ident:
.. index:: get ID of a task
.. index:: rtems_task_ident
TASK_IDENT - Get ID of a task
-----------------------------
.. index:: get ID of a task
.. index:: rtems_task_ident
CALLING SEQUENCE:
.. code-block:: c
@ -789,11 +798,11 @@ NOTES:
\clearpage
.. _rtems_task_self:
.. index:: obtain ID of caller
.. index:: rtems_task_self
TASK_SELF - Obtain ID of caller
-------------------------------
.. index:: obtain ID of caller
.. index:: rtems_task_self
CALLING SEQUENCE:
.. code-block:: c
@ -815,11 +824,11 @@ NOTES:
\clearpage
.. _rtems_task_start:
.. index:: starting a task
.. index:: rtems_task_start
TASK_START - Start a task
-------------------------
.. index:: starting a task
.. index:: rtems_task_start
CALLING SEQUENCE:
.. code-block:: c
@ -869,11 +878,11 @@ NOTES:
\clearpage
.. _rtems_task_restart:
.. index:: restarting a task
.. index:: rtems_task_restart
TASK_RESTART - Restart a task
-----------------------------
.. index:: restarting a task
.. index:: rtems_task_restart
CALLING SEQUENCE:
.. code-block:: c
@ -931,11 +940,11 @@ NOTES:
\clearpage
.. _rtems_task_delete:
.. index:: deleting a task
.. index:: rtems_task_delete
TASK_DELETE - Delete a task
---------------------------
.. index:: deleting a task
.. index:: rtems_task_delete
CALLING SEQUENCE:
.. code-block:: c
@ -987,11 +996,11 @@ NOTES:
\clearpage
.. _rtems_task_suspend:
.. index:: suspending a task
.. index:: rtems_task_suspend
TASK_SUSPEND - Suspend a task
-----------------------------
.. index:: suspending a task
.. index:: rtems_task_suspend
CALLING SEQUENCE:
.. code-block:: c
@ -1034,11 +1043,11 @@ NOTES:
\clearpage
.. _rtems_task_resume:
.. index:: resuming a task
.. index:: rtems_task_resume
TASK_RESUME - Resume a task
---------------------------
.. index:: resuming a task
.. index:: rtems_task_resume
CALLING SEQUENCE:
.. code-block:: c
@ -1079,11 +1088,11 @@ NOTES:
\clearpage
.. _rtems_task_is_suspended:
.. index:: is task suspended
.. index:: rtems_task_is_suspended
TASK_IS_SUSPENDED - Determine if a task is Suspended
----------------------------------------------------
.. index:: is task suspended
.. index:: rtems_task_is_suspended
CALLING SEQUENCE:
.. code-block:: c
@ -1117,15 +1126,15 @@ NOTES:
\clearpage
.. _rtems_task_set_priority:
TASK_SET_PRIORITY - Set task priority
-------------------------------------
.. index:: rtems_task_set_priority
.. index:: current task priority
.. index:: set task priority
.. index:: get task priority
.. index:: obtain task priority
TASK_SET_PRIORITY - Set task priority
-------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -1181,14 +1190,14 @@ NOTES:
\clearpage
.. _rtems_task_get_priority:
TASK_GET_PRIORITY - Get task priority
-------------------------------------
.. index:: rtems_task_get_priority
.. index:: current task priority
.. index:: get task priority
.. index:: obtain task priority
TASK_GET_PRIORITY - Get task priority
-------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -1230,9 +1239,6 @@ NOTES:
\clearpage
.. _rtems_task_mode:
TASK_MODE - Change the current task mode
----------------------------------------
.. index:: current task mode
.. index:: set task mode
.. index:: get task mode
@ -1241,6 +1247,9 @@ TASK_MODE - Change the current task mode
.. index:: obtain task mode
.. index:: rtems_task_mode
TASK_MODE - Change the current task mode
----------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -1309,13 +1318,13 @@ NOTES:
\clearpage
.. _rtems_task_wake_after:
TASK_WAKE_AFTER - Wake up after interval
----------------------------------------
.. index:: delay a task for an interval
.. index:: wake up after an interval
.. index:: rtems_task_wake_after
TASK_WAKE_AFTER - Wake up after interval
----------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -1352,13 +1361,13 @@ NOTES:
\clearpage
.. _rtems_task_wake_when:
TASK_WAKE_WHEN - Wake up when specified
---------------------------------------
.. index:: delay a task until a wall time
.. index:: wake up at a wall time
.. index:: rtems_task_wake_when
TASK_WAKE_WHEN - Wake up when specified
---------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -1608,11 +1617,11 @@ NOTES:
\clearpage
.. _rtems_task_iterate:
.. index:: iterate over all threads
.. index:: rtems_task_iterate
TASK_ITERATE - Iterate Over Tasks
---------------------------------
.. index:: iterate over all threads
.. index:: rtems_task_iterate
CALLING SEQUENCE:
.. code-block:: c
@ -1650,10 +1659,10 @@ Deprecated and Removed Directives
\clearpage
.. _rtems_iterate_over_all_threads:
.. index:: rtems_iterate_over_all_threads
ITERATE_OVER_ALL_THREADS - Iterate Over Tasks
---------------------------------------------
.. index:: rtems_iterate_over_all_threads
.. warning::
@ -1689,11 +1698,11 @@ NOTES:
\clearpage
.. _rtems_task_get_note:
.. index:: get task notepad entry
.. index:: rtems_task_get_note
TASK_GET_NOTE - Get task notepad entry
--------------------------------------
.. index:: get task notepad entry
.. index:: rtems_task_get_note
.. warning::
@ -1742,11 +1751,11 @@ NOTES:
\clearpage
.. _rtems_task_set_note:
.. index:: set task notepad entry
.. index:: rtems_task_set_note
TASK_SET_NOTE - Set task notepad entry
--------------------------------------
.. index:: set task notepad entry
.. index:: rtems_task_set_note
.. warning::
@ -1794,14 +1803,14 @@ NOTES:
\clearpage
.. _rtems_task_variable_add:
TASK_VARIABLE_ADD - Associate per task variable
-----------------------------------------------
.. index:: per-task variable
.. index:: task private variable
.. index:: task private data
.. index:: rtems_task_variable_add
TASK_VARIABLE_ADD - Associate per task variable
-----------------------------------------------
.. warning::
This directive was removed in RTEMS 5.1.
@ -1857,13 +1866,13 @@ NOTES:
\clearpage
.. _rtems_task_variable_get:
TASK_VARIABLE_GET - Obtain value of a per task variable
-------------------------------------------------------
.. index:: get per-task variable
.. index:: obtain per-task variable
.. index:: rtems_task_variable_get
TASK_VARIABLE_GET - Obtain value of a per task variable
-------------------------------------------------------
.. warning::
This directive was removed in RTEMS 5.1.
@ -1914,14 +1923,14 @@ NOTES:
\clearpage
.. _rtems_task_variable_delete:
TASK_VARIABLE_DELETE - Remove per task variable
-----------------------------------------------
.. index:: per-task variable
.. index:: task private variable
.. index:: task private data
.. index:: rtems_task_variable_delete
TASK_VARIABLE_DELETE - Remove per task variable
-----------------------------------------------
.. warning::
This directive was removed in RTEMS 5.1.

48
c-user/timer_manager.rst
View File

@ -4,11 +4,11 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: timers
Timer Manager
*************
.. index:: timers
Introduction
============
@ -84,14 +84,14 @@ service routine finished its work.
The Timer Server is designed to remain blocked until a task-based timer fires.
This reduces the execution overhead of the Timer Server.
.. index:: rtems_timer_service_routine
Timer Service Routines
----------------------
The timer service routine should adhere to C calling conventions and have a
prototype similar to the following:
.. index:: rtems_timer_service_routine
.. code-block:: c
rtems_timer_service_routine user_routine(
@ -195,11 +195,11 @@ related constants, usage, and status codes.
\clearpage
.. _rtems_timer_create:
.. index:: create a timer
.. index:: rtems_timer_create
TIMER_CREATE - Create a timer
-----------------------------
.. index:: create a timer
.. index:: rtems_timer_create
CALLING SEQUENCE:
.. code-block:: c
@ -241,11 +241,11 @@ NOTES:
\clearpage
.. _rtems_timer_ident:
.. index:: obtain the ID of a timer
.. index:: rtems_timer_ident
TIMER_IDENT - Get ID of a timer
-------------------------------
.. index:: obtain the ID of a timer
.. index:: rtems_timer_ident
CALLING SEQUENCE:
.. code-block:: c
@ -281,11 +281,11 @@ NOTES:
\clearpage
.. _rtems_timer_cancel:
.. index:: cancel a timer
.. index:: rtems_timer_cancel
TIMER_CANCEL - Cancel a timer
-----------------------------
.. index:: cancel a timer
.. index:: rtems_timer_cancel
CALLING SEQUENCE:
.. code-block:: c
@ -316,11 +316,11 @@ NOTES:
\clearpage
.. _rtems_timer_delete:
.. index:: delete a timer
.. index:: rtems_timer_delete
TIMER_DELETE - Delete a timer
-----------------------------
.. index:: delete a timer
.. index:: rtems_timer_delete
CALLING SEQUENCE:
.. code-block:: c
@ -355,11 +355,11 @@ NOTES:
\clearpage
.. _rtems_timer_fire_after:
.. index:: fire a timer after an interval
.. index:: rtems_timer_fire_after
TIMER_FIRE_AFTER - Fire timer after interval
--------------------------------------------
.. index:: fire a timer after an interval
.. index:: rtems_timer_fire_after
CALLING SEQUENCE:
.. code-block:: c
@ -399,11 +399,11 @@ NOTES:
\clearpage
.. _rtems_timer_fire_when:
.. index:: fire a timer at wall time
.. index:: rtems_timer_fire_when
TIMER_FIRE_WHEN - Fire timer when specified
-------------------------------------------
.. index:: fire a timer at wall time
.. index:: rtems_timer_fire_when
CALLING SEQUENCE:
.. code-block:: c
@ -447,11 +447,11 @@ NOTES:
\clearpage
.. _rtems_timer_initiate_server:
.. index:: initiate the Timer Server
.. index:: rtems_timer_initiate_server
TIMER_INITIATE_SERVER - Initiate server for task-based timers
-------------------------------------------------------------
.. index:: initiate the Timer Server
.. index:: rtems_timer_initiate_server
CALLING SEQUENCE:
.. code-block:: c
@ -492,11 +492,11 @@ NOTES:
\clearpage
.. _rtems_timer_server_fire_after:
.. index:: fire task-based a timer after an interval
.. index:: rtems_timer_server_fire_after
TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval
--------------------------------------------------------------
.. index:: fire task-based a timer after an interval
.. index:: rtems_timer_server_fire_after
CALLING SEQUENCE:
.. code-block:: c
@ -540,11 +540,11 @@ NOTES:
\clearpage
.. _rtems_timer_server_fire_when:
.. index:: fire a task-based timer at wall time
.. index:: rtems_timer_server_fire_when
TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified
-------------------------------------------------------------
.. index:: fire a task-based timer at wall time
.. index:: rtems_timer_server_fire_when
CALLING SEQUENCE:
.. code-block:: c
@ -592,11 +592,11 @@ NOTES:
\clearpage
.. _rtems_timer_reset:
.. index:: reset a timer
.. index:: rtems_timer_reset
TIMER_RESET - Reset an interval timer
-------------------------------------
.. index:: reset a timer
.. index:: rtems_timer_reset
CALLING SEQUENCE:
.. code-block:: c

32
c-user/timespec_helpers.rst
View File

@ -4,6 +4,8 @@
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.
.. index:: TImespec Helpers
Timespec Helpers
****************
@ -124,11 +126,11 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_timespec_set:
.. index:: set struct timespec instance
.. index:: rtems_timespec_set
TIMESPEC_SET - Set struct timespec Instance
-------------------------------------------
.. index:: set struct timespec instance
.. index:: rtems_timespec_set
CALLING SEQUENCE:
.. code-block:: c
@ -155,10 +157,10 @@ NOTES:
\clearpage
.. _rtems_timespec_zero:
.. index:: rtems_timespec_zero
TIMESPEC_ZERO - Zero struct timespec Instance
---------------------------------------------
.. index:: rtems_timespec_zero
CALLING SEQUENCE:
.. code-block:: c
@ -182,10 +184,10 @@ NOTES:
\clearpage
.. _rtems_timespec_is_valid:
.. index:: rtems_timespec_is_valid
TIMESPEC_IS_VALID - Check validity of a struct timespec instance
----------------------------------------------------------------
.. index:: rtems_timespec_is_valid
CALLING SEQUENCE:
.. code-block:: c
@ -211,10 +213,10 @@ NOTES:
\clearpage
.. _rtems_timespec_add_to:
.. index:: rtems_timespec_add_to
TIMESPEC_ADD_TO - Add Two struct timespec Instances
---------------------------------------------------
.. index:: rtems_timespec_add_to
CALLING SEQUENCE:
.. code-block:: c
@ -240,10 +242,10 @@ NOTES:
\clearpage
.. _rtems_timespec_subtract:
.. index:: rtems_timespec_subtract
TIMESPEC_SUBTRACT - Subtract Two struct timespec Instances
----------------------------------------------------------
.. index:: rtems_timespec_subtract
CALLING SEQUENCE:
.. code-block:: c
@ -274,10 +276,10 @@ NOTES:
\clearpage
.. _rtems_timespec_divide:
.. index:: rtems_timespec_divide
TIMESPEC_DIVIDE - Divide Two struct timespec Instances
------------------------------------------------------
.. index:: rtems_timespec_divide
CALLING SEQUENCE:
.. code-block:: c
@ -314,10 +316,10 @@ NOTES:
\clearpage
.. _rtems_timespec_divide_by_integer:
.. index:: rtems_timespec_divide_by_integer
TIMESPEC_DIVIDE_BY_INTEGER - Divide a struct timespec Instance by an Integer
----------------------------------------------------------------------------
.. index:: rtems_timespec_divide_by_integer
CALLING SEQUENCE:
.. code-block:: c
@ -345,10 +347,10 @@ NOTES:
\clearpage
.. _rtems_timespec_less_than:
.. index:: rtems_timespec_less_than
TIMESPEC_LESS_THAN - Less than operator
---------------------------------------
.. index:: rtems_timespec_less_than
CALLING SEQUENCE:
.. code-block:: c
@ -375,10 +377,10 @@ NOTES:
\clearpage
.. _rtems_timespec_greater_than:
.. index:: rtems_timespec_greater_than
TIMESPEC_GREATER_THAN - Greater than operator
---------------------------------------------
.. index:: rtems_timespec_greater_than
CALLING SEQUENCE:
.. code-block:: c
@ -403,10 +405,10 @@ NOTES:
\clearpage
.. _rtems_timespec_equal_to:
.. index:: rtems_timespec_equal_to
TIMESPEC_EQUAL_TO - Check equality of timespecs
-----------------------------------------------
.. index:: rtems_timespec_equal_to
CALLING SEQUENCE:
.. code-block:: c
@ -431,10 +433,10 @@ NOTES:
\clearpage
.. _rtems_timespec_get_seconds:
.. index:: rtems_timespec_get_seconds
TIMESPEC_GET_SECONDS - Get Seconds Portion of struct timespec Instance
----------------------------------------------------------------------
.. index:: rtems_timespec_get_seconds
CALLING SEQUENCE:
.. code-block:: c
@ -459,10 +461,10 @@ NOTES:
\clearpage
.. _rtems_timespec_get_nanoseconds:
.. index:: rtems_timespec_get_nanoseconds
TIMESPEC_GET_NANOSECONDS - Get Nanoseconds Portion of the struct timespec Instance
----------------------------------------------------------------------------------
.. index:: rtems_timespec_get_nanoseconds
CALLING SEQUENCE:
.. code-block:: c
@ -487,10 +489,10 @@ NOTES:
\clearpage
.. _rtems_timespec_to_ticks:
.. index:: rtems_timespec_to_ticks
TIMESPEC_TO_TICKS - Convert struct timespec Instance to Ticks
-------------------------------------------------------------
.. index:: rtems_timespec_to_ticks
CALLING SEQUENCE:
.. code-block:: c
@ -514,10 +516,10 @@ NOTES:
\clearpage
.. _rtems_timespec_from_ticks:
.. index:: rtems_timespec_from_ticks
TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation
---------------------------------------------------------------------
.. index:: rtems_timespec_from_ticks
CALLING SEQUENCE:
.. code-block:: c

61
c-user/user_extensions.rst
View File

@ -5,12 +5,11 @@
.. COMMENT: All rights reserved.
.. _User Extensions Manager:
.. index:: user extensions
User Extensions Manager
***********************
.. index:: user extensions
Introduction
============
@ -62,11 +61,12 @@ dynamic memory allocations and object creation/deletion. Some user extensions
are invoked with thread dispatching disabled. The fatal error extension is
invoked in an arbitrary context.
Extension Sets
--------------
.. index:: user extension set
.. index:: rtems_extensions_table
Extension Sets
--------------
User extensions are maintained as a set. All user extensions are optional and
may be `NULL`. Together a set of these user extensions typically performs a
specific functionality such as performance monitoring or debugger support. The
@ -86,9 +86,10 @@ extension set is defined via the following structure.
rtems_task_terminate_extension thread_terminate;
} rtems_extensions_table;
.. index:: TCB extension area
TCB Extension Area
------------------
.. index:: TCB extension area
There is no system-provided storage for the initial extension sets.
@ -169,6 +170,8 @@ installed after the Standard C Library will operate correctly even if they
utilize the C Library because the C Library's thread delete extension is
invoked after that of the other thread delete extensions.
.. index:: rtems_task_create_extension
Thread Create Extension
-----------------------
@ -176,8 +179,6 @@ The thread create extension is invoked during thread creation, for example
via :ref:`rtems_task_create() <rtems_task_create>` or :c:func:`pthread_create`.
The thread create extension is defined as follows.
.. index:: rtems_task_create_extension
.. code-block:: c
typedef bool ( *rtems_task_create_extension )(
@ -202,6 +203,8 @@ must return :c:data:`true`.
The thread create extension is invoked in forward order with thread dispatching
enabled (except during system initialization).
.. index:: rtems_task_start_extension
Thread Start Extension
----------------------
@ -209,8 +212,6 @@ The thread start extension is invoked during a thread start, for example
via :ref:`rtems_task_start() <rtems_task_start>` or :c:func:`pthread_create`.
The thread start extension is defined as follows.
.. index:: rtems_task_start_extension
.. code-block:: c
typedef void ( *rtems_task_start_extension )(
@ -228,6 +229,8 @@ invoked.
The thread start extension is invoked in forward order with thread dispatching
disabled.
.. index:: rtems_task_restart_extension
Thread Restart Extension
------------------------
@ -235,8 +238,6 @@ The thread restart extension is invoked during a thread restart, for example
via :ref:`rtems_task_restart() <rtems_task_start>`.
The thread restart extension is defined as follows.
.. index:: rtems_task_restart_extension
.. code-block:: c
typedef void ( *rtems_task_restart_extension )(
@ -254,6 +255,8 @@ dispatching enabled (except during system initialization). The thread life is
protected. Thread restart and delete requests issued by thread restart
extensions lead to recursion.
.. index:: rtems_task_switch_extension
Thread Switch Extension
-----------------------
@ -261,8 +264,6 @@ The thread switch extension is invoked before the context switch from the
currently executing thread to the heir thread. The thread switch extension is
defined as follows.
.. index:: rtems_task_switch_extension
.. code-block:: c
typedef void ( *rtems_task_switch_extension )(
@ -280,14 +281,14 @@ SMP lock is owned.
The context switches initiated through the multitasking start are not covered
by the thread switch extension.
.. index:: rtems_task_begin_extension
Thread Begin Extension
----------------------
The thread begin extension is invoked during a thread begin before the thread
entry function is called. The thread begin extension is defined as follows.
.. index:: rtems_task_begin_extension
.. code-block:: c
typedef void ( *rtems_task_begin_extension )(
@ -303,14 +304,14 @@ The thread begin extension is invoked in forward order with thread dispatching
enabled. The thread switch extension may be called multiple times for this
thread before the thread begin extension is invoked.
.. index:: rtems_task_exitted_extension
Thread Exitted Extension
------------------------
The thread exitted extension is invoked once the thread entry function returns.
The thread exitted extension is defined as follows.
.. index:: rtems_task_exitted_extension
.. code-block:: c
typedef void ( *rtems_task_exitted_extension )(
@ -322,6 +323,8 @@ thread.
This extension is invoked in forward order with thread dispatching enabled.
.. index:: rtems_task_terminate_extension
Thread Termination Extension
----------------------------
@ -331,8 +334,6 @@ due to calls of :ref:`rtems_task_delete() <rtems_task_delete>`,
:c:func:`pthread_exit`, or :c:func:`pthread_cancel`. The thread termination
extension is defined as follows.
.. index:: rtems_task_terminate_extension
.. code-block:: c
typedef void ( *rtems_task_terminate_extension )(
@ -351,6 +352,8 @@ The thread terminate extension is invoked in reverse order with thread
dispatching enabled. The thread life is protected. Thread restart and delete
requests issued by thread terminate extensions lead to recursion.
.. index:: rtems_task_delete_extension
Thread Delete Extension
-----------------------
@ -358,8 +361,6 @@ The thread delete extension is invoked in case a zombie thread is killed. A
thread becomes a zombie thread after it terminated. The thread delete
extension is defined as follows.
.. index:: rtems_task_delete_extension
.. code-block:: c
typedef void ( *rtems_task_delete_extension )(
@ -383,14 +384,14 @@ must first terminate and this may take some time. The thread delete extension
is invoked by :ref:`rtems_task_create() <rtems_task_create>` or similar as a
result of a lazy garbage collection of zombie threads.
.. index:: rtems_fatal_extension
Fatal Error Extension
---------------------
The fatal error extension is invoked during :ref:`system termination
<Terminate>`. The fatal error extension is defined as follows.
.. index:: rtems_fatal_extension
.. code-block:: c
typedef void( *rtems_fatal_extension )(
@ -424,11 +425,11 @@ sequence, related constants, usage, and status codes.
\clearpage
.. _rtems_extension_create:
.. index:: create an extension set
.. index:: rtems_extension_create
EXTENSION_CREATE - Create a extension set
-----------------------------------------
.. index:: create an extension set
.. index:: rtems_extension_create
CALLING SEQUENCE:
.. code-block:: c
@ -472,13 +473,13 @@ NOTES:
\clearpage
.. _rtems_extension_ident:
EXTENSION_IDENT - Get ID of a extension set
-------------------------------------------
.. index:: get ID of an extension set
.. index:: obtain ID of an extension set
.. index:: rtems_extension_ident
EXTENSION_IDENT - Get ID of a extension set
-------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
@ -513,11 +514,11 @@ NOTES:
\clearpage
.. _rtems_extension_delete:
.. index:: delete an extension set
.. index:: rtems_extension_delete
EXTENSION_DELETE - Delete a extension set
-----------------------------------------
.. index:: delete an extension set
.. index:: rtems_extension_delete
CALLING SEQUENCE:
.. code-block:: c