[PATCH v3] eng: Add register block specification types
Sebastian Huber
sebastian.huber at embedded-brains.de
Fri May 5 08:50:35 UTC 2023
A register block may be used to specify the interface of devices which
contain registers associated with an integer address. 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 "register-block-include" link role.
Registers consists of bit fields. 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.
Update #3715.
---
For examples see:
https://git.rtems.org/rtems-central/tree/spec/dev/grlib/if
v2:
Clarify wording and remove the "register-block-type" attribute.
v3:
Do not mention a linear address space.
eng/req/items.rst | 338 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 338 insertions(+)
diff --git a/eng/req/items.rst b/eng/req/items.rst
index 783800f..59e3d30 100644
--- a/eng/req/items.rst
+++ b/eng/req/items.rst
@@ -99,6 +99,8 @@ The specification item types have the following hierarchy:
* :ref:`SpecTypeInterfaceVariableItemType`
+ * :ref:`SpecTypeRegisterBlockItemType`
+
* :ref:`SpecTypeProxyItemTypes`
* :ref:`SpecTypeRequirementItemType`
@@ -1159,6 +1161,8 @@ This type is refined by the following types:
* :ref:`SpecTypeInterfaceVariableItemType`
+* :ref:`SpecTypeRegisterBlockItemType`
+
.. _SpecTypeApplicationConfigurationGroupItemType:
Application Configuration Group Item Type
@@ -1619,6 +1623,65 @@ depend on configuration options. For example, in one configuration a constant
could be a compile time constant and in another configuration it could be a
read-only object.
+.. _SpecTypeRegisterBlockItemType:
+
+Register Block Item Type
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+This type refines the :ref:`SpecTypeInterfaceItemType` through the
+``interface-type`` attribute if the value is ``register-block``. This set of
+attributes specifies a register block. A register block may 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
+:ref:`SpecTypeRegisterBlockIncludeRole`. Registers consists of bit fields (see
+:ref:`SpecTypeRegisterBitsDefinition`. 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. All explicit attributes shall be
+specified. The explicit attributes for this type are:
+
+brief
+ The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
+
+definition
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeRegisterBlockMemberDefinitionDirective`.
+
+description
+ The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
+
+identifier
+ The attribute value shall be an :ref:`SpecTypeInterfaceGroupIdentifier`.
+
+name
+ The attribute value shall be a string. It shall be the name of the register
+ block.
+
+notes
+ The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
+
+register-block-group
+ The attribute value shall be a string. It shall be the name of the
+ interface group defined for the register block. For the group identifier
+ see the ``identifier`` attribute.
+
+register-block-size
+ The attribute value shall be an :ref:`SpecTypeOptionalInteger`. If the
+ value is present, then it shall be the size of the register block in units
+ of the address space granule.
+
+register-prefix
+ The attribute value shall be an optional string. If the value is present,
+ then it will be used to prefix register bit field names, otherwise the
+ value of the ``name`` attribute will be used.
+
+registers
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeRegisterDefinition`.
+
.. _SpecTypeRequirementItemType:
Requirement Item Type
@@ -3919,6 +3982,12 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceVariableItemType`
+* :ref:`SpecTypeRegisterBitsDefinition`
+
+* :ref:`SpecTypeRegisterBlockItemType`
+
+* :ref:`SpecTypeRegisterDefinition`
+
.. _SpecTypeInterfaceCompoundDefinitionKind:
Interface Compound Definition Kind
@@ -4174,6 +4243,12 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceVariableItemType`
+* :ref:`SpecTypeRegisterBitsDefinition`
+
+* :ref:`SpecTypeRegisterBlockItemType`
+
+* :ref:`SpecTypeRegisterDefinition`
+
.. _SpecTypeInterfaceEnabledByExpression:
Interface Enabled-By Expression
@@ -4223,6 +4298,10 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`
+* :ref:`SpecTypeRegisterBitsDefinitionVariant`
+
+* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant`
+
.. _SpecTypeInterfaceEnumDefinitionKind:
Interface Enum Definition Kind
@@ -4364,6 +4443,8 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceGroupItemType`
+* :ref:`SpecTypeRegisterBlockItemType`
+
.. _SpecTypeInterfaceGroupMembershipLinkRole:
Interface Group Membership Link Role
@@ -4428,6 +4509,8 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceVariableItemType`
+* :ref:`SpecTypeRegisterBlockItemType`
+
.. _SpecTypeInterfaceParameter:
Interface Parameter
@@ -4591,6 +4674,8 @@ This type is refined by the following types:
* :ref:`SpecTypeProxyMemberLinkRole`
+* :ref:`SpecTypeRegisterBlockIncludeRole`
+
* :ref:`SpecTypeRequirementRefinementLinkRole`
* :ref:`SpecTypeRequirementValidationLinkRole`
@@ -4637,6 +4722,8 @@ This type is used by the following types:
* :ref:`SpecTypeNonFunctionalRequirementItemType`
+* :ref:`SpecTypeRegisterDefinition`
+
* :ref:`SpecTypeRequirementItemType`
* :ref:`SpecTypeRequirementValidationItemType`
@@ -4670,6 +4757,21 @@ A value of this type shall be of one of the following variants:
* There may be no value (null).
+.. _SpecTypeOptionalInteger:
+
+Optional Integer
+^^^^^^^^^^^^^^^^
+
+A value of this type shall be of one of the following variants:
+
+* The value may be an integer number.
+
+* There may be no value (null).
+
+This type is used by the following types:
+
+* :ref:`SpecTypeRegisterBlockItemType`
+
.. _SpecTypeOptionalString:
Optional String
@@ -4731,6 +4833,242 @@ This type is used by the following types:
* :ref:`SpecTypeDesignGroupRequirementItemType`
+.. _SpecTypeRegisterBitsDefinition:
+
+Register Bits Definition
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A value of this type shall be of one of the following variants:
+
+* The value may be a set of attributes. This set of attributes specifies a
+ register bit field. Single bits are bit fields with a width of one. All
+ explicit attributes shall be specified. The explicit attributes for this type
+ are:
+
+ brief
+ The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
+
+ description
+ The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
+
+ name
+ The attribute value shall be a string. It shall be the name of the
+ register bit field.
+
+ properties
+ The attribute value shall be a list of strings. 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.
+
+ start
+ The attribute value shall be an integer number. It shall be the start bit
+ of the bit field. Bit ``0`` is the least-significant bit.
+
+ width
+ The attribute value shall be an integer number. It shall be the width in
+ bits of the bit field.
+
+* There may be no value (null).
+
+This type is used by the following types:
+
+* :ref:`SpecTypeRegisterBitsDefinitionDirective`
+
+* :ref:`SpecTypeRegisterBitsDefinitionVariant`
+
+.. _SpecTypeRegisterBitsDefinitionDirective:
+
+Register Bits Definition Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This set of attributes specifies a register bits directive. All explicit
+attributes shall be specified. The explicit attributes for this type are:
+
+default
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeRegisterBitsDefinition`. The default definition will be used
+ if no variant-specific definition is enabled.
+
+variants
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeRegisterBitsDefinitionVariant`.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeRegisterDefinition`
+
+.. _SpecTypeRegisterBitsDefinitionVariant:
+
+Register Bits Definition Variant
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This set of attributes specifies a register bits variant. All explicit
+attributes shall be specified. The explicit attributes for this type are:
+
+definition
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeRegisterBitsDefinition`. The definition will be used if the
+ expression defined by the ``enabled-by`` attribute evaluates to true. In
+ generated header files, the expression is evaluated by the C preprocessor.
+
+enabled-by
+ The attribute value shall be an
+ :ref:`SpecTypeInterfaceEnabledByExpression`.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeRegisterBitsDefinitionDirective`
+
+.. _SpecTypeRegisterBlockIncludeRole:
+
+Register Block Include Role
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
+value is ``register-block-include``. It defines the register block include role
+of links. Links of this role are used to build register blocks using other
+register blocks. All explicit attributes shall be specified. The explicit
+attributes for this type are:
+
+name
+ The attribute value shall be a string. 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
+ :ref:`SpecTypeRegisterList`.
+
+.. _SpecTypeRegisterBlockMemberDefinition:
+
+Register Block Member Definition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A value of this type shall be of one of the following variants:
+
+* The value may be a set of attributes. This set of attributes specifies a
+ register block member definition. All explicit attributes shall be specified.
+ The explicit attributes for this type are:
+
+ count
+ The attribute value shall be an integer number. It shall be the count of
+ registers of the register block member.
+
+ name
+ The attribute value shall be a :ref:`SpecTypeRegisterName`.
+
+* There may be no value (null).
+
+This type is used by the following types:
+
+* :ref:`SpecTypeRegisterBlockMemberDefinitionDirective`
+
+* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant`
+
+.. _SpecTypeRegisterBlockMemberDefinitionDirective:
+
+Register Block Member Definition Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This set of attributes specifies a register block member definition directive.
+All explicit attributes shall be specified. The explicit attributes for this
+type are:
+
+default
+ The attribute value shall be a
+ :ref:`SpecTypeRegisterBlockMemberDefinition`. The default definition will
+ be used if no variant-specific definition is enabled.
+
+offset
+ The attribute value shall be an integer number. It shall be the address of
+ the register block member relative to the base address of the register
+ block.
+
+variants
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeRegisterBlockMemberDefinitionVariant`.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeRegisterBlockItemType`
+
+.. _SpecTypeRegisterBlockMemberDefinitionVariant:
+
+Register Block Member Definition Variant
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This set of attributes specifies a register block member definition variant.
+All explicit attributes shall be specified. The explicit attributes for this
+type are:
+
+definition
+ The attribute value shall be a
+ :ref:`SpecTypeRegisterBlockMemberDefinition`. The definition will be used
+ if the expression defined by the ``enabled-by`` attribute evaluates to
+ true. In generated header files, the expression is evaluated by the C
+ preprocessor.
+
+enabled-by
+ The attribute value shall be an
+ :ref:`SpecTypeInterfaceEnabledByExpression`.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeRegisterBlockMemberDefinitionDirective`
+
+.. _SpecTypeRegisterDefinition:
+
+Register Definition
+^^^^^^^^^^^^^^^^^^^
+
+This set of attributes specifies a register. All explicit attributes shall be
+specified. The explicit attributes for this type are:
+
+bits
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeRegisterBitsDefinitionDirective`.
+
+brief
+ The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
+
+description
+ The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
+
+name
+ The attribute value shall be a string. It shall be the name to identify the
+ register definition. The name shall be unique within the scope of the
+ :ref:`SpecTypeRegisterBlockIncludeRole` links of the item and the
+ :ref:`SpecTypeRegisterList`.
+
+width
+ The attribute value shall be an integer number. It shall be the width of
+ the register in bits.
+
+In addition to the explicit attributes, generic attributes may be specified.
+Each generic attribute key shall be a :ref:`SpecTypeName`. The attribute value
+may have any type.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeRegisterBlockItemType`
+
+.. _SpecTypeRegisterName:
+
+Register Name
+^^^^^^^^^^^^^
+
+The value shall be a string. The name consists either of an identifier, or an
+identifier and an alias. The identifier and alias are separated by a colon
+(``:``). The identifier shall match with the name of a register definition of
+the item (see :ref:`SpecTypeRegisterDefinition`) or the name of a register
+block include of the item (see :ref:`SpecTypeRegisterBlockIncludeRole`). If no
+alias is specified, then the identifier is used for the register block member
+name, otherwise the alias is used. If the register block member names are not
+unique within the item, then a postfix number is appended to the names. The
+number starts with zero for each set of names. The value shall match with the
+regular expression "``^[a-zA-Z_][a-zA-Z0-9_]*(:[a-zA-Z_][a-zA-Z0-9_]*)?$``".
+
+This type is used by the following types:
+
+* :ref:`SpecTypeRegisterBlockMemberDefinition`
+
.. _SpecTypeRequirementRefinementLinkRole:
Requirement Refinement Link Role
--
2.35.3
More information about the devel
mailing list