[PATCH] eng: Add register block specification types

Sat Sep 11 17:53:55 UTC 2021

On Fri, Sep 10, 2021 at 8:41 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> A register block may be used to specify the memory-mapped interface to
> the hardware.  Register blocks consist of register block members.
> Register block members are either instances of registers or instances of
> other register blocks.  Registers consists of bit fields.
>
> Update #3715.
> ---
> For examples see:
>
> https://git.rtems.org/rtems-central/tree/spec/dev/grlib/if
>
>  eng/req/items.rst | 334 ++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 334 insertions(+)
>
> diff --git a/eng/req/items.rst b/eng/req/items.rst
> index 1489f19..be6ab5f 100644
> --- a/eng/req/items.rst
> +++ b/eng/req/items.rst
> @@ -103,6 +103,8 @@ The specification item types have the following hierarchy:
>
>      * :ref:`SpecTypeInterfaceVariableItemType`
>
> +    * :ref:`SpecTypeRegisterBlockItemType`
> +
>    * :ref:`SpecTypeRequirementItemType`
>
>      * :ref:`SpecTypeFunctionalRequirementItemType`
> @@ -1143,6 +1145,8 @@ This type is refined by the following types:
>
>  * :ref:`SpecTypeInterfaceVariableItemType`
>
> +* :ref:`SpecTypeRegisterBlockItemType`
> +
>  .. _SpecTypeApplicationConfigurationGroupItemType:
>
>  Application Configuration Group Item Type
> @@ -1614,6 +1618,67 @@ name
>  notes
>      The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
>
> +.. _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 memory-mapped interface to the hardware.  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`. 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 integer number. It shall be the size in
> +    bytes of the register block.
> +
> +register-block-type
> +    The attribute value shall be a :ref:`SpecTypeRegisterBlockType`.
> +
> +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`.
> +
> +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.
> +
>  .. _SpecTypeRequirementItemType:
>
>  Requirement Item Type
> @@ -3733,6 +3798,12 @@ This type is used by the following types:
>
>  * :ref:`SpecTypeInterfaceVariableItemType`
>
> +* :ref:`SpecTypeRegisterBitsDefinition`
> +
> +* :ref:`SpecTypeRegisterBlockItemType`
> +
> +* :ref:`SpecTypeRegisterDefinition`
> +
>  .. _SpecTypeInterfaceCompoundDefinitionKind:
>
>  Interface Compound Definition Kind
> @@ -3992,6 +4063,12 @@ This type is used by the following types:
>
>  * :ref:`SpecTypeInterfaceVariableItemType`
>
> +* :ref:`SpecTypeRegisterBitsDefinition`
> +
> +* :ref:`SpecTypeRegisterBlockItemType`
> +
> +* :ref:`SpecTypeRegisterDefinition`
> +
>  .. _SpecTypeInterfaceEnabledByExpression:
>
>  Interface Enabled-By Expression
> @@ -4041,6 +4118,10 @@ This type is used by the following types:
>
>  * :ref:`SpecTypeInterfaceFunctionDefinitionVariant`
>
> +* :ref:`SpecTypeRegisterBitsDefinitionVariant`
> +
> +* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant`
> +
>  .. _SpecTypeInterfaceEnumDefinitionKind:
>
>  Interface Enum Definition Kind
> @@ -4182,6 +4263,8 @@ This type is used by the following types:
>
>  * :ref:`SpecTypeInterfaceGroupItemType`
>
> +* :ref:`SpecTypeRegisterBlockItemType`
> +
>  .. _SpecTypeInterfaceGroupMembershipLinkRole:
>
>  Interface Group Membership Link Role
> @@ -4248,6 +4331,8 @@ This type is used by the following types:
>
>  * :ref:`SpecTypeInterfaceVariableItemType`
>
> +* :ref:`SpecTypeRegisterBlockItemType`
> +
>  .. _SpecTypeInterfaceParameter:
>
>  Interface Parameter
> @@ -4423,6 +4508,8 @@ This type is refined by the following types:
>
>  * :ref:`SpecTypePlacementOrderLinkRole`
>
> +* :ref:`SpecTypeRegisterBlockIncludeRole`
> +
>  * :ref:`SpecTypeRequirementRefinementLinkRole`
>
>  * :ref:`SpecTypeRequirementValidationLinkRole`
> @@ -4471,6 +4558,10 @@ This type is used by the following types:
>
>  * :ref:`SpecTypeNonFunctionalRequirementItemType`
>
> +* :ref:`SpecTypeRegisterBlockItemType`
> +
> +* :ref:`SpecTypeRegisterDefinition`
> +
>  * :ref:`SpecTypeRequirementItemType`
>
>  * :ref:`SpecTypeRootItemType`
> @@ -4512,6 +4603,249 @@ value is ``placement-order``. This link role defines the placement order of
>  items in a container item (for example an interface function in a header file
>  or a documentation section).
>
> +.. _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
> +  register bits. All explicit attributes shall be specified. The explicit
> +  attributes for this type are:
> +
> +  access
> +      The attribute value shall be a list of strings. It shall be the list of
> +      access attributes.
> +
> +  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.
> +
> +  start
> +      The attribute value shall be an integer number. It shall be the start bit
> +      of the bit field.
> +
is it necessary to explain anywhere the convention that bit 0 is the
last, least-significant bit of a register?

> +  width
> +      The attribute value shall be an integer number. It shall be the width in
> +      bits of the bit field.
> +
> +* There may by be no value (null).
delete 'by'?

> +
> +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 the unique name to
> +    identify the included register block within the item.
> +
> +.. _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 by be no value (null).
'by'

> +
> +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 offset in
> +    bytes from the register block begin to the register member.
> +
> +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`
> +
> +.. _SpecTypeRegisterBlockType:
> +
> +Register Block Type
> +^^^^^^^^^^^^^^^^^^^
> +
> +The value shall be a string. It specifies the register block type. The value
> +shall be an element of
> +
> +* "``memory``".
> +
> +This type is used by the following types:
> +
> +* :ref:`SpecTypeRegisterBlockItemType`
> +
> +.. _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 unique name to
> +    identify the register definition.
> +
> +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`
> +
>  .. _SpecTypeRequirementReference:
>
>  Requirement Reference
> --
> 2.31.1
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel