specware 1.3.4__tar.gz → 1.3.6__tar.gz

{specware-1.3.4 → specware-1.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specware
-Version: 1.3.4
+Version: 1.3.6
 Summary: Provides utilities to specify software.
 Keywords: certification,documentation,markdown,qualification,requirements-management,traceability
 Author: The specware Authors

{specware-1.3.4 → specware-1.3.6}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [project]
 name = "specware"
-version = "1.3.4"
+version = "1.3.6"
 description = "Provides utilities to specify software."
 authors = [
     {name = "The specware Authors", email = "specthings@embedded-brains.de"}

{specware-1.3.4 → specware-1.3.6}/src/specware/__init__.py

@@ -30,6 +30,7 @@ from .contentc import *  # noqa: F401, F403
 from .interface import *  # noqa: F401, F403
 from .interfacedoc import *  # noqa: F401, F403
 from .interfacemapper import *  # noqa: F401, F403
+from .registerblock import *  # noqa: F401, F403
 from .rtems import *  # noqa: F401, F403
 from .transitionmap import *  # noqa: F401, F403
 from .util import *  # noqa: F401, F403

{specware-1.3.4 → specware-1.3.6}/src/specware/cliview.py

@@ -38,9 +38,9 @@ from specitems import (COL_SPAN, CommonMarkContent, Item, ItemCache,
 from specware import (exit_on_config_file_error, open_tree,
                       augment_with_test_case_links, augment_with_test_links,
                       gather_api_items, gather_build_files,
-                      get_register_bits_run, get_register_member_name,
-                      recursive_is_enabled, Transition, TransitionMap,
-                      validate)
+                      get_register_bits_run, get_register_block_layout,
+                      get_register_member_name, recursive_is_enabled,
+                      Transition, TransitionMap, validate)
 
 _DOC_FORMAT = {
     "commonmark": CommonMarkContent,
@@ -56,8 +56,8 @@ _CHILD_ROLES = [
 
 _PARENT_ROLES = [
     "function-implementation", "interface-enumerator",
-    "performance-runtime-limits-provider", "test-timeouts",
-    "verification-provider"
+    "interface-group-member", "performance-runtime-limits-provider",
+    "test-timeouts", "verification-provider"
 ]
 
 
@@ -122,7 +122,8 @@ def _visit_item(item: Item, mapper: ItemMapper, level: int,
 
 def _view_interface_placment(item: Item, mapper: ItemMapper, level: int,
                              validated_filter: str) -> None:
-    for link in item.links_to_children("interface-placement"):
+    for link in itertools.chain(item.links_to_children("interface-placement"),
+                                item.links_to_parents("register-block-host")):
         if _visit_item(link.item, mapper, level, link, validated_filter):
             _view_interface_placment(link.item, mapper, level + 1,
                                      validated_filter)
@@ -507,12 +508,12 @@ def _register_member(place: str, definition: dict[str, Any],
     print(" ".join(parts))
 
 
-def _register_placed(item: Item, includes: dict[str, Item],
+def _register_placed(members: list[Any], includes: dict[str, Item],
                      registers: dict[str,
                                      Any], seen: set[str]) -> tuple[int, int]:
     count = 0
     unclassified = 0
-    for member in item["definition"]:
+    for member in members:
         for definition in _register_definitions(member):
             name, alias = get_register_member_name(definition)
             if name in includes:
@@ -550,13 +551,14 @@ def _register_block(item: Item) -> tuple[int, int]:
     parts.extend(link.item["title"]
                  for link in item.links_to_parents("reference", _any_link))
     print(" ".join(parts))
+    layout = get_register_block_layout(item)
     includes = dict(
-        (link["name"], link.item)
-        for link in item.links_to_parents("register-block-include", _any_link))
+        (part.data["name"], part.data.item) for part in layout.includes)
     registers = dict(
-        (register["name"], register) for register in item["registers"])
+        (part.data["name"], part.data) for part in layout.registers)
     seen: set[str] = set()
-    placed = _register_placed(item, includes, registers, seen)
+    placed = _register_placed([part.data for part in layout.definition],
+                              includes, registers, seen)
     unplaced = _register_unplaced(registers, seen)
     return placed[0] + unplaced[0], placed[1] + unplaced[1]
 
@@ -572,7 +574,12 @@ def _register_blocks(item: Item, blocks: list[Item],
     visited.add(item.uid)
     if item.get("interface-type", None) == "register-block":
         blocks.append(item)
-    for link in item.links_to_children(is_link_enabled=_any_link):
+        return
+    for link in itertools.chain(
+            item.links_to_children(is_link_enabled=_any_link),
+            item.links_to_parents(
+                ["interface-group-member", "register-block-host"],
+                is_link_enabled=_any_link)):
         _register_blocks(link.item, blocks, visited)
 
 

{specware-1.3.4 → specware-1.3.6}/src/specware/contentc.py

@@ -589,7 +589,8 @@ def get_value_params(ctx: ItemGetValueContext) -> Any:
 def forward_declaration(item: Item) -> str:
     """ Gets the forward declare for the item. """
     target = item.parent("interface-target")
-    return f"{target['interface-type']} {target['name']}"
+    kind = target["interface-type"].removeprefix("unspecified-")
+    return f"{kind} {target['name']}"
 
 
 def get_value_forward_declaration(ctx: ItemGetValueContext) -> Any:

{specware-1.3.4 → specware-1.3.6}/src/specware/interface.py

@@ -48,6 +48,11 @@ from .contentc import (CContent, CInclude, DEFAULT_ITEM_MARKER,
                        get_value_forward_declaration, get_value_hash,
                        get_value_header_file, get_value_params,
                        get_value_unspecified_type)
+from .registerblock import (
+    RegisterBlockPart, get_register_block_group, get_interface_groups,
+    get_register_block_host_of_domain, get_register_block_hosts,
+    get_register_block_identifier, get_register_block_layout,
+    get_register_block_prefixes)
 from .rtems import is_export_affected
 from .util import get_register_bits_run, get_register_member_name
 
@@ -57,13 +62,19 @@ _GetLines = Callable[["_Node", Item, str, Any], GenericContent]
 
 def _get_ingroups(item: Item) -> _ItemMap:
     ingroups: _ItemMap = {}
-    for group in item.parents("interface-ingroup"):
+    for group in get_interface_groups(item):
         ingroups[group.uid] = group
     return ingroups
 
 
+def _get_group_identifier(item: Item) -> str:
+    if item.type == "interface/register-block":
+        return get_register_block_identifier(item)
+    return item["identifier"]
+
+
 def _get_group_identifiers(groups: _ItemMap) -> list[str]:
-    return [item["identifier"] for item in groups.values()]
+    return [_get_group_identifier(item) for item in groups.values()]
 
 
 def _get_cite(ctx: ItemGetValueContext) -> str:
@@ -269,6 +280,7 @@ class _RegisterMemberContext(NamedTuple):
     regs: dict[str, Any]
     reg_counts: dict[str, int]
     reg_indices: dict[str, int]
+    parts: list[RegisterBlockPart]
 
 
 def _add_register_padding(content: CContent, new_offset: int, old_offset: int,
@@ -409,11 +421,10 @@ def _get_register_bits_shift(start: int, stride: int, first: int) -> str:
     return f"( {start} {'+' if stride > 0 else '-'} {term} )"
 
 
-def _get_register_bits_prefix(item: Item, reg_name: str) -> str:
+def _get_register_bits_prefix(item: Item, host: Optional[Link],
+                              reg_name: str) -> str:
     """ Get the define prefix of the bit fields of a register. """
-    prefix = item["register-prefix"]
-    if prefix is None:
-        prefix = item["name"]
+    prefix, _ = get_register_block_prefixes(item, host)
     prefix = f"{prefix}_{reg_name}_" if prefix else f"{reg_name}_"
     return prefix.upper()
 
@@ -507,9 +518,13 @@ class _Node:
     """ Nodes of a header file. """
 
     # pylint: disable=too-many-instance-attributes
-    def __init__(self, header_file: "_HeaderFile", item: Item):
+    def __init__(self,
+                 header_file: "_HeaderFile",
+                 item: Item,
+                 host: Optional[Link] = None):
         self.header_file = header_file
         self.item = item
+        self.host = host
         self.ingroups = _get_ingroups(item)
         self.dependents: set[_Node] = set()
         self.depends_on: set[_Node] = set()
@@ -580,22 +595,17 @@ class _Node:
     def generate_enum(self) -> None:
         """ Generate an enum. """
         with self._enum_struct_or_union():
-            enumerators: list[CContent] = []
-            for parent in self.item.parents("interface-enumerator"):
-                enumerator = self._get_description(parent, {})
-                enumerator.append(
+            parents = list(self.item.parents("interface-enumerator"))
+            for index, parent in enumerate(parents):
+                if index > 0:
+                    self.content.append("")
+                self.content.append(self._get_description(parent, {}))
+                get_lines = _Node._get_enumerator_definition
+                if index < len(parents) - 1:
+                    get_lines = _Node._get_enumerator_definition_comma
+                self.content.append(
                     _add_definition(self, parent, "definition",
-                                    parent["definition"],
-                                    _Node._get_enumerator_definition))
-                enumerators.append(enumerator)
-            for enumerator in enumerators[0:-1]:
-                enumerator.last += ","
-                enumerator.append("")
-                self.content.append(enumerator)
-            try:
-                self.content.append(enumerators[-1])
-            except IndexError:
-                pass
+                                    parent["definition"], get_lines))
 
     def generate_define(self) -> None:
         """ Generate a define. """
@@ -623,10 +633,16 @@ class _Node:
         """ Generate a macro. """
         self._add_generic_definition(_Node._get_macro_definition)
 
+    def _new_register_member_context(self) -> _RegisterMemberContext:
+        layout = get_register_block_layout(self.item)
+        return _RegisterMemberContext({}, {}, collections.defaultdict(int),
+                                      collections.defaultdict(int),
+                                      layout.definition)
+
     def _add_register_bits(self, group: str) -> _RegisterMemberContext:
-        ctx = _RegisterMemberContext({}, {}, collections.defaultdict(int),
-                                     collections.defaultdict(int))
-        for index, register in enumerate(self.item["registers"]):
+        ctx = self._new_register_member_context()
+        for part in get_register_block_layout(self.item).registers:
+            register = part.data
             name = register["name"]
             group_ident = group + to_camel_case(name)
             width = register["width"]
@@ -636,17 +652,17 @@ class _Node:
                 "type": f"uint{width}_t",
                 "group": group_ident
             }
-            brief = self.substitute_text(register["brief"])
+            brief = self.substitute_text(register["brief"], part.item)
             with self.content.defgroup_block(group_ident, f"{brief} ({name})"):
                 self.content.add_brief_description(
                     "This group contains register bit definitions.")
-                self.content.wrap(self.substitute_text(
-                    register["description"]))
+                self.content.wrap(
+                    self.substitute_text(register["description"], part.item))
                 self.content.add("@{")
             for index_2, bits in enumerate(register["bits"]):
                 self.content.add(
                     _add_definition(
-                        self, self.item, f"registers[{index}]/bits[{index_2}]",
+                        self, part.item, f"{part.prefix}/bits[{index_2}]",
                         bits,
                         functools.partial(_Node._get_register_bits_definition,
                                           reg_name=name,
@@ -656,16 +672,17 @@ class _Node:
 
     def _add_register_block_includes(self,
                                      ctx: _RegisterMemberContext) -> None:
-        for link in self.item.links_to_parents("register-block-include"):
+        for part in get_register_block_layout(self.item).includes:
+            link = part.data
             name = link["name"]
             ctx.regs[name] = {}
             ctx.regs[name]["size"] = link.item["register-block-size"]
             ctx.regs[name]["type"] = link.item["name"]
-            ctx.regs[name]["group"] = link.item["identifier"]
+            ctx.regs[name]["group"] = get_register_block_identifier(link.item)
 
     def _get_register_member_info(self, ctx: _RegisterMemberContext) -> None:
         offset = -1
-        for index, member in enumerate(self.item["definition"]):
+        for index, member in enumerate(part.data for part in ctx.parts):
             assert member["offset"] > offset
             offset = member["offset"]
             default = [member["default"]] if member["default"] else []
@@ -689,13 +706,13 @@ class _Node:
                 self.substitute_text(self.item["brief"]))
             self.content.wrap(self.substitute_text(self.item["description"]))
             self.content.add("@{")
-        for index, member in enumerate(self.item["definition"]):
+        for part in ctx.parts:
             self.content.add(
                 _add_definition(
-                    self, self.item, f"definition[{index}]", member,
+                    self, part.item, part.prefix, part.data,
                     functools.partial(_Node._get_register_define_definition,
                                       ctx=ctx,
-                                      offset=member["offset"])))
+                                      offset=part.data["offset"])))
         self.content.add_close_group()
 
     def _add_register_struct(self, ctx: _RegisterMemberContext,
@@ -708,13 +725,13 @@ class _Node:
         default_padding = min(*ctx.sizes.values(), 8)
         offset = 0
         with self.content.indent():
-            for index, member in enumerate(self.item["definition"]):
-                member_offset = member["offset"]
+            for index, part in enumerate(ctx.parts):
+                member_offset = part.data["offset"]
                 _add_register_padding(self.content, member_offset, offset,
                                       default_padding)
                 self.content.add(
                     _add_definition(
-                        self, self.item, f"definition[{index}]", member,
+                        self, part.item, part.prefix, part.data,
                         functools.partial(
                             _Node._get_register_member_definition, ctx=ctx)))
                 offset = member_offset + ctx.sizes[index]
@@ -729,14 +746,18 @@ class _Node:
         else:
             self._add_register_struct(ctx, size)
 
+    def _add_register_block_dependencies(self) -> None:
+        for part in get_register_block_layout(self.item).includes:
+            parent = part.data.item
+            self.header_file.add_includes(parent)
+            self.header_file.add_dependency(self, parent)
+
     def generate_register_block(self) -> None:
         """ Generate a register block. """
         self.header_file.add_includes(self.item.map("/c/if/uint32_t"))
-        for parent in self.item.parents("register-block-include"):
-            self.header_file.add_includes(parent)
-            self.header_file.add_dependency(self, parent)
-        group = self.item["identifier"]
-        name = self.item["register-block-group"]
+        self._add_register_block_dependencies()
+        group = get_register_block_identifier(self.item, self.host)
+        name = get_register_block_group(self.item, self.host)
         with self.content.defgroup_block(group, name):
             self.content.add_ingroup(_get_group_identifiers(self.ingroups))
             self.content.add_brief_description(
@@ -811,6 +832,11 @@ class _Node:
             return f"{name} = {self.substitute_code(definition, prefix)}"
         return f"{name}"
 
+    def _get_enumerator_definition_comma(self, item: Item, prefix: str,
+                                         definition: Any) -> GenericContent:
+        # The comma ends the enumerator line inside each branch of a variant.
+        return f"{self._get_enumerator_definition(item, prefix, definition)},"
+
     def _get_define_definition(self, item: Item, prefix: str,
                                definition: Any) -> GenericContent:
         name = item["name"]
@@ -865,7 +891,7 @@ class _Node:
                                       definition: Any, reg_name: str,
                                       reg_width: int) -> GenericContent:
         lines = []  # list[str]
-        prefix = _get_register_bits_prefix(self.item, reg_name)
+        prefix = _get_register_bits_prefix(self.item, self.host, reg_name)
         for index, bit in enumerate(definition):
             if index != 0:
                 lines.append("")
@@ -875,7 +901,13 @@ class _Node:
                                          bit))
         return lines
 
-    def _get_register_define_definition(self, item: Item, _prefix: str,
+    def _get_offset_prefix(self) -> str:
+        prefix = self.item["name"]
+        if self.host is not None:
+            prefix = self.host.data.get("prefix", None) or prefix
+        return prefix.upper()
+
+    def _get_register_define_definition(self, _item: Item, _prefix: str,
                                         definition: Any,
                                         ctx: _RegisterMemberContext,
                                         offset: int) -> GenericContent:
@@ -886,7 +918,7 @@ class _Node:
         with content.doxygen_block():
             content.add(f"@brief See @ref {ctx.regs[name]['group']}.")
         content.append(
-            f"#define {item['name'].upper()}_{alias.upper()} {offset:#x}")
+            f"#define {self._get_offset_prefix()}_{alias.upper()} {offset:#x}")
         return content
 
     def _get_register_member_definition(
@@ -1004,7 +1036,7 @@ class _ZephyrNode(_Node):
                                       definition: Any, reg_name: str,
                                       reg_width: int) -> GenericContent:
         lines = []  # list[str]
-        prefix = _get_register_bits_prefix(self.item, reg_name)
+        prefix = _get_register_bits_prefix(self.item, self.host, reg_name)
         for bit in sorted(definition, key=lambda x: x["start"]):
             lines.extend(
                 _get_zephyr_register_bits_lines(
@@ -1013,9 +1045,9 @@ class _ZephyrNode(_Node):
         return lines
 
     def _add_register_bits(self, group: str) -> _RegisterMemberContext:
-        ctx = _RegisterMemberContext({}, {}, collections.defaultdict(int),
-                                     collections.defaultdict(int))
-        for index, register in enumerate(self.item["registers"]):
+        ctx = self._new_register_member_context()
+        for part in get_register_block_layout(self.item).registers:
+            register = part.data
             name = register["name"]
             width = register["width"]
             assert width in [8, 16, 32, 64]
@@ -1024,7 +1056,7 @@ class _ZephyrNode(_Node):
             for index_2, bits in enumerate(register["bits"]):
                 self.content.append(
                     _add_definition(
-                        self, self.item, f"registers[{index}]/bits[{index_2}]",
+                        self, part.item, f"{part.prefix}/bits[{index_2}]",
                         bits,
                         functools.partial(
                             _ZephyrNode._get_register_bits_definition,
@@ -1032,34 +1064,36 @@ class _ZephyrNode(_Node):
                             reg_width=width)))
         return ctx
 
-    def _get_register_define_definition(self, item: Item, _prefix: str,
+    def _get_offset_prefix(self) -> str:
+        _, prefix = get_register_block_prefixes(self.item, self.host)
+        return prefix.upper()
+
+    def _get_register_define_definition(self, _item: Item, _prefix: str,
                                         definition: Any,
                                         ctx: _RegisterMemberContext,
                                         offset: int) -> GenericContent:
         name, alias = get_register_member_name(definition)
-        prefix = item.get("offset-prefix", None)
-        if prefix is None:
-            prefix = item["name"]
-        define = f"#define {prefix.upper()}_{alias.upper()}"
+        define = f"#define {self._get_offset_prefix()}_{alias.upper()}"
         count = definition["count"]
         if count == 1:
             return f"{define} {offset:#x}U"
         return f"{define}(i) ({offset:#x}U + {ctx.regs[name]['size']}U * (i))"
 
     def _add_register_defines(self, ctx: _RegisterMemberContext) -> None:
-        for index, member in enumerate(self.item["definition"]):
+        for part in ctx.parts:
             self.content.append(
                 _add_definition(
-                    self, self.item, f"definition[{index}]", member,
+                    self, part.item, part.prefix, part.data,
                     functools.partial(
                         _ZephyrNode._get_register_define_definition,
                         ctx=ctx,
-                        offset=member["offset"])))
+                        offset=part.data["offset"])))
 
     def _add_register_block_includes(self,
                                      ctx: _RegisterMemberContext) -> None:
         super()._add_register_block_includes(ctx)
-        for link in self.item.links_to_parents("register-block-include"):
+        for part in get_register_block_layout(self.item).includes:
+            link = part.data
             # Register block structures are not typedefed in this style
             ctx.regs[link["name"]]["type"] = f"struct {link.item['name']}"
 
@@ -1089,13 +1123,13 @@ class _ZephyrNode(_Node):
         default_padding = min(*ctx.sizes.values(), 8)
         offset = 0
         with self.content.indent():
-            for index, member in enumerate(self.item["definition"]):
-                member_offset = member["offset"]
+            for index, part in enumerate(ctx.parts):
+                member_offset = part.data["offset"]
                 self._append_register_padding(member_offset, offset,
                                               default_padding)
                 self.content.append(
                     _add_definition(
-                        self, self.item, f"definition[{index}]", member,
+                        self, part.item, part.prefix, part.data,
                         functools.partial(
                             _ZephyrNode._get_register_member_definition,
                             ctx=ctx)))
@@ -1106,19 +1140,17 @@ class _ZephyrNode(_Node):
 
     def generate_register_block(self) -> None:
         domain, size = _get_register_domain_and_size(self.item)
-        self.header_file.add_includes(self.item.map("/zephyr/if/genmask"))
-        for parent in self.item.parents("register-block-include"):
-            self.header_file.add_includes(parent)
-            self.header_file.add_dependency(self, parent)
-        group = self.item["identifier"]
-        name = self.item["register-block-group"]
-        ctx = self._add_register_bits(group)
+        self.header_file.add_includes(
+            self.item.map(self.header_file.register_bit_macros))
+        self._add_register_block_dependencies()
+        ctx = self._add_register_bits("")
         self._add_register_block_includes(ctx)
         self._get_register_member_info(ctx)
         if domain == "memory":
             self.header_file.add_includes(self.item.map("/c/if/uint32_t"))
             self._add_register_struct(ctx, size)
         else:
+            name = get_register_block_group(self.item, self.host)
             self.content.add(f"/* {name} address offsets */")
             self._add_register_defines(ctx)
 
@@ -1173,6 +1205,9 @@ def _merge_enabled_by(options: dict[str, Item], link: Link) -> Any:
     return {"and": [enabled_by, enabled_by_2]}
 
 
+DEFAULT_REGISTER_BIT_MACROS = "/zephyr/kernel/sys-util/if/genmask"
+
+
 class _HeaderFile:
     """ A header file. """
 
@@ -1184,7 +1219,8 @@ class _HeaderFile:
                  context: ContentContext,
                  option_expressions: OptionExpressions,
                  formatter: Optional[ClangFormatter] = None,
-                 item_marker: str = DEFAULT_ITEM_MARKER):
+                 item_marker: str = DEFAULT_ITEM_MARKER,
+                 register_bit_macros: str = DEFAULT_REGISTER_BIT_MACROS):
         # pylint: disable=too-many-arguments
         # pylint: disable=too-many-positional-arguments
         self._item = item
@@ -1197,6 +1233,7 @@ class _HeaderFile:
         self.options = options
         self.enabled = enabled
         self.item_marker = item_marker
+        self.register_bit_macros = register_bit_macros
         self._option_expressions = option_expressions
 
     def option_expression(self, option: str) -> str:
@@ -1204,18 +1241,42 @@ class _HeaderFile:
         return self._option_expressions.get_expression(self._item, option)
 
     def add_includes(self, item: Item) -> None:
-        """ Add the includes of the item to the header file includes. """
+        """
+        Add the includes of the item to the header file includes.
+
+        A register block which header files host adds the host of the domain
+        of this header file.
+        """
         for parent in item.parents("interface-placement"):
             if parent.type in [
                     "interface/header-file",
                     "interface/unspecified-header-file"
             ]:
                 self._includes.append(parent)
+        if get_register_block_hosts(item):
+            self._includes.append(
+                get_register_block_host_of_domain(
+                    item, self._item.parent("interface-placement")).item)
 
     def add_node(self, item: Item) -> None:
         """ Add a node for the item. """
         self._nodes[item.uid] = _Node(self, item)
 
+    def add_hosted_node(self, link: Link) -> None:
+        """ Add a node for the register block of the host link. """
+        item = link.item
+        if item.type != "interface/register-block":
+            raise ValueError(f"header file '{self._item.uid}' hosts "
+                             f"'{item.uid}' which is no register block")
+        if any(True for _ in item.parents("interface-placement")):
+            raise ValueError(f"register block '{item.uid}' has an interface "
+                             "placement and header file "
+                             f"'{self._item.uid}' hosts it")
+        get_register_block_host_of_domain(
+            item, self._item.parent("interface-placement"))
+        node_type = _ZephyrNode if link["style"] == "zephyr" else _Node
+        self._nodes[item.uid] = node_type(self, item, link)
+
     def add_dependency(self, node: _Node, item: Item) -> None:
         """
         Add a dependency from a node to another node identified by an item if
@@ -1231,6 +1292,9 @@ class _HeaderFile:
         for child in self._item.children("interface-placement"):
             self.add_node(child)
             self.content.register_license_and_copyrights_of_item(child)
+        for link in self._item.links_to_parents("register-block-host"):
+            self.add_hosted_node(link)
+            self.content.register_license_and_copyrights_of_item(link.item)
         for node in self._nodes.values():
             node.generate()
 
@@ -1362,7 +1426,8 @@ def _generate_header_file(item: Item, config: dict, options: dict[str, Item],
     header_file = _HEADER_FILE[config.get("style", "default")](
         item, options, config["enabled"], context,
         OptionExpressions(config["option-expressions"]), formatter,
-        config.get("item-marker", DEFAULT_ITEM_MARKER))
+        config.get("item-marker", DEFAULT_ITEM_MARKER),
+        config.get("register-bit-macros", DEFAULT_REGISTER_BIT_MACROS))
     header_file.generate_nodes()
     header_file.finalize()
     header_file.write(domain_path, file_path)

specware-1.3.6/src/specware/registerblock.py

@@ -0,0 +1,300 @@
+# SPDX-License-Identifier: BSD-2-Clause
+""" Provides the placement and the layout of register blocks. """
+
+# Copyright (C) 2026 embedded brains GmbH & Co. KG
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+from typing import Any, NamedTuple, Optional
+
+from specitems import Item, Link
+
+__all__ = [
+    "RegisterBlockLayout", "RegisterBlockPart", "get_group_members",
+    "get_interface_container", "get_interface_groups", "get_interface_members",
+    "get_register_block_base", "get_register_block_group",
+    "get_register_block_host_of_domain", "get_register_block_hosts",
+    "get_register_block_identifier", "get_register_block_layout",
+    "get_register_block_prefixes"
+]
+
+
+def get_register_block_hosts(item: Item) -> list[Link]:
+    """
+    Get the links of the header files which host the register block.
+
+    Each link is a link from the header file to the register block, so
+    ``link.item`` is the header file.  The links are sorted by the UID of the
+    header file.
+    """
+    return sorted(item.links_to_children("register-block-host"),
+                  key=lambda link: link.item.uid)
+
+
+def get_register_block_host_of_domain(item: Item, domain: Item) -> Link:
+    """
+    Get the link of the header file of the domain which hosts the register
+    block.
+
+    Raises:
+        ValueError: No header file or more than one header file of the domain
+            hosts the register block.
+    """
+    hosts = [
+        link for link in get_register_block_hosts(item)
+        if link.item.parent("interface-placement") == domain
+    ]
+    if not hosts:
+        raise ValueError(f"no header file of domain '{domain.uid}' hosts "
+                         f"register block '{item.uid}'")
+    if len(hosts) > 1:
+        raise ValueError(f"more than one header file of domain "
+                         f"'{domain.uid}' hosts register block '{item.uid}': "
+                         f"{', '.join(link.item.uid for link in hosts)}")
+    return hosts[0]
+
+
+def get_interface_members(item: Item) -> list[Item]:
+    """
+    Get the interfaces which the interface container places.
+
+    These are the children of the ``interface-placement`` links and the
+    register blocks of the ``register-block-host`` links of the container.
+    """
+    return list(item.children("interface-placement")) + list(
+        item.parents("register-block-host"))
+
+
+def get_interface_groups(item: Item) -> list[Item]:
+    """
+    Get the interface groups of the interface.
+
+    These are the parents of the ``interface-ingroup`` links of the interface
+    and the groups which link to the interface through the
+    ``interface-group-member`` role.
+
+    Raises:
+        ValueError: A group links to an interface which is no register block.
+    """
+    members = list(item.children("interface-group-member"))
+    if members and item.type != "interface/register-block":
+        raise ValueError(f"group '{members[0].uid}' has the member "
+                         f"'{item.uid}' which is no register block")
+    groups = dict(
+        (group.uid, group) for group in item.parents("interface-ingroup"))
+    groups.update((group.uid, group) for group in members)
+    return list(groups.values())
+
+
+def get_group_members(item: Item) -> list[Item]:
+    """
+    Get the members of the interface group.
+
+    These are the children of the ``interface-ingroup`` links of the group
+    and the parents of its ``interface-group-member`` links.
+    """
+    return list(item.children("interface-ingroup")) + list(
+        item.parents("interface-group-member"))
+
+
+def get_interface_container(item: Item) -> Item:
+    """
+    Get the interface container of the interface.
+
+    The container is the parent of the ``interface-placement`` link.  A
+    register block without such a link resides in the first header file which
+    hosts it.
+
+    Raises:
+        IndexError: The interface resides in no container.
+    """
+    try:
+        return item.parent("interface-placement")
+    except IndexError:
+        hosts = get_register_block_hosts(item)
+        if not hosts:
+            raise
+        return hosts[0].item
+
+
+def _get_block_value(item: Item, host: Optional[Link], key: str) -> Any:
+    if host is not None:
+        value = host.data.get(key, None)
+        if value is not None:
+            return value
+    else:
+        values = set(link.data[key] for link in get_register_block_hosts(item)
+                     if link.data.get(key, None) is not None)
+        if len(values) > 1:
+            raise ValueError(f"the header files which host register block "
+                             f"'{item.uid}' state different values for "
+                             f"'{key}': {', '.join(sorted(values))}")
+        if values:
+            return values.pop()
+    value = item.get(key, None)
+    if value is None:
+        raise ValueError(f"register block '{item.uid}' has no '{key}' and no "
+                         "host link states one")
+    return value
+
+
+def get_register_block_identifier(item: Item,
+                                  host: Optional[Link] = None) -> str:
+    """
+    Get the interface group identifier of the register block.
+
+    The value of the host link takes precedence over the value of the block.
+    Without a host link, the value of the host links of the block takes
+    precedence.
+    """
+    return _get_block_value(item, host, "identifier")
+
+
+def get_register_block_group(item: Item, host: Optional[Link] = None) -> str:
+    """
+    Get the interface group name of the register block.
+
+    The value of the host link takes precedence over the value of the block.
+    Without a host link, the value of the host links of the block takes
+    precedence.
+    """
+    return _get_block_value(item, host, "register-block-group")
+
+
+def get_register_block_prefixes(item: Item,
+                                host: Optional[Link] = None
+                                ) -> tuple[str, str]:
+    """
+    Get the register prefix and the offset prefix of the register block.
+
+    The prefix of the host link replaces both prefixes of the block.  A
+    missing prefix of the block is the name of the block.
+    """
+    if host is not None:
+        prefix = host.data.get("prefix", None)
+        if prefix is not None:
+            return prefix, prefix
+    register_prefix = item["register-prefix"]
+    if register_prefix is None:
+        register_prefix = item["name"]
+    offset_prefix = item.get("offset-prefix", None)
+    if offset_prefix is None:
+        offset_prefix = item["name"]
+    return register_prefix, offset_prefix
+
+
+def get_register_block_base(item: Item) -> Optional[Item]:
+    """
+    Get the base of the register block.
+
+    Raises:
+        ValueError: The block has more than one base.
+    """
+    bases = list(item.parents("register-block-base"))
+    if len(bases) > 1:
+        raise ValueError(f"register block '{item.uid}' has more than one "
+                         "base")
+    return bases[0] if bases else None
+
+
+class RegisterBlockPart(NamedTuple):
+    """
+    Is a register, a member or an include link of a register block layout.
+    """
+    item: Item
+    prefix: str
+    data: Any
+
+
+class RegisterBlockLayout(NamedTuple):
+    """
+    Is the layout of a register block which includes the parts of its bases.
+    """
+    registers: list[RegisterBlockPart]
+    definition: list[RegisterBlockPart]
+    includes: list[RegisterBlockPart]
+
+
+def _own_layout(item: Item) -> RegisterBlockLayout:
+    return RegisterBlockLayout([
+        RegisterBlockPart(item, f"registers[{index}]", register)
+        for index, register in enumerate(item["registers"])
+    ], [
+        RegisterBlockPart(item, f"definition[{index}]", member)
+        for index, member in enumerate(item["definition"])
+    ], [
+        RegisterBlockPart(item, "", link)
+        for link in item.links_to_parents("register-block-include")
+    ])
+
+
+def _derive_layout(item: Item, base: RegisterBlockLayout,
+                   own: RegisterBlockLayout) -> RegisterBlockLayout:
+    include_names = set(part.data["name"] for part in base.includes)
+    for part in own.includes:
+        name = part.data["name"]
+        if name in include_names or any(part_2.data["name"] == name
+                                        for part_2 in base.registers):
+            raise ValueError(f"register block '{item.uid}' includes a "
+                             f"register block named '{name}' which its base "
+                             "defines")
+    registers = list(base.registers)
+    for part in own.registers:
+        name = part.data["name"]
+        if name in include_names:
+            raise ValueError(f"register '{name}' of register block "
+                             f"'{item.uid}' has the name of a register block "
+                             "which its base includes")
+        for index, part_2 in enumerate(registers):
+            if part_2.data["name"] == name:
+                registers[index] = part
+                break
+        else:
+            registers.append(part)
+    members = dict((part.data["offset"], part) for part in base.definition)
+    members.update((part.data["offset"], part) for part in own.definition)
+    return RegisterBlockLayout(registers,
+                               [members[offset] for offset in sorted(members)],
+                               base.includes + own.includes)
+
+
+def _get_layout(item: Item, visited: set[str]) -> RegisterBlockLayout:
+    if item.uid in visited:
+        raise ValueError(f"register block '{item.uid}' is its own base")
+    visited.add(item.uid)
+    own = _own_layout(item)
+    base = get_register_block_base(item)
+    if base is None:
+        return own
+    return _derive_layout(item, _get_layout(base, visited), own)
+
+
+def get_register_block_layout(item: Item) -> RegisterBlockLayout:
+    """
+    Get the layout of the register block.
+
+    A derivative starts with the layout of its base.  A register of the name
+    of a base register replaces the base register.  A member at the offset of
+    a base member replaces the base member.  The derivative adds its other
+    registers, members and includes.
+    """
+    return _get_layout(item, set())

{specware-1.3.4 → specware-1.3.6}/src/specware/rtems.py

@@ -31,6 +31,8 @@ from typing import Any, Callable, Iterable
 from specitems import (EnabledSet, Item, ItemCache, create_unique_link,
                        link_is_enabled, to_iterable)
 
+from .registerblock import get_interface_members
+
 _NOT_PRE_QUALIFIED = frozenset((
     "/acfg/constraint/option-not-pre-qualified",
     "/constraint/constant-not-pre-qualified",
@@ -49,6 +51,10 @@ _ENABLEMENT_ROLES = ("interface-function", "interface-ingroup",
                      "interface-ingroup-hidden", "requirement-refinement",
                      "validation")
 
+# An item is enabled through the items which link to it by these roles.
+_ENABLEMENT_CHILD_ROLES = ("interface-group-member", "register-block-base",
+                           "register-block-host", "register-block-include")
+
 
 def recursive_is_enabled(enabled_set: EnabledSet, item: Item) -> bool:
     """
@@ -58,8 +64,10 @@ def recursive_is_enabled(enabled_set: EnabledSet, item: Item) -> bool:
     if not item.is_enabled(enabled_set):
         return False
     result = True
-    for parent in item.parents(_ENABLEMENT_ROLES,
-                               is_link_enabled=link_is_enabled):
+    for parent in itertools.chain(
+            item.parents(_ENABLEMENT_ROLES, is_link_enabled=link_is_enabled),
+            item.children(_ENABLEMENT_CHILD_ROLES,
+                          is_link_enabled=link_is_enabled)):
         if recursive_is_enabled(enabled_set, parent):
             return True
         result = False
@@ -123,21 +131,25 @@ _CHILD_ROLES = ("requirement-refinement", "interface-ingroup",
 _PARENT_ROLES = ("function-implementation", "interface-enumerator",
                  "performance-runtime-limits")
 
-# WARNING: This role set works only with _visit_tree() which stops the
-# recursion once it sees an item the second time.  It is there to support older
-# versions of the RTEMS specification where not every interface was assigned to
-# an interface group or other group membership roles were used.
-_BACKWARD_COMPATIBLE_CHILD_ROLES = _CHILD_ROLES + ("appl-config-group-member",
-                                                   "interface-placement")
+# Through this role, a group is the child of each of its members.
+_VALIDATION_PARENT_ROLES = _PARENT_ROLES + ("interface-group-member", )
+
+# WARNING: These role sets work only with _visit_tree() which stops the
+# recursion once it sees an item the second time.  The appl-config-group-member
+# role supports older versions of the RTEMS specification which used this group
+# membership role.
+_VISIT_CHILD_ROLES = _CHILD_ROLES + ("appl-config-group-member",
+                                     "interface-placement")
+
+_VISIT_PARENT_ROLES = _VALIDATION_PARENT_ROLES + ("register-block-host", )
 
 
 def _visit_tree(item: Item, related_items: set[Item]) -> None:
     if item in related_items:
         return
     related_items.add(item)
-    for item_2 in itertools.chain(
-            item.children(_BACKWARD_COMPATIBLE_CHILD_ROLES),
-            item.parents(_PARENT_ROLES)):
+    for item_2 in itertools.chain(item.children(_VISIT_CHILD_ROLES),
+                                  item.parents(_VISIT_PARENT_ROLES)):
         _visit_tree(item_2, related_items)
 
 
@@ -158,14 +170,15 @@ _EXPORT_CHILD_ROLES = ("interface-function", "interface-placement",
                        "requirement-disposition", "requirement-refinement",
                        "test-case", "validation")
 
-_EXPORT_PARENT_ROLES = _PARENT_ROLES + ("constraint", "errno",
-                                        "register-block-include")
+_EXPORT_PARENT_ROLES = _PARENT_ROLES + (
+    "constraint", "errno", "register-block-base", "register-block-host",
+    "register-block-include")
 
 # Items reached through the shallow roles contribute to the generated content
 # of the visiting item, however, the items related to them do not.  Expanding
 # them would relate a header file to every item of each included header file
 # and to every member of each interface group.
-_EXPORT_SHALLOW_CHILD_ROLES = ("placement-order", )
+_EXPORT_SHALLOW_CHILD_ROLES = ("interface-group-member", "placement-order")
 
 _EXPORT_SHALLOW_PARENT_ROLES = ("interface-include", "interface-ingroup",
                                 "interface-ingroup-hidden", "interface-target")
@@ -420,8 +433,9 @@ def _validate_tree(item: Item, validator: Callable[[Item, bool], bool],
     validation_dependencies: list[tuple[str, str]] = []
     for index, link in enumerate(
             sorted(
-                itertools.chain(item.links_to_children(_CHILD_ROLES),
-                                item.links_to_parents(_PARENT_ROLES)))):
+                itertools.chain(
+                    item.links_to_children(_CHILD_ROLES),
+                    item.links_to_parents(_VALIDATION_PARENT_ROLES)))):
         item_2 = link.item
         validated = _validate_tree(item_2, validator, order[:-1] +
                                    (order[-1] + index + 1, 0),
@@ -430,7 +444,8 @@ def _validate_tree(item: Item, validator: Callable[[Item, bool], bool],
             role = _VALIDATION_METHOD[item_2.type]
         elif link.role == "requirement-refinement":
             role = "refinement"
-        elif link.role.startswith("interface-ingroup"):
+        elif link.role.startswith("interface-ingroup") or (
+                link.role == "interface-group-member"):
             role = "group member"
         else:
             role = link.role.replace("-", " ")
@@ -445,7 +460,7 @@ def _validate_tree(item: Item, validator: Callable[[Item, bool], bool],
     if type_name in _CONTAINER_TYPE:
         validation_dependencies.extend(
             (item_2.uid, "interface placement")
-            for item_2 in item.children("interface-placement"))
+            for item_2 in get_interface_members(item))
     validated = validator(item, validated)
     item.view["validated"] = validated
     item.view["validation-dependencies"] = sorted(validation_dependencies)
@@ -457,7 +472,7 @@ def _validate_containers(item: Item) -> bool:
     if item.type in _CONTAINER_TYPE:
         # If at least one not validated child exists, then the container is not
         # validated
-        for item_2 in item.children("interface-placement"):
+        for item_2 in get_interface_members(item):
             try:
                 if not item_2.view["validated"]:
                     validated = False
@@ -468,19 +483,20 @@ def _validate_containers(item: Item) -> bool:
                     f"{item.uid} container member "
                     f"{item_2.uid} has no validated status") from err
     for item_2 in itertools.chain(item.children(_CHILD_ROLES),
-                                  item.parents(_PARENT_ROLES)):
+                                  item.parents(_VALIDATION_PARENT_ROLES)):
         validated = _validate_containers(item_2) and validated
     return validated
 
 
-def _fixup_pre_qualified(item: Item, types: list[str],
-                         roles: str | list[str]) -> None:
+def _fixup_pre_qualified(
+        item: Item, types: list[str],
+        get_members: Callable[[Item], Iterable[Item]]) -> None:
     for type_name in types:
         for item_2 in item.cache.items_by_type.get(type_name, []):
             # Count of not pre-qualified (index 0) and pre-qualified (index 1)
             # children
             count = [0, 0]
-            for item_3 in item_2.children(roles):
+            for item_3 in get_members(item_2):
                 count[int(item_3.view["pre-qualified"])] += 1
             # If at least one not pre-qualified child exists and no
             # pre-qualified child exists, then the item is not pre-qualified.
@@ -497,11 +513,13 @@ def validate(root: Item, validator: Callable[[Item, bool], bool]) -> set[Item]:
     related_items: set[Item] = set()
     _validate_tree(root, validator, (0, ), related_items)
     _validate_containers(root)
-    _fixup_pre_qualified(root,
-                         ["interface/appl-config-group", "interface/group"],
-                         ["interface-ingroup", "interface-ingroup-hidden"])
+    _fixup_pre_qualified(
+        root, ["interface/appl-config-group", "interface/group"],
+        lambda item_2: itertools.chain(
+            item_2.children(["interface-ingroup", "interface-ingroup-hidden"]),
+            item_2.parents("interface-group-member")))
     _fixup_pre_qualified(root, ["interface/header-file"],
-                         "interface-placement")
+                         get_interface_members)
     return related_items