[rtems-central commit] spec: Reword register block descriptions

[Sebastian Huber]

Module:    rtems-central
Branch:    master
Commit:    d853ba97812ccd9385578511310cfadb186708d6
Changeset: http://git.rtems.org/rtems-central/commit/?id=d853ba97812ccd9385578511310cfadb186708d6

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Fri May  5 14:41:18 2023 +0200

spec: Reword register block descriptions

---

 spec/spec/interface-register-bits.yml              |  9 ++++++---
 .../spec/interface-register-block-include-role.yml |  5 +++--
 .../interface-register-block-member-directive.yml  |  4 ++--
 spec/spec/interface-register-block.yml             | 22 +++++++++++-----------
 spec/spec/interface-register.yml                   |  5 ++++-
 5 files changed, 26 insertions(+), 19 deletions(-)

diff --git a/spec/spec/interface-register-bits.yml b/spec/spec/interface-register-bits.yml
index e428aa81..7205811f 100644
--- a/spec/spec/interface-register-bits.yml
+++ b/spec/spec/interface-register-bits.yml
@@ -11,9 +11,11 @@ spec-info:
   none: null
   dict:
     attributes:
-      access:
+      properties:
         description: |
-          It shall be the list of access attributes.
+          It shall be the list of bit field properties.  Properties are for
+          example if the bit field can be read or written, or an access has
+          side-effects such as clearing a status.
         spec-type: list-str
       brief:
         description: null
@@ -35,7 +37,8 @@ spec-info:
           It shall be the width in bits of the bit field.
         spec-type: int
     description: |
-      This set of attributes specifies register bits.
+      This set of attributes specifies a register bit field.  Single bits are
+      bit fields with a width of one.
     mandatory-attributes: all
 spec-name: Register Bits Definition
 spec-type: interface-register-bits
diff --git a/spec/spec/interface-register-block-include-role.yml b/spec/spec/interface-register-block-include-role.yml
index 3a37f626..3cee4e7f 100644
--- a/spec/spec/interface-register-block-include-role.yml
+++ b/spec/spec/interface-register-block-include-role.yml
@@ -16,8 +16,9 @@ spec-info:
     attributes:
       name:
         description: |
-          It shall be the unique name to identify the included register block
-          within the item.
+          It shall be a name to identify the included register block within the
+          item.  The name shall be unique within the scope of the item links of
+          this role and the ${interface-register-list:/spec-name}.
         spec-type: str
     description: |
       It defines the register block include role of links.  Links of this role
diff --git a/spec/spec/interface-register-block-member-directive.yml b/spec/spec/interface-register-block-member-directive.yml
index 3f661616..bb8f7ba4 100644
--- a/spec/spec/interface-register-block-member-directive.yml
+++ b/spec/spec/interface-register-block-member-directive.yml
@@ -17,8 +17,8 @@ spec-info:
         spec-type: interface-register-block-member
       offset:
         description: |
-          It shall be the offset from the register block begin to the register
-          member in units of the address space granule.
+          It shall be the address of the register block member relative to the
+          base address of the register block.
         spec-type: int
       variants:
         description: null
diff --git a/spec/spec/interface-register-block.yml b/spec/spec/interface-register-block.yml
index c7b68ca6..1b9d2808 100644
--- a/spec/spec/interface-register-block.yml
+++ b/spec/spec/interface-register-block.yml
@@ -54,17 +54,17 @@ spec-info:
         spec-type: optional-str
     description: |
       This set of attributes specifies a register block.  A register block may
-      be used to specify the interface of devices which use a linear address
-      space.  Register blocks consist of register block members specified by
-      the ``definition`` attribute.  Register block members are either
-      instances of registers specified by the ``registers`` attribute or
-      instances of other register blocks specified by links with the
-      ${interface-register-block-include-role:/spec-name}.  Registers consists
-      of bit fields (see ${interface-register-bits:/spec-name}.  The register
-      block members are placed into the address space of the device relative to
-      the base address of the register block.  Register member offests and the
-      register block size are specified in units of the address space granule.
-      The address space granule is usually 8-bits also known as one byte.
+      be used to specify the interface of devices.  Register blocks consist of
+      register block members specified by the ``definition`` attribute.
+      Register block members are either instances of registers specified by the
+      ``registers`` attribute or instances of other register blocks specified
+      by links with the ${interface-register-block-include-role:/spec-name}.
+      Registers consists of bit fields (see
+      ${interface-register-bits:/spec-name}.  The register block members are
+      placed into the address space of the device relative to the base address
+      of the register block.  Register member offests and the register block
+      size are specified in units of the address space granule.  The address
+      space granule is usually 8-bits also known as one byte.
     mandatory-attributes: all
 spec-name: Register Block Item Type
 spec-type: interface-register-block
diff --git a/spec/spec/interface-register.yml b/spec/spec/interface-register.yml
index c02ba160..251150e8 100644
--- a/spec/spec/interface-register.yml
+++ b/spec/spec/interface-register.yml
@@ -21,7 +21,10 @@ spec-info:
         spec-type: interface-description
       name:
         description: |
-          It shall be the unique name to identify the register definition.
+          It shall be the name to identify the register definition.  The name
+          shall be unique within the scope of the
+          ${interface-register-block-include-role:/spec-name} links of the item
+          and the ${interface-register-list:/spec-name}.
         spec-type: str
       width:
         description: |