[PATCH v3] eng: Add register block specification types
Chris Johns
chrisj at rtems.org
Mon May 15 00:13:44 UTC 2023
Hi,
Sorry about the delay, I have been out sick for the last week or so.
I am ok with this to be pushed. I have a minor correction below and a clean up
if you want.
On 5/5/2023 6:50 pm, Sebastian Huber wrote:
> 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
offests -> offsets
> +specified in units of the address space granule. The address space granule is
> +usually 8-bits also known as one byte.
Does "usually" mean using right or usually wrong? I am fine if the reference to
8-bits is removed.
Chris
> 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
More information about the devel
mailing list