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_@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 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel