Merge pull request #3 from joecrop/access-types

Added control for which access type to use

Author: darsor

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+### Added
+
+- `access_mode` parameter to control whether software or hardware access permissions are used.
+- `read_only` parameter to force all registers/fields to be treated as read-only.
+
 ### Fixed
 
 - Generate self-contained `use` statements that don't rely on the module structure outside the generated code. ([#9](https://github.com/darsor/PeakRDL-rust/issues/9))

crates/peakrdl-rust-build/src/lib.rs

@@ -21,6 +21,15 @@ pub enum Endian {
     Little,
 }
 
+/// Access mode
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum AccessMode {
+    /// Use software access permissions (sw property)
+    Software,
+    /// Use hardware access permissions (hw property)
+    Hardware,
+}
+
 /// Builder for configuring and running the PeakRDL-rust code generator.
 #[derive(Debug)]
 pub struct Generator {
@@ -54,6 +63,11 @@ pub struct Generator {
     /// By default uses the `littleendian` and `bigendian` addrmap properties,
     /// or little endian if not defined.
     word_endian: Option<Endian>,
+    // Access mode for register/field access functions.
+    access_mode: Option<AccessMode>,
+    // Treat all registers and fields as read-only. Write-only registers and
+    // fields are not exposed.
+    read_only: bool,
 }
 
 impl Default for Generator {
@@ -79,6 +93,8 @@ impl Generator {
             fmt: false,
             byte_endian: None,
             word_endian: None,
+            access_mode: None,
+            read_only: false,
         }
     }
 
@@ -174,7 +190,20 @@ impl Generator {
         self
     }
 
+    /// Set the access mode for register/field access functions.
+    pub fn access_mode(&mut self, mode: AccessMode) -> &mut Self {
+        self.access_mode = Some(mode);
+        self
+    }
+
+    /// Set to `true` to treat all registers/fields as read-only.
+    pub fn read_only(&mut self, read_only: bool) -> &mut Self {
+        self.read_only = read_only;
+        self
+    }
+
     #[allow(clippy::missing_errors_doc)]
+    #[allow(clippy::too_many_lines)]
     /// Run the code generator.
     ///
     /// This will:
@@ -282,7 +311,21 @@ impl Generator {
             Some(Endian::Little) => {
                 cmd.args(["--word-endian", "little"]);
             }
-            _ => (),
+            None => (),
+        }
+
+        match self.access_mode {
+            Some(AccessMode::Hardware) => {
+                cmd.args(["--access-mode", "hardware"]);
+            }
+            Some(AccessMode::Software) => {
+                cmd.args(["--access-mode", "software"]);
+            }
+            None => (),
+        }
+
+        if self.read_only {
+            cmd.arg("--read-only");
         }
 
         for file in &self.files {

docs/configuring.rst

@@ -16,6 +16,8 @@ For example:
     fmt = true
     byte_endian = "big"
     word_endian = "little"
+    access_mode = "software"
+    read_only = false
 
 
 .. data:: force
@@ -49,3 +51,24 @@ For example:
     word endianness.
 
     Default: addrmap endianness propery, or ``little`` if not defined
+
+
+.. data:: access_mode
+
+    Controls which access properties are used for register and field access
+    determination.
+
+    Options:
+
+    - ``software`` - Use software read/write access properties (sw property)
+    - ``hardware`` - Use hardware read/write access properties (hw property)
+
+    Default: ``software``
+
+
+.. data:: read_only
+
+    If true, treat all registers and fields as read-only. Write-only registers and
+    fields are not exposed.
+
+    Default: ``false``

docs/examples/Makefile

@@ -7,7 +7,6 @@ $(EXAMPLE_HTML):
 	mkdir -p $(REPO_ROOT)/docs/rust_docs/examples
 	mkdir -p turboencabulator/tests
 	cp $(TEST_SRC)/turboencabulator.rs turboencabulator/tests/
-	sed -i 's/peakrdl_rust_test/turboencabulator/g' turboencabulator/tests/turboencabulator.rs
 	cd turboencabulator && cargo test
 	cd turboencabulator && cargo doc
 	cp -r turboencabulator/target/doc/. $(REPO_ROOT)/docs/rust_docs/examples/

src/peakrdl_rust/__peakrdl__.py

@@ -22,6 +22,8 @@ class Exporter(ExporterSubcommandPlugin):
         "no_fmt": schema.Boolean(),
         "byte_endian": schema.Choice(["big", "little"]),
         "word_endian": schema.Choice(["big", "little"]),
+        "access_mode": schema.Choice(["software", "hardware"]),
+        "read_only": schema.Boolean(),
     }
 
     def add_exporter_arguments(self, arg_group: "argparse._ActionsContainer") -> None:
@@ -63,6 +65,26 @@ def add_exporter_arguments(self, arg_group: "argparse._ActionsContainer") -> Non
             """,
         )
 
+        arg_group.add_argument(
+            "--access-mode",
+            choices=["software", "hardware"],
+            default="software",
+            help="""
+            Which RDL access attribute (hw or sw) to use for register/field
+            access permissions.
+            """,
+        )
+
+        arg_group.add_argument(
+            "--read-only",
+            action="store_true",
+            default=False,
+            help="""
+            Treat all registers and fields as read-only. Write-only registers and
+            fields are not exposed.
+            """,
+        )
+
     def do_export(self, top_node: "AddrmapNode", options: "argparse.Namespace") -> None:
         x = RustExporter()
         x.export(
@@ -72,4 +94,6 @@ def do_export(self, top_node: "AddrmapNode", options: "argparse.Namespace") -> N
             fmt=options.fmt,
             byte_endian=options.byte_endian,
             word_endian=options.word_endian,
+            access_mode=options.access_mode,
+            read_only=options.read_only,
         )

src/peakrdl_rust/component_context.py

@@ -183,13 +183,18 @@ def __init__(
         top_nodes: list[AddrmapNode],
         byte_endian: Literal["Big", "Little"],
         word_endian: Literal["Big", "Little"],
+        access_mode: str = "software",
+        read_only: bool = False,
     ) -> None:
         self.top_nodes = top_nodes
         self.byte_endian: Literal["Big", "Little"] = byte_endian
         self.word_endian: Literal["Big", "Little"] = word_endian
+        self.access_mode = access_mode
+        self.read_only = read_only
         self.top_component_modules: list[str] = []
         self.components: dict[Path, Component] = {}
         self.msg = top_nodes[0].env.msg
+        self.access_mode = access_mode
 
     def run(self) -> None:
         for node in self.top_nodes:
@@ -260,7 +265,7 @@ def enter_addrmap_or_regfile_or_memory(
                 addr_offset = child.address_offset
 
             if isinstance(child, RegNode):
-                if not utils.reg_access(child):
+                if not utils.reg_access(child, self.access_mode, self.read_only):
                     continue
                 registers.append(
                     RegisterInst(
@@ -325,10 +330,10 @@ def enter_addrmap_or_regfile_or_memory(
                 memories=memories,
                 size=node.size,
             )
-        else:
+        else:  # MemNode
             assert len(submaps) == 0
             assert len(memories) == 0
-            if not (access := utils.field_access(node)):
+            if not (access := utils.mem_access(node, self.access_mode, self.read_only)):
                 return WalkerAction.Continue
             memwidth = node.get_property("memwidth")
             primitive_width = 2 ** int(math.ceil(math.log2(memwidth)))
@@ -366,12 +371,19 @@ def enter_Reg(self, node: RegNode) -> Optional[WalkerAction]:
             # already handled
             return WalkerAction.SkipDescendants
 
-        if not (access := utils.reg_access(node)):
+        if not (reg_access := utils.reg_access(node, self.access_mode, self.read_only)):
             return WalkerAction.Continue
 
         reg_reset_val = 0
         fields: list[FieldInst] = []
         for field in node.fields():
+            if not (
+                field_access := utils.field_access(
+                    field, self.access_mode, self.read_only
+                )
+            ):
+                continue
+
             encoding = field.get_property("encode")
             if encoding is not None:
                 encoding_name = (
@@ -429,7 +441,7 @@ def enter_Reg(self, node: RegNode) -> Optional[WalkerAction]:
                     comment=utils.doc_comment(field),
                     inst_name=snakecase(field.inst_name),
                     type_name=pascalcase(field.inst_name),
-                    access=utils.field_access(field),
+                    access=field_access,
                     primitive=primitive,
                     encoding=encoding_name,
                     exhaustive=exhaustive,
@@ -454,7 +466,7 @@ def enter_Reg(self, node: RegNode) -> Optional[WalkerAction]:
             type_name=utils.rust_type_name(node),
             regwidth=node.get_property("regwidth"),
             accesswidth=node.get_property("accesswidth"),
-            access=access,
+            access=reg_access,
             reset_val=reg_reset_val,
             fields=fields,
             has_sw_readable=node.has_sw_readable,

src/peakrdl_rust/design_state.py

@@ -47,6 +47,17 @@ def __init__(self, top_nodes: list[AddrmapNode], path: str, kwargs: Any) -> None
         self.byte_endian: Literal["Big", "Little"] = byte_endian.capitalize()  # type: ignore
         self.word_endian: Literal["Big", "Little"] = word_endian.capitalize()  # type: ignore
 
+        self.access_mode: str
+        self.access_mode = kwargs.pop("access_mode", "software")
+        if self.access_mode not in ("software", "hardware"):
+            raise ValueError(
+                f"Invalid access_mode '{self.access_mode}'. "
+                "Must be one of: 'software', 'hardware'"
+            )
+
+        self.read_only: bool
+        self.read_only = kwargs.pop("read_only", False)
+
         # ------------------------
         # Collect info for export
         # ------------------------
@@ -55,7 +66,11 @@ def __init__(self, top_nodes: list[AddrmapNode], path: str, kwargs: Any) -> None
         self.has_fixedpoint: bool = scanner.has_fixedpoint
 
         component_context = ContextScanner(
-            self.top_nodes, self.byte_endian, self.word_endian
+            self.top_nodes,
+            self.byte_endian,
+            self.word_endian,
+            self.access_mode,
+            self.read_only,
         )
         component_context.run()
         self.top_component_modules: list[str] = component_context.top_component_modules

src/peakrdl_rust/exporter.py

@@ -33,6 +33,13 @@ def export(
         word_endian: Optional[Literal["big", "little"]]
             Ordering of `accesswidth`-sized words within a wide register. Overrides
             the `littleendian` and `bigendian` addrmap properties.
+        access_mode: str
+            Access mode for register/field access functions. One of:
+            - `software` (default): Use software read/write access properties
+            - `hardware`: Use hardware read/write access properties
+        read_only: bool
+            Treat all registers and fields as read-only. Write-only registers and
+            fields are not exposed.
         """
         # If it is the root node, skip to top addrmap
         if isinstance(node, RootNode):

src/peakrdl_rust/utils.py

@@ -170,27 +170,74 @@ def crate_enum_module_path(field: FieldNode, enum: type[UserEnum]) -> list[str]:
         return parent_modules + ["named_types", module_name]
 
 
-def reg_access(node: RegNode) -> Union[str, None]:
-    if node.has_sw_readable:
-        if node.has_sw_writable:
+def reg_access(
+    node: RegNode,
+    access_mode: str = "software",
+    read_only: bool = False,
+) -> Union[str, None]:
+    if access_mode == "hardware":
+        readable = node.has_hw_readable
+        writable = node.has_hw_writable and not read_only
+    else:  # software (default)
+        readable = node.has_sw_readable
+        writable = node.has_sw_writable and not read_only
+
+    if readable:
+        if writable:
             return "RW"
         else:
             return "R"
     else:
-        if node.has_sw_writable:
+        if writable:
             return "W"
         else:
             return None
 
 
-def field_access(node: Union[FieldNode, MemNode]) -> Union[str, None]:
-    if node.is_sw_readable:
-        if node.is_sw_writable:
+def field_access(
+    node: FieldNode,
+    access_mode: str = "software",
+    read_only: bool = False,
+) -> Union[str, None]:
+    if access_mode == "hardware":
+        readable = node.is_hw_readable
+        writable = node.is_hw_writable and not read_only
+    else:  # software (default)
+        readable = node.is_sw_readable
+        writable = node.is_sw_writable and not read_only
+
+    if readable:
+        if writable:
             return "RW"
         else:
             return "R"
     else:
-        if node.is_sw_writable:
+        if writable:
+            return "W"
+        else:
+            return None
+
+
+def mem_access(
+    node: MemNode,
+    access_mode: str = "software",
+    read_only: bool = False,
+) -> Union[str, None]:
+    if access_mode == "hardware":
+        # Assume RW since there's no hw access attribute for memories
+        readable = True
+        writable = not read_only
+    else:  # software (default)
+        readable = node.is_sw_readable
+        writable = node.is_sw_writable and not read_only
+
+    if readable:
+        if writable:
+            return "RW"
+        else:
+            return "R"
+    else:
+        if writable:
             return "W"
         else:
             return None