On Fri, Sep 10, 2021 at 8:41 AM Sebastian Huber <sebastian.hu...@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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
