[PATCH rtems-docs] c-user: Add Local vs Global to Key Concepts Chapter
Joel Sherrill
joel at rtems.org
Thu Dec 1 18:32:51 UTC 2022
Add multiple new index entries and cite them where RTEMS_LOCAL
and RTEMS_GLOBAL are cited.
Closes #4453.
---
c-user/key_concepts.rst | 78 ++++++++++++++++++++++++++++++++++++-----
c-user/message/directives.rst | 5 +++
c-user/partition/directives.rst | 5 +++
c-user/semaphore/directives.rst | 5 +++
c-user/task/directives.rst | 5 +++
5 files changed, 89 insertions(+), 9 deletions(-)
diff --git a/c-user/key_concepts.rst b/c-user/key_concepts.rst
index e3f4811..f7f62e3 100644
--- a/c-user/key_concepts.rst
+++ b/c-user/key_concepts.rst
@@ -82,21 +82,78 @@ name:
char buffer[10]; /* name assumed to be 10 characters or less */
char *result;
result = rtems_object_get_name( id, sizeof(buffer), buffer );
- printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") );
+ printk( "id=0x%08x name=%s\n", id, ((result) ? result : "no name") );
}
-.. index:: object ID
-.. index:: object ID composition
+.. index:: object id
+.. index:: object id composition
.. index:: rtems_id
-Object IDs
+Object Ids
----------
-An object ID is a unique 32-bit 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 manipulation of object IDs is critical to the performance of some
-RTEMS services.
+an object id is a unique 32-bit 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 manipulation of object ids is critical to the performance of some
+rtems services.
+
+.. index:: rtems_extension_ident()
+.. index:: rtems_barrier_ident()
+.. index:: rtems_port_ident()
+.. index:: rtems_message_queue_ident()
+.. index:: rtems_partition_ident()
+.. index:: rtems_region_ident()
+.. index:: rtems_semaphore_ident()
+.. index:: rtems_task_ident()
+.. index:: rtems_timer_ident()
+
+There are multiple directives with names of the form
+``rtems_ at CLASS@_ident`` that take a name as argument and return the associated
+id if the name is found. The following is the set of name to id services:
+which can look up an object
+
+* ``rtems_extension_ident()``
+* ``rtems_barrier_ident()``
+* ``rtems_port_ident()``
+* ``rtems_message_queue_ident()``
+* ``rtems_partition_ident()``
+* ``rtems_region_ident()``
+* ``rtems_semaphore_ident()``
+* ``rtems_task_ident()``
+* ``rtems_timer_ident()``
+
+Local and Global Scope
+----------------------
+
+.. index:: uniprocesor
+.. index:: multiprocessing
+.. index:: distributed multiprocessing
+.. index:: symmetric multiprocessing (SMP)
+.. index:: local scope
+.. index:: global scope
+.. index:: RTEMS_GLOBAL
+.. index:: RTEMS_LOCAL
+.. index:: RTEMS_GLOBAL
+
+RTEMS supports uniprocessing, distributed multiprocessing, and Symmetric
+Multiprocessing (SMP) configurations. A uniprocessor system includes only
+a single processor in a single node. Distributed multiprocessor systems
+include multiple nodes, each of which is a single processor and is usually
+referred to as just multiprocessor mode for historical reasons. SMP
+systems consist of multiple processors cores in a single node.
+
+In distributed multiprocessing configurations, there are multiple nodes in
+the system and object instances may be visible on just the creating node
+or to all nodes. If visible only to the creating node, this is referred to
+as **local scope** and corresponds to the RTEMS_LOCAL attribute setting
+which is the default. If RTEMS GLOBAL is specified as part of the object
+attributes, then the object instance has **global scope** and the object
+id can be used anywhere in the system to identify that object instance.
+
+In uniprocessing and SMP configurations, there is only one node in
+the system and object instances are locally scoped to that node. Any
+attempt to create with the RTEMS_GLOBAL attribute is an error.
Object ID Format
~~~~~~~~~~~~~~~~
@@ -122,6 +179,9 @@ sixteen bits form an identifier within a particular object type. This
identifier, called the object index, ranges in value from 1 to the maximum
number of objects configured for this object type.
+None of the fields in an object id may be zero except for the special
+case of RTEMS_SELF to indicate the currently running thread.
+
Object ID Description
---------------------
diff --git a/c-user/message/directives.rst b/c-user/message/directives.rst
index 9cb88e2..b71cdc6 100644
--- a/c-user/message/directives.rst
+++ b/c-user/message/directives.rst
@@ -99,6 +99,11 @@ effect. Default attributes can be selected by using the
* the task wait queue discipline used by the message queue:
:c:macro:`RTEMS_FIFO` (default) or :c:macro:`RTEMS_PRIORITY`.
+.. index:: local scope
+.. index:: global scope
+.. index:: RTEMS_GLOBAL
+.. index:: RTEMS_LOCAL
+
The message queue has a local or global **scope** in a multiprocessing network
(this attribute does not refer to SMP systems). The scope is selected by the
mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL`
diff --git a/c-user/partition/directives.rst b/c-user/partition/directives.rst
index 534cfb4..078a728 100644
--- a/c-user/partition/directives.rst
+++ b/c-user/partition/directives.rst
@@ -102,6 +102,11 @@ The partition has a local or global **scope** in a multiprocessing network
mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL`
attributes.
+.. index:: local scope
+.. index:: global scope
+.. index:: RTEMS_GLOBAL
+.. index:: RTEMS_LOCAL
+
* A **local scope** is the default and can be emphasized through the use of the
:c:macro:`RTEMS_LOCAL` attribute. A local partition can be only used by the
node which created it.
diff --git a/c-user/semaphore/directives.rst b/c-user/semaphore/directives.rst
index 5a66ac1..4aa0310 100644
--- a/c-user/semaphore/directives.rst
+++ b/c-user/semaphore/directives.rst
@@ -114,6 +114,11 @@ The semaphore has a local or global **scope** in a multiprocessing network
mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL`
attributes.
+.. index:: local scope
+.. index:: global scope
+.. index:: RTEMS_GLOBAL
+.. index:: RTEMS_LOCAL
+
* A **local scope** is the default and can be emphasized through the use of the
:c:macro:`RTEMS_LOCAL` attribute. A local semaphore can be only used by the
node which created it.
diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst
index 05b035c..a85a541 100644
--- a/c-user/task/directives.rst
+++ b/c-user/task/directives.rst
@@ -194,6 +194,11 @@ attribute does not refer to SMP systems). The scope is selected by the
mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL`
attributes.
+.. index:: local scope
+.. index:: global scope
+.. index:: RTEMS_GLOBAL
+.. index:: RTEMS_LOCAL
+
* A **local scope** is the default and can be emphasized through the use of the
:c:macro:`RTEMS_LOCAL` attribute. A local task can be only used by the node
which created it.
--
1.8.3.1
More information about the devel
mailing list