review tweaks

Author: amykyta3

docs/api/hwio.rst

@@ -5,7 +5,7 @@ HWIO
 
 The PyRAL runtime library provides several built-in HWIO classes that you can use
 
-.. list-table:: Frozen Delights!
+.. list-table::
     :header-rows: 1
 
     *   - Class

docs/index.rst

@@ -80,8 +80,8 @@ Links
 - `Source repository <https://github.com/SystemRDL/PeakRDL-PyRAL>`_
 - `Release Notes <https://github.com/SystemRDL/PeakRDL-PyRAL/releases>`_
 - `Issue tracker <https://github.com/SystemRDL/PeakRDL-PyRAL/issues>`_
-- `PyPi (Exporter) <https://pypi.org/project/peakrdl-pyral>`_
-- `PyPi (Runtime) <https://pypi.org/project/peakrdl-pyral-runtime>`_
+- `PyPI (Exporter) <https://pypi.org/project/peakrdl-pyral>`_
+- `PyPI (Runtime) <https://pypi.org/project/peakrdl-pyral-runtime>`_
 - `SystemRDL Specification <http://accellera.org/downloads/standards/systemrdl>`_
 
 

docs/ug/hier-hwio.rst

@@ -24,16 +24,16 @@ different hierarchical nodes.
     from my_soc_ral import my_soc
 
     # Create each HWIO
+    uio0 = MMapFileHWIO("/dev/uio0")
     uio1 = MMapFileHWIO("/dev/uio1")
     uio2 = MMapFileHWIO("/dev/uio2")
     uio3 = MMapFileHWIO("/dev/uio3")
-    uio4 = MMapFileHWIO("/dev/uio4")
 
     # Create the RAL
     ral = my_soc.get_ral()
 
     # Attach HWIO to the respective components
-    ral.awesome_A.attach_hwio(uio1)
-    ral.awesome_B.attach_hwio(uio2)
-    ral.splendid_X.attach_hwio(uio3)
-    ral.splendid_Y.attach_hwio(uio4)
+    ral.awesome_A.attach_hwio(uio0)
+    ral.awesome_B.attach_hwio(uio1)
+    ral.splendid_X.attach_hwio(uio2)
+    ral.splendid_Y.attach_hwio(uio3)

docs/ug/installing.rst

@@ -16,10 +16,30 @@ use-case, you may not need to install both of them every time.
     The exported RAL requires additional runtime files to be installed on the
     system that will run the RAL & application. This runtime package provides this.
 
-.. todo::
-    Add instructions on how to install the runtime on a device that cannot fetch from pypi
 
-    - pip download command for a specific platform
-    - copy wheels over
-    - install within the device
-    - Mention that installing the runtime as part of the rootfs may be preferred
+Installing the runtime without PyPI
+------------------------------------
+Targets that cannot reach PyPI (embedded devices, air-gapped networks) can still
+install ``peakrdl-pyral-runtime`` from wheels you fetch ahead of time.
+
+On a machine with network access, download the wheel as follows:
+
+.. code-block:: bash
+
+    mkdir wheels
+    python3 -m pip download peakrdl-pyral-runtime -d wheels
+
+Since the runtime is implemented in pure Python, the weel is implicitly
+platform-independent.
+
+Copy the ``wheels/`` directory to the device, then install from disk without
+contacting an index:
+
+.. code-block:: bash
+
+   python3 -m pip install --no-index --find-links=wheels peakrdl-pyral-runtime
+
+
+.. note::
+    For custom OS images, it is often preferable to install the runtime wheel
+    during image build so the package included on the rootfs.

docs/ug/key-concepts.rst

@@ -12,7 +12,7 @@ PeakRDL-PyRAL implements two major abstraction layers: The RAL and HWIO.
 Hardware I/O Abstraction Layer (HWIO)
     The HWIO layer defines how low-level read/write operations are initiated on
     the hardware. A HWIO layer may issue these accesses locally via a direct
-    memory mapping, via a hardware debugger like JTAG, or even remotely though
+    memory mapping, via a hardware debugger like JTAG, or even remotely through
     an SSH or telnet connection. Alternatively it could call read/write operations
     on a bus driver in a simulated environment like cocotb.
 

pkg-runtime/src/peakrdl_pyral_runtime/dbapi.py

@@ -94,10 +94,23 @@ def get_ref_dbapi(self, ref_dbid: int) -> "DBAPI":
         cur.close()
 
         import_path = row["import_path"]
-        # TODO: Make sure import errors result in a helpful error.
-        #   Ensure it tells the user what is wrong
-        ref_module = importlib.import_module(import_path, self.origin_module_name)
-        new_dbapi: DBAPI = ref_module._get_dbapi()
+        try:
+            ref_module = importlib.import_module(import_path, self.origin_module_name)
+        except ImportError as exc:
+            raise ImportError(
+                f"Failed to import grafted PyRAL module '{import_path}' while resolving an "
+                f"external reference from RAL package '{self.origin_module_name}. "
+                "Ensure the module is installed and importable, and that PeakRDL "
+                "--graft-type path provided is correct."
+            ) from exc
+
+        get_dbapi = getattr(ref_module, "_get_dbapi", None)
+        if get_dbapi is None:
+            raise RuntimeError(
+                f"Grafted module '{import_path} (imported for RAL '{self.origin_module_name}) "
+                "does not define _get_dbapi(); expected a PeakRDL-PyRAL generated module."
+            )
+        new_dbapi: DBAPI = get_dbapi()
 
         # Child DBAPIs all share a common HWIO registry. Graft it in
         new_dbapi.hwio_registry = self.hwio_registry

pkg-runtime/src/peakrdl_pyral_runtime/model/base.py

@@ -80,7 +80,7 @@ def _lookup_hwio(self) -> tuple["HWIO", int]:
             return self.parent._lookup_hwio()
 
         # Reached root without finding anything
-        raise LookupError("No HWIF was connected")
+        raise LookupError("No HWIO was connected")
 
     def attach_hwio(self, hwio: "HWIO") -> None:
         """